# iOS SDK API 接口说明 本文档提供API接口的说明，包括： * [启动MTA](https://dtsupport.gitbook.io/mta-docs/app/app_ios/pages/-M7juN6liGSbo8fynq0i#启动MTA) * [统计页面时长](https://dtsupport.gitbook.io/mta-docs/app/app_ios/pages/-M7juN6liGSbo8fynq0i#统计页面时长) * [自定义事件](https://dtsupport.gitbook.io/mta-docs/app/app_ios/pages/-M7juN6liGSbo8fynq0i#自定义事件) * [上报当前缓存的事件](https://dtsupport.gitbook.io/mta-docs/app/app_ios/pages/-M7juN6liGSbo8fynq0i#上报当前缓存的事件) * [使用时长统计](https://dtsupport.gitbook.io/mta-docs/app/app_ios/pages/-M7juN6liGSbo8fynq0i#使用时长统计) * [接口统计](https://dtsupport.gitbook.io/mta-docs/app/app_ios/pages/-M7juN6liGSbo8fynq0i#接口统计) * [用户画像](https://dtsupport.gitbook.io/mta-docs/app/app_ios/pages/-M7juN6liGSbo8fynq0i#用户画像) ## 启动MTA **说明** * 使用统计功能以前，需要先启动MTA。在UIApplicationDelegate的 ``` - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions; ``` 回调中调用 MTA 的 startWithAppkey 方法即可启动MTA。 **接口** ``` 启动MTA - (void)startWithAppkey:(NSString *)appkey; /** 检测版本，并启动MTA。 如果当前MTA的版本小于ver参数，则MTA不启动。否则启动MTA。 */ - (BOOL)startWithAppkey:(NSString *)appkey checkedSdkVersion:(NSString *)ver; ``` **参数说明** * appKey：从网页申请的appKey * ver: 最低允许启动的版本 **示例** ``` * (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [MTA startWithAppkey:@"ABCDEFG"]; } ``` ## 统计页面时长 **说明** * 此接口可以统计某个页面的访问时长 **接口** ``` /** 标记一次页面访问的开始 此接口需要跟trackPageViewEnd配对使用 多次开始以第一次开始的时间为准 */ - (void)trackPageViewBegin:(NSString *)page; /** 标记一起页面访问的开始 并且指定上报方式 此接口需要跟trackPageViewEnd配对使用 多次开始以第一次开始的时间为准 */ - (void)trackPageViewBegin:(NSString *)page appkey:(NSString *)appkey; - (void)trackPageViewEnd:(NSString *)page; /** 标记一起页面访问的结束 并且指定上报方式 此接口需要跟trackPageViewBegin配对使用 多次结束以第一次结束的时间为准 */ - (void)trackPageViewEnd:(NSString *)page appkey:(NSString *)appkey isRealTime:(BOOL)isRealTime; ``` **参数说明** * page：页面ID，ID需要先在MTA前台配置好才能生效 * appkey：若此参数不为nil，则上报到此appkey。否则，上报到startWithAppkey中传入的appkey * isRealTime 是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。 **示例** ``` -(void) viewDidAppear:(BOOL)animated { [MTA trackPageViewBegin:@"Page"]; [super viewDidAppear:animated]; } * (void)viewWillDisappear:(BOOL)animated { [MTA trackPageViewEnd:@"Page"]; [super viewWillDisappear:animated]; } ``` ## 自定义事件 **说明** **自定义事件分为两类：** * 次数统计 * 时长统计 两类自定义事件都可以带 NSDictionary 类型的参数 **接口** ``` /** 上报自定义事件 */ - (void)trackCustomKeyValueEvent:(NSString *)event_id props:(NSDictionary*)kvs; /** 上报自定义事件 并且指定上报方式 */ - (void)trackCustomKeyValueEvent:(NSString *)event_id props:(NSDictionary *)kvs appkey:(NSString *)appkey isRealTime:(BOOL)isRealTime; /** 开始统计自定义时长事件 此接口需要跟trackCustomKeyValueEventEnd配对使用 多次调用以第一次开始时间为准 */ - (void)trackCustomKeyValueEventBegin:(NSString *)event_id props:(NSDictionary *)kvs; /** 开始统计自定义时长事件 并指定上报方式 此接口需要跟trackCustomKeyValueEventEnd配对使用 多次调用以第一次开始时间为准 */ - (void)trackCustomKeyValueEventBegin:(NSString *)event_id props:(NSDictionary *)kvs appkey:(NSString *)appkey; /** 结束统计自定义时长事件 此接口需要跟trackCustomKeyValueEventBegin配对使用 多次调用以第一次结束时间为准 */ - (void)trackCustomKeyValueEventEnd:(NSString *)event_id props:(NSDictionary *)kvs; /** 结束上报自定义时长事件 并指定上报方式 此接口需要跟trackCustomKeyValueEventBegin配对使用 多次调用以第一次结束时间为准 */ - (void)trackCustomKeyValueEventEnd:(NSString *)event_id props:(NSDictionary *)kvs appkey:(NSString *)appkey isRealTime:(BOOL)isRealTime; /** 直接统计自定义时长事件 这个方法用于上报统计好的时长事件 */ - (void)trackCustomKeyValueEventDuration:(float)seconds withEventid:(NSString *)event_id props:(NSDictionary *)kvs; /** 直接上报自定义时长事件 并指定上报方式 这个方法用于上报统计好的时长事件 */ - (void)trackCustomKeyValueEventDuration:(float)seconds withEventid:(NSString *)event_id props:(NSDictionary *)kvs appKey:(NSString *)appkey isRealTime:(BOOL)isRealTime; ``` **参数说明** * event\_id：事件的ID，ID需要先在MTA前台配置好才能生效 * kvs：事件的参数，参数需要先在MTA前台配置好才能生效 * appkey:需要上报的appKey，若传入nil，则上报到启动函数中的appkey * isRealTime:是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。 * seconds:自定义事件的时长，单位秒 **示例** ``` // 次数统计 - (IBAction)clickKVButton:(id)sender { [MTA trackCustomKeyValueEvent:@"KVEvent" props:[NSDictionary dictionaryWithObject:@"Value" forKey:@"Key"]]; } // 时长统计 - (IBAction)clickStartKvButton:(id)sender { [MTA trackCustomKeyValueEventBegin:@"KVEvent" props:[NSDictionary dictionaryWithObject:@"Value" forKey:@"TimeKey"]]; } - (IBAction)clickEndKvButton:(id)sender { [MTA trackCustomKeyValueEventEnd:@"KVEvent" props:[NSDictionary dictionaryWithObject:@"Value" forKey:@"TimeKey"]]; } ``` ## 上报当前缓存的事件 **说明** 若当前有缓存的事件（比如上报策略不为实时上报，或者有事件上报失败）时，调用此方法可以上报缓存的事件 **接口** ``` /** 上报当前缓存的数据 若当前有缓存的事件（比如上报策略不为实时上报，或者有事件上报失败）时 调用此方法可以上报缓存的事件 */ * (void)commitCachedStats:(int32_t)maxStatCount; ``` **参数说明** * maxStatCount：最大上报事件的条数 ## 使用时长统计 **说明** 在UIApplicationDelegate的 ``` - (void)applicationDidBecomeActive:(UIApplication *)application; - (void)applicationWillResignActive:(UIApplication *)application; ``` 的两个回调中，分别添加对应的打点代码，即可上报app的使用时长 **接口** ``` /** 开始统计使用时长 建议在App进入前台时调用 */ - (void)trackActiveBegin; /** 结束统计使用时长 建议在App离开前台时调用 */ - (void)trackActiveEnd; ``` **示例** ``` // 开始打点 - (void)applicationDidBecomeActive:(UIApplication *)application { [MTA trackActiveBegin]; } // 结束打点 - (void)applicationWillResignActive:(UIApplication *)application { [MTA trackActiveEnd]; } ``` ## 接口统计 **说明** 统计应用对某个外部接口（特别是网络类的接口，如连接、登陆、下载等）的调用情况。当开发者用到某个外部接口，可调用该函数将一些指标进行上报，MTA将统计出每个接口的调用情况，并在接口可用性发生变化时进行告警通知；对于调用量很大的接口，也可以采样上报，云监控统计将根据sampling参数在展现页面进行数量的还原。 **接口** ``` /** 接口统计的枚举值 */ typedef enum { /** 接口调用成功 */ MTA_SUCCESS = 0, /** 接口调用失败 */ MTA_FAILURE = 1, /** 接口调用出现逻辑错误 */ MTA_LOGIC_FAILURE = 2 } MTAAppMonitorErrorType; /** 接口统计的数据结构 */ @interface MTAAppMonitorStat : NSObject /** 监控业务接口名 */ @property (nonatomic, strong) NSString *interface; /** 上传请求包量，单位字节 */ @property uint32_t requestPackageSize; /** 接收应答包量，单位字节 */ @property uint32_t responsePackageSize; /** 消耗的时间，单位毫秒 */ @property uint64_t consumedMilliseconds; /** 业务返回的应答码 */ @property int32_t returnCode; /** 业务返回类型 */ @property MTAAppMonitorErrorType resultType; /** 上报采样率，默认0含义为无采样 */ @property uint32_t sampling; @end /** 对网络接口的调用情况进行统计 参数的详细信息请看接口统计数据结构中的相关说明 */ + (void)reportAppMonitorStat:(MTAAppMonitorStat *)stat; /** 对网络接口的调用情况进行统计 并指定上报方式 参数的详细信息请看接口统计数据结构中的相关说明 */ + (void)reportAppMonitorStat:(MTAAppMonitorStat *)stat appkey:(NSString *)appkey isRealTime:(BOOL)isRealTime; ``` **参数说明** * stat：接口统计的数据，详情请看接口统计数据结构的相关说明 * appkey：需要上报的appKey，若传入nil，则上报到启动函数中的appkey * isRealTime：是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。 **示例** ``` -(IBAction) clickNormaltButton:(id)sender{ MTAAppMonitorStat* stat = [[MTAAppMonitorStat alloc] init]; [stat setInterface:@"interface1"]; [stat setRetsultType: SUCCESS]; [MTA reportAppMonitorStat:stat]; } ``` ## 用户画像 **说明** MTA的用户画像功能需要开发者上报用户的QQ号码。上报QQ号码后，MTA后台会自动生成APP的用户画像。 **接口** ``` /** 上报QQ号 上报QQ号以后可以使用MTA提供的用户画像功能 */ - (void)reportQQ:(NSString *)qq; /** 上报QQ号 并指定上报方式 上报QQ号以后可以使用MTA提供的用户画像功能 */ - (void)reportQQ:(NSString *)qq appkey:(NSString *)appkey isRealTime: (BOOL)isRealTime; ``` **参数说明** * qq：QQ 号 * appkey：需要上报的appKey，若传入nil，则上报到启动函数中的appkey * isRealTime：是否实时上报，若传入YES，则忽略全局上报策略实时上报。否则按照全局策略上报。 **示例** ``` * (void)loginSuccess:(BOOL)animated { NSString *qq = @"45284547"; [MTA reportQQ:qq]; } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://dtsupport.gitbook.io/mta-docs/app/app_ios/ios_api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.