埋点API

1 如何查看埋点方案

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

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

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

• 设备ID：macOS设备默认设备ID为应用级别唯一的设备ID，由Quick Tracking SDK自动生成或者通过调用setCustomDeviceId接口设置。

• 账号ID：客户端用户登录体系的账号标识，当一个用户在不同的设备进行登录时，设备ID会发生变化，但是账号ID不会发生变化。例如一个用户分别使用两台电脑登录。

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

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

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

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

埋点须知

• 传入参数大小限制：

2. 应用预制事件

2.1 手动触发应用启动事件

接口函数：

// 手动触发应用启动事件
-(void)trackAppStart:(NSDictionary *_Nullable)properties;

参数：

示例：

NSDictionary *appStartProperties = @{
    @"appStartTest": @"appStartTest",
    @"times": @1024,
    @"subContents": @[@"test1", @"test2", @"test3"]
};
[[QuickTrackingSDK sharedInstance] trackAppStart:appStartProperties];

2.2 手动触发应用退出事件

接口函数：

// 手动触发应用退出事件
-(void)trackAppEnd:(NSDictionary *_Nullable)properties;

参数：

示例：

NSDictionary *appEndProperties = @{
    @"appEndTest": @"appEndTest"
};
[[QuickTrackingSDK sharedInstance] trackAppEnd:appEndProperties];

3 设备ID

SDK支持自定义设备ID，如果要使用自定义设备ID，需要设置setCustomDeviceId 接口为有效值（非空），默认值为设备唯一标识加密后的内容。

3.1 设置自定义设备ID

接口函数：

// 设置自定义设备ID
-(void)setCustomDeviceId:(NSString *_Nonnull)customDeviceID;

参数：

示例：

[[QuickTrackingSDK sharedInstance] setCustomDeviceId:@"your_deviceId"];

3.2 读取设备ID

接口函数：

// 读取设备ID
-(NSString *_Nullable)getDeviceID;

示例：

NSString *deviceID = [[QuickTrackingSDK sharedInstance] getDeviceID];

使用注意：

该方法依赖于SDK初始化完成，可能返回空值

4 账号ID

4.1 用户登入

Quick Tracking SDK在统计用户时以设备为标准，如果需要统计自身的账号，请使用以下方法。

接口函数：

// 登录
- (void)onProfileSignIn:(NSString *_Nonnull)userId;

参数：

示例：

[[QuickTrackingSDK sharedInstance] onProfileSignIn:@"your_userId"];

4.2 用户登出

如果不再需要绑定用户账号，可以调用SDK提供的用户登出方法，调用后SDK不再发送用户账号相关内容。

接口函数：

// 登出
- (void)onProfieSignOff;

示例：

[[QuickTrackingSDK sharedInstance] onProfieSignOff];

5 用户属性上传

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

接口函数：

// 用户属性上传
- (void)uploadUserProfile:(NSDictionary *_Nullable)properties;

参数：

示例：

NSDictionary *userProfile = @{
  @"name": @"your_name",
  @"email": @"example@example.com"
};
[[QuickTrackingSDK sharedInstance] uploadUserProfile:userProfile];

使用注意：

SDK不会缓存用户属性，上报用户属性需先调用用户账号设置APIonProfileSignIn才能保证数据准确性。

6. 全局属性

6.1 注册全局属性

接口函数：

// 设置全局属性
-(void)registerGlobalProperties:(NSDictionary * _Nonnull)properties;

参数：

示例：

[[QuickTrackingSDK sharedInstance] registerGlobalProperties:@{
    @"content": @"测试",
    @"times": @1024,
    @"subContents": @[@"abc", @"def", @"ghi"]
}];

使用注意：

如果和已经存在的全局属性key重复，则更新已有值；如果和已经存在的全局属性key不一致，则插入新的全局属性。

6.2 删除一个全局属性

接口函数：

// 根据Key删除全局属性
-(void)unregisterGlobalProperty:(NSString *_Nonnull)propertyName;

参数：

示例：

[[QuickTrackingSDK sharedInstance] unregisterGlobalProperty:@"your_key"];

6.3 根据key获取单个全局属性

接口函数：

// 根据Key获取全局属性
-(id _Nullable)getGlobalProperty:(NSString *_Nonnull)propertyName;

参数：

返回值：

示例：

id value = [[QuickTrackingSDK sharedInstance] getGlobalProperty:@"your_key"];

6.4 获取全部全局属性

接口函数：

// 获取全部全局属性
-(NSDictionary *_Nullable)getGlobalProperties;

返回值：

示例：

NSDictionary *globalProperties = [[QuickTrackingSDK sharedInstance] getGlobalProperties];

6.5 清空全部全局属性

接口函数：

// 清空全部全局属性
-(void)clearGlobalProperties;

示例：

[[QuickTrackingSDK sharedInstance] clearGlobalProperties];

7. 页面浏览事件

使用前，请先到QuickTracking管理后台的数据采集-->埋点管理-->事件管理模块，创建相应的页面事件，然后在工程中传入相应的页面编码（page_name）。

7.1 页面启动

接口函数：

// 统计页面进入行为
+(void)onPageStart:(id _Nonnull)pageContext page_name:(NSString * _Nonnull)page_name options:(NSDictionary *_Nullable)options;

参数：

示例：

NSDictionary *pageOptions = @{
    @"url": @"your_url",
    @"page_title": @"your_page_title"
};
[QuickTrackingSDK onPageStart:self page_name:@"your_page_name" options:pageOptions];

7.2 页面离开

接口函数：

// 统计页面离开行为
+(void)onPageEnd:(id _Nonnull)pageContext page_name:(NSString * _Nonnull)page_name;

参数：

示例：

[QuickTrackingSDK onPageEnd:self page_name:@"your_page_name"];

7.3 设置页面事件属性

接口函数：

// 设置页面事件属性
+(void)updatePageProperties:(id _Nonnull)pageContext page_name:(NSString *_Nonnull)page_name properties:(NSDictionary *_Nonnull)properties;

参数：

示例：

NSDictionary *pageProperties = @{
    @"page_type": @"main",
    @"user_role": @"admin"
};
[QuickTrackingSDK updatePageProperties:self page_name:@"your_name" properties:pageProperties];

8. 事件埋点

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

使用前，请先到QuickTracking管理后台的数据采集-->埋点管理-->事件管理模块，创建相应的自定义事件，然后在工程中传入相应的事件编码。

接口函数：

// 埋点事件
- (void)event:(NSString *_Nonnull)eventCode;
// 埋点事件带事件属性
- (void)event:(NSString *_Nonnull)eventCode properties:(NSDictionary *_Nullable)properties;
// 埋点事件带页面编码
- (void)event:(NSString *_Nonnull)eventCode page_name:(NSString *_Nonnull)page_name;
// 埋点事件带页面编码和事件属性
- (void)event:(NSString *_Nonnull)eventCode page_name:(NSString *_Nonnull)page_name properties:(NSDictionary *_Nullable)properties;

参数：

示例：

// 埋点事件
NSString *eventCodeSimple = @"your_event_code";
[[QuickTrackingSDK sharedInstance] event:eventCodeSimple];

// 埋点事件带页面属性
NSString *eventCodeWithProperties = @"your_event_code";
NSDictionary *yourProperties = @{
    @"item_name": @"your_item_name",
    @"item_price": @20
};
[[QuickTrackingSDK sharedInstance] event:eventCodeWithProperties properties:yourProperties];

// 埋点事件带页面编码
NSString *eventCodeWithPage = @"your_event_code";
NSString *page_name = @"homepage";
[[QuickTrackingSDK sharedInstance] event:eventCodeWithPage page_name:page_name];

// 埋点事件带页面编码和事件属性
NSString *eventCodeWithPageWithProperties = @"your_event_code";
NSString *page_name = @"settings_page";
NSDictionary *properties = @{
    @"button_name": @"save_settings",
    @"user_id": @"test"
};
[[QuickTrackingSDK sharedInstance] event:eventCodeWithPageWithProperties page_name:page_name properties:properties];

9. 其他

9.1 禁用SDK

调用后，SDK将不采集事件，不发送网络请求。

接口函数：

// 禁用SDK
+(void)disableSDK;

示例：

[QuickTrackingSDK disableSDK];

9.2 开启SDK

如果之前SDK是禁止状态，调用后将恢复数据采集功能。

接口函数：

// 开启SDK
+(void)enableSDK;

示例：

[QuickTrackingSDK enableSDK];