埋点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"];

2.2 账号ID设置

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

接口函数：

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

+ (void)profileSignOff;

参数：

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

示例代码：

在统计用户时以设备为标准，若需要统计应用自身的账号，下述两种API任选其一接口：

// PUID：用户账号ID.长度小于64字节
// Provider：账号来源。不能以下划线"_"开头，使用大写字母和数字标识，长度小于32 字节 ; 

[MobClick profileSignInWithPUID:@"UserID"];

//Signoff调用后，不再发送账号内容。
[MobClick profileSignOff];

2.3 设备ID获取

设备ID的获取

可使用下述方法获取：

+ (NSString *)umidString;

3 用户属性上传

1、使用事件编码固定为"$$_user_profile"的自定义事件上传，该事件所携带的事件属性会被作为用户属性放在用户表中。注：用户属性上传一定要在账号统计调用后

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

4 渠道属性

4.1 H5链接唤起App

渠道属性无需进行任何埋点，但是需要唤起小程序或App的URL中携带这些渠道属性，且属性key务必以“utm_”开头，因为SDK识别的关键字为“utm_”。例如：

<URL scheme>?utm_channel=gzh

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

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

该场景下，如果仅是H5链接中携带“utm_”参数，已经无法做到下载App后的启动事件携带“utm_”参数。所以需要进行“H5唤起事件”与“App启动事件”做关于“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
 */
+(void) registerGlobalProperty:(NSDictionary *)property;

5.2 获取一个全局属性

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

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

5.3 删除一个全局属性

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

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

5.4 获取所有全局属性

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

5.5 清除所有的全局属性

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

6 页面浏览事件API

6.1 页面自动采集

SDK默认不开启自动采集，如果需要开启，接口如下：

接口函数：

//在初始化函数前设置
+ (void)setAutoPageEnabled:(BOOL)value;

示例代码：

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

禁止某页面的自动上报

若需要对某页面的页面编码进行修改，可以通过调用beginLogPageView：和endLogPageView：这组接口对该页面进行手动埋点，并使用skipMe禁止该页面的自动上报。

1. 引入UMSPM.framework

2. 引入头文件UMSpmHybrid.h

3. 调用+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

建议在viewDidAppear最开始调用，如只不统计当前自动页面，可以将pageName参数设置成nil。例：

- (void)viewDidAppear:(BOOL)animated
{
    //不统计当前class自动页面
 [UMSpmHybrid skipMe:[self class] pageName:nil ];

 [super viewDidAppear:animated];
 [MobClick beginLogPageView:@"PageHome"];

}

6.2 页面手动采集

接口函数：

+ (void)beginLogPageView:(NSString *)pageName;

+ (void)endLogPageView:(NSString *)pageName;

参数：

注意：

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

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

示例代码：

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

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

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

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

6.3 页面属性设置

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

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

参数：

事例： 在调用必须在beginLogPageView之后，才可设置页面属性。

[UMSpm updatePageProperties:@"page_home" properties: @{@"page_home_key":@"page_home_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;

参数说明：

示例1：

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

[MobClick event:@"Forward"];

示例2：

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

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