埋点API

1 如何查看埋点方案

在进行埋点前，需要确定在哪里埋点、埋哪些点等，即需要梳理清楚明确的埋点需求。在QuickTracking平台中将明确的埋点需求称为埋点方案，并为埋点方案设计了规范模板。如下：

在埋点方案中，明确的所需埋点内容有：

1、事件主体：指“谁”触发了这个事件，分为设备ID和账号ID，上报的事件务必具备其中之一。

• 设备ID：Android设备和iOS设备的默认设备ID为应用级别唯一的设备ID，由Quicktracking自动生成：

  • Android9及以下设备：SDK自动采集imei、wifimac、androidid、SN生成设备ID，生成后存入本地，只有卸载应用或者删除应用数据才会重新生成设备ID。

  • Android10级以上设备：SDK自动采集oaid、gaid、androidid、SN生成设备ID，生成后存入本地，只有卸载应用或者删除应用数据才会重新生成设备ID。

  • iOS设备：SDK自动采集openudid生成设备ID，生成后放入keychain中，只有恢复出厂设置或者删除应用数据才会重新生成设备ID。

  • 使用应用的C端用户同意采集idfa和oaid，QuickTracking SDK才会采集，只有QuickTracking app SDK可以采集到oaid、gaid、imei、wifimac、androidid、SN、idfa、idfv。

• 账号ID：客户端用户登录后账号标识，当一个用户在不同的设备进行登录时，设备ID会发生变化，但是账号ID不会发生变化。例如一个用户使用手机和pad分别登录。

2、用户属性：针对账号ID的属性，例如账号ID为“testdemo@111”的用户，“生日”为“1999-02-13”，“会员等级”为“铂金”等。“生日”和“会员”等级就为用户属性。

3、渠道属性：广告投放的属性，例如投放渠道、投放方式、投放内容等。

4、全局属性：在全局设置一次后，每一个事件都会携带的属性

5、页面浏览事件：页面加载时上报的事件（埋点方案中页面编码和事件编码相等的事件，也是标记为蓝色的事件）

6、点击、曝光、自定义事件：客户端用户与客户端发生任意交互时上报的事件。

2 设置设备ID&账号ID

2.1 设备ID设置

SDK 内部默认会采集如下参数。

如果开发者希望针对上表中的某几个设备标识符采集行为做控制，如：不采集或自行实现采集方法。可以实现对应block回调，如下示例：

[QTConfigure customSetIdfaBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetIdfvBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetOpenUdidBlock:^NSString *{
  return @"custom-openudid";
}];
[QTConfigure customSetUtdidBlock:^NSString *{
  return @"custom-utdid";
}];
[QTConfigure customSetMccBlock:^NSString *{
  return @"custom-mcc";
}];
[QTConfigure customSetMncBlock:^NSString *{
  return @"custom-mnc";
}];

注意：请谨慎决定是否实现对应方法，一旦您选择自己实现采集方法，此设备标识的采集工作就由你全权接管了，SDK不会再试图采集此设备标识。SDK能采集到的设备标识越少，对统计数据的准确性和稳定性的负面影响越大。

// 请在设置收数域名之前，调用SDK预初始化函数之前，先调用采集工具类注册函数
// 如果不需要对设备标识采集行为做控制，就不需要实现自定义工具类并注册它
[QTConfigure customSetIdfvBlock:^NSString *{
    return [[UIDevice currentDevice].identifierForVendor UUIDString];
}];
[QTConfigure setCustomDomain:@"您的收数域名" standbyDomain:nil];
[QTConfigure initWithAppKey:@"您的appkey" channel:@"App Store"];

SDK支持自定义设备ID，如果要使用自定义设备ID需要在初始化前（即init前） 设置setCustomDeviceId：接口为有效值（非空）。

+ (void)setCustomDeviceId:(NSString *)devID;

使用示例：

[QTConfigure setCustomDeviceId:@"xxxxxx"];

注意：因该功能在未获取到设备ID时生效，如果本地已存在设备ID，设置后无效。如果本地已获取到设备ID可以通过卸载重装方式验证此功能。

2.2 账号ID设置

1、QT在统计用户时以设备为标准，如果需要统计应用自身的账号，请使用以下接口：

接口函数：

+ (void)profileSignInWithPUID:(NSString *)puid;

参数：

注意：账号ID设置后将被存入本地存储，只有卸载App、清空应用数据或者调用下述的登出接口时，账号ID才会失效，否则每一个事件都将携带账号ID。

示例代码：

[QTMobClick profileSignInWithPUID:@"UserID"];

如果不再需要绑定用户账号，可以调用登出接口，调用后，不再发送账号相关内容。

+ (void)profileSignOff;

示例代码：

[QTMobClick profileSignOff];

2.3 设备ID获取

接口函数：

+ (NSString *)umidString;

示例代码：

NSString *deviceID = [QTConfigure umidString];

3 用户属性上传

1、使用事件编码固定为"$$_user_profile"的自定义事件上传，该事件所携带的事件属性会被作为用户属性放在用户表中。

NSDictionary *dict = @{@"sex" : @"girl", @"age" : @"8"};
[QTMobClick event:@"$$_user_profile" attributes:dict];

请注意：用户属性上传一定要在账号统计调用后

4 渠道属性

4.1 H5链接唤起App

1. 唤起App的URL Scheme中携带这些渠道属性，且属性key务必以“utm_”开头，因为SDK识别的关键字为“utm_”。例如：<URL scheme>?utm_channel=gzh

2. 添加您的 URL Scheme 到项目中，URL Scheme 位于项目设置 target ->选项卡 Info ->URL Types。填入的scheme。在AppDelegate中调用函数[MobClick handleUrl:url]来接收 URL

AppDelegate调用：

- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
 if ([QTMobClick handleUrl:url]) {
 return YES;
 }

 return YES;
}

SceneDelegate调用：

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {

 for (UIOpenURLContext *context in connectionOptions.URLContexts) {
 [QTMobClick handleUrl:context.URL];
 }
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {

 [QTMobClick handleUrl:URLContexts.allObjects.firstObject.URL];
}

PS：如果渠道属性已经与市面上渠道投放公司进行了合作，无法使用utm_开头，可以使用全局属性API将渠道属性进行埋点上报（属性key依然需要以“utm_”开头）。

4.2 H5链接唤起应用市场下载并启动App

该场景下，如果仅是H5链接中携带“utm_”参数，已经无法做到下载App后的启动事件携带“utm_”参数。所以需要进行“H5唤起事件”与“应用激活事件”做关于“IP地址和浏览器UserAgent”的模糊匹配。

1. 当用户在H5中点击「唤起/下载App」的按钮时，上报“应用唤起事件（$$_app_link）”，在事件中需要携带唤起App的appkey和渠道属性。

//示例
aplus_queue.push({
  action:'aplus.recordAppLink',
  arguments:[{
    targetAppKey: '要唤起的应用appKey',  // 必填，要唤起的应用appKey
    custom1: 'custom1', // 选填，自定义参数
    ...
  }]
})

2. App下载后的第一次启动事件“应用激活事件（$$_app_install）”由QT App SDK自动采集上报。

3. QuickTracking系统进行应用唤起事件（$$_app_link）和应用激活事件（$$_app_install）关于“IP地址和浏览器UserAgent”的模糊匹配。您使用时，可以直接在app应用中分析“应用激活（预置）”的渠道属性即可。

4.3 App各应用市场活跃数据统计

在初始化函数中的第二个入参Channel即为设置该应用的应用市场：[QTConfigure initWithAppkey:@"您的appkey" channel:@"App Store"];，在分析中可使用“系统属性-升级渠道”查看。

5 全局属性

注册全局属性后，后续触发的所有事件都将自动包含这些属性，并且这些属性及属性值存入缓存，APP进程结束后清除。在分析数据时，可根据此属性进行查看和筛选。

5.1 注册全局属性

/**
 * 设置全局属性 键值对 
 * 如果和已经存在的全局属性key重复，则更新已有值
 * 如果和已经存在的全局属性key不一致，则插入新的全局属性
 */
+(void) registerGlobalProperty:(NSDictionary *)property;

示例：

NSDictionary *firstPropertyDict = @{
     @"a" : @"1",
     @"b" : @"2"
};
[QTMobClick registerGlobalProperty:firstPropertyDict];//当前globalproperty为a:1和b:2
    
NSDictionary *secondPropertyDict = @{
     @"b" : @"3",
     @"c" : @"4"
};
[QTMobClick registerGlobalProperty:secondPropertyDict];//当前globalproperty为a:1、b:3和c:4

5.2 获取一个全局属性

/**
 * 获取一个全局属性；如果不存在，则返回空。
 */
+(NSString *) getGlobalProperty:(NSString *)propertyName;

5.3 删除一个全局属性

删除一个特定的全局属性，删除后，后续触发的所有事件都不再携带该属性。

/**
 *
 * 删除指定全局属性
 @param key
 */
+(void) unregisterGlobalProperty:(NSString *)propertyName;

5.4 获取所有全局属性

/**
 * 获取所有全局属性；如果不存在，则返回空。
 */
+(NSDictionary *)getGlobalProperties;

5.5 清除所有的全局属性

/**
 * 清空所有全局属性。
 */
+(void)clearGlobalProperties;

6 页面浏览事件API

SDK提供页面自动采集和页面手动采集两种方式上报页面浏览事件，两种方式也可以混用。

6.1 页面自动采集

页面自动采集是hook系统viewWillAppear和viewWillDisappear，获取className 实现。SDK默认不开启页面自动采集，如果需要开启，建议在初始化之前调用。

接口函数：

+ (void)setAutoPageEnabled:(BOOL)value;

示例代码：

//设置为开启页面自动采集
[QTMobClick setAutoPageEnabled:YES];

6.1.1 禁止单个页面的自动上报

如果全局设置了开启页面自动采集，可以通过此接口设置跳过单个页面的自动采集。建议在viewWillAppear最开始调用，如只不统计当前自动页面采集，可以将pageName参数设置成nil。

接口函数：

+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

示例：

#import <QTCommon/UMSpmHybrid.h>

- (void)viewWillAppear:(BOOL)animated
{
  
    [super viewWillAppear:animated];

    //不统计当前class自动页面采集
    [UMSpmHybrid skipMe:[self class] pageName:nil];
}

6.2 页面手动采集

接口函数：

/** 自动页面时长统计, 开始记录某个页面展示时长.
 使用方法：必须配对调用beginLogPageView:和endLogPageView:两个函数来完成自动统计，若只调用某一个函数不会生成有效数据。
 在该页面展示时调用beginLogPageView:，当退出该页面时调用endLogPageView:
 @param pageName 统计的页面名称.
 @return void.
 */
+ (void)beginLogPageView:(NSString *)pageName;

/** 自动页面时长统计, 结束记录某个页面展示时长.
 使用方法：必须配对调用beginLogPageView:和endLogPageView:两个函数来完成自动统计，若只调用某一个函数不会生成有效数据。
 在该页面展示时调用beginLogPageView:，当退出该页面时调用endLogPageView:
 @param pageName 统计的页面名称.
 @return void.
 */
+ (void)endLogPageView:(NSString *)pageName;

参数：

注意：

• 必须配对调用beginLogPageView：和endLogPageView：两个函数来完成自动统计，若只调用某一个函数不会生成有效数据；

• 在该页面展示时调用beginLogPageView：，当退出该页面时调用endLogPageView：。

示例代码：

在ViewController类的viewWillAppear: 和 viewWillDisappear：中配对调用如下方法：

- (void)viewWillAppear:(BOOL)animated
{
 [super viewWillAppear:animated];
 [QTMobClick beginLogPageView:@"Pagename"]; //("Pagename"为页面名称，可自定义)
}

- (void)viewWillDisappear:(BOOL)animated 
{
 [super viewWillDisappear:animated];
 [QTMobClick endLogPageView:@"Pagename"];
}

您也可以根据您自己的业务场景，在viewDidAppear：和viewDidDisappear：等方法中配对调用beginLogPageView：和endLogPageView：两个函数来完成自动统计。

6.2.1 页面属性设置

iOS端页面属性设置接口updatePageProperties，支持给当前页面附加自定义属性。 接口：

/**
 * @brief 更新页面业务参数.
 *
 * @param pageName 页面名称,如Page_Detail
 * @param pProperties 业务参数,kv对
 *
 * @warning 调用说明:必须在viewWillDisappear之前调用
 *
 * 最佳位置:在viewWillDisappear之前调用即可
 */
+(void) updatePageProperties:(NSString *)pageName properties:(NSDictionary *) pProperties;

参数：

请注意：请在调用beginLogPageView之后设置页面属性。

引入头文件：

#import <QTCommon/UMSpm.h>

示例：

[UMSpm updatePageProperties:@"page_home" properties: @{@"page_home_key":@"page_home_val"}];

请注意：页面属性设置只支持页面手动埋点

6.2.2 透传页面属性

此外，QuickTracking SDK还提供透传页面属性埋点接口updateNextPageProperties，支持给下一个页面附加自定义属性。

/**
 * @brief  更新下一个页面业务参数.
 *
 * @param properties 传给下一个页面业务参数,kv对
 *
 * @warning  调用说明：必须在下一个页面pageAppear之前调用,否则会携带错误
 *
 * 最佳位置：必须在下一个页面pageAppear之前调用
 */
+(void) updateNextPageProperties:(NSDictionary *) properties;

参数：

示例：

必须在下一个页面beginLogPageView之前调用。

[UMSpm updateNextPageProperties:@{@"news_next_key":@"news_next_val"}];

请注意：透传页面属性只支持页面手动埋点

7 事件埋点

自定义事件可以用于追踪用户行为，记录行为发生的具体细节。

7.1 事件埋点

接口：

+ (void)event:(NSString *)eventCode; 

+ (void)event:(NSString *)eventCode attributes:(NSDictionary *)attributes;

+ (void)event:(NSString *)eventId pageName:(NSString *)pageName attributes:(NSDictionary *)attributes;

参数说明：

事件上传数量限制：

• 自定义属性key字符串长度上限：1024

• 自定义属性value字符串长度上限：1024*4

• 自定义属性map长度（参数个数）：100 个键值对

• 当自定义属性值value为数组元素时，属性值的数组长度上限：100

• 单条日志报文的总长度限制：2MB

示例1：

统计应用中”转发”事件发生的次数，那么在转发的函数里调用：

[QTMobClick event:@"Forward"];

示例2：

统计应用中“购买”事件发生的次数，以及购买的商品类型及数量，那么在购买的函数里调用：

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"};
[QTMobClick event:@"purchase" attributes:dict];

示例3:

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"};
[QTMobClick event:@"purchase" pageName:@"ViewController" attributes:dict];

8 全埋点（自动埋点）

8.1 全埋点适用范围

SDK适用于iOS 8.0及以上操作系统。

8.2 全埋点接口说明

8.2.1 自动页面采集接口

/** 设置是否自动采集页面, 默认NO(不自动采集).
 @param value 设置为YES, QT SDK 会自动采集页面信息
 */
+ (void)setAutoPageEnabled:(BOOL)value;

示例：

 [QTMobClick setAutoPageEnabled:YES];
 //设置域名
 [QTConfigure setCustomDomain:@"您的收数域名" standbyDomain:nil]; 
 //初始化appkey
 [QTConfigure initWithAppkey:@"您应用的appKey" channel:@"App Store"];

关闭某个页面的自动页面采集

/**
 * @brief                   跳过当前页面统计.
 *
 * @param     PageObject    容器对象（自动获取页面时使用，默认手动可填nil）
 * @param     pageName      页面名称（手动设置页面时使用，当设置自动获取页面时可填nil）
 * @warning                 建议在设置页面之前调用此接口，调用后设置的native页面将不发送数据
 *                          
 */
+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

示例：

[UMSpmHybrid skipMe:self pageName:nil];

8.2.2 开启控件点击数据全埋点

建议在初始化之前调用，默认是关闭

/** 设置是否自动采集点击事件, 默认NO(不自动采集)
 @param value 设置为YES, QT SDK 会将自动采集点击事件
 */
+ (void)setAutoEventEnabled:(BOOL)value;

示例：

 [QTMobClick setAutoEventEnabled:YES];
 //设置域名
 [QTConfigure setCustomDomain:@"您的收数域名" standbyDomain:nil]; 
 //初始化appkey
 [QTConfigure initWithAppkey:@"您应用的appKey" channel:@"App Store"];

支持的控件：

忽略某个容器的点击事件

/**
 * @abstract
 * 忽略某一页面的点击
 *
 * @param PageObject 对应容器
 */
+(void)ignorePageView:(id)PageObject;

例：

// 该方法支持多次调用，对合集进行忽略    
[QTAutoTrack ignorePageView:self];

忽略特定类型控件点击事件的自动采集

通过 ignoreViewType 方法忽略特定类型控件点击事件的自动采集。

/**
 * @abstract
 * 忽略某一类型的点击
 *
 * @param aClass View 对应的 Class
 */
+(void)ignoreViewType:(Class)aclass;

示例：

// 该方法支持多次调用，对合集进行忽略    
[QTAutoTrack ignoreViewType:[UIButton class]];    
[QTAutoTrack ignoreViewType:[UISwitch class]];

忽略特定控件点击事件的自动采集

通过 UMAnalyticsIgnoreView 方法忽略特定控件点击事件的自动采集。

button.UMAnalyticsIgnoreView=YES;

8.2.3 页面设置自定义信息

页面设置自定义编码

通过实现 -(NSString *)getUMPageName 方法，返回一个自定义编码

-(NSString *)getUMPageName
{
   return @"testPageCode";
}

页面设置自定义属性

通过实现 -(NSDictionary *)getUMPageProperties 方法，给页面设置自定义属性

-(NSDictionary *)getUMPageProperties
{
   return @{@"key1":@"val1",@"key2":@"val2"};
}

页面设置来源（page_referrer）信息

通过实现 -(NSString *) getUMScreenUrl 方法，返回一个自定义来源信息

- (NSString *)getUMScreenUrl {
    return @"um//um/page";
}

8.2.4 设置控件点击事件自定义属性

通过该方法，可以对特定控件设置自定义属性，自定义属性可以设置多个键值对，Key和Value都需要是字符串类型。自定义属性和值会包含在此控件全埋点点击事件数据中。

button.UMAnalyticsViewProperties=@{@"key11":@"val11"};

控件设置Event Code

通过该方法，可以对特定控件设置事件编码

button.UMAnalyticsEventCode=@"abcd123";