文档目录

目录

1. 使用说明

  • 本文是 DMHub iOS SDK 标准的开发指南文档，用以指导 SDK 的集成和使用，默认读者已经具备一定的 iOS 开发能力。
  • 本篇指南匹配的 DMHub iOS SDK 版本为： v3.0.10 。
  • DMHub iOS SDK 3.0.10 要求 iOS >= 8.0 。

2 导入 SDK

2.1 下载 SDK

点击下载 dmhubsdk-ios-3.0.10.zip

2.2 添加 SDK 文件

下载解压后将 DMHubSDK.framework 库拷贝到工程目录下，然后在 Xcode 中的 TARGETS ---> General ---> Frameworks,Libraries,and Embedded Content 中点击 + 进行添加，或者直接将库文件拖入。

2.3 引入头文件

在需要使用 DMHubSDK 功能的文件中引入头文件：

#import <DMHubSDK/DMHubSDK.h>

通常采用pch文件统一引入该头文件, 如:

#ifndef PrefixHeader_pch
#define PrefixHeader_pch

#import <DMHubSDK/DMHubSDK.h>

#endif

然后在Xcode 中的 TARGETS ---> Build Settings ---> Prefix Header中，指定pch文件

3. 初始化

使用 SDK 记录事件之前需要先进行启动，在整个应用程序全局，只需要启动一次，SDK 提供了多个启动方法，请开发者根据实际需求选择。

  • 接口定义
/**
 启动 DMHubSDK

 @param trackUrl 在 DM Hub 平台创建应用时获得的 url
 @param appId 在 DM Hub 平台创建应用时获得的 appid
 @param appName 在时间轴中显示的应用名
 */
+ (void)startWithUrl:(NSString *)trackUrl
                     appId:(NSString *)appId
                   appName:(NSString *)appName
             launchOptions:launchOptions;
  • 代码示例

在 AppDelegate.m 文件中的 - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 方法中启动 DMHubSDK：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    // 启动 DMHubSDK
    [DMHubSDK startWithUrl:@"<在 DM Hub 平台获得的 url>"
                     appId:@"<在 DM Hub 平台获得的 appid>"
                   appName:@"<时间轴中显示的 app name>"
             launchOptions:launchOptions]
    return YES;
}
  • SDK 设备信息收集

请参考 采集详情

4. 客户身份

客户身份是 DM Hub 中客户的标识，App 端 SDK 采集到的客户事件以及客户相关信息需要通过客户身份与客户进行绑定。

4.1 设置客户身份

为了将客户事件以及客户相关信息与客户绑定，需要在 App 获取到客户身份信息时（如客户注册或登录），设置客户身份。

多次调用设置身份接口，新的身份将会覆盖旧的身份，此后产生的客户事件将与新身份对应的客户绑定。

客户在未设置客户身份期间产生的事件将会作为匿名事件进行记录，匿名事件会保存 30 天。

  • 接口定义
/**
 设置客户身份，用于绑定事件
 如果重复设置，将会使用新的客户身份进行事件绑定
 */
+ (void)setIdentityWithType:(NSString *)identityType
                      value:(NSString *)identityValue;
  • 代码示例
[DMHubSDK setIdentityWithType:@"mobile" value:@"18611110000"];

4.2 当前客户身份

获取当前设置的客户身份。

  • 接口定义
/**
 获取当前设置的客户身份

 @return 如果当前还未设置过有效的客户身份，返回 nil
 */
+ (DMHubIdentity *)currentIdentity;
  • 代码示例
DMHubIdentity * identity = [DMHubSDK currentIdentity];
NSLog(@"type: %@ value: %@", identity.type, identity.value);
@end

4.3 清除客户身份

清除客户身份之后产生的客户事件将会作为匿名事件进行记录。

  • 接口定义
/**
 清除当前设置的客户身份

 @return 当前设置的客户身份，如果当前还未设置过有效的客户身份，返回 nil
 */
+ (DMHubIdentity *)clearIdentity;

5. 跟踪客户事件

5.1 跟踪客户自定义事件

根据业务需求在 DM Hub 后台新建自定义事件后，可以调用该 API 对自定义客户事件进行跟踪。在新建自定义事件时，还可以根据需要添加自定义属性，并在调用 API 时作为参数传入。

  • 接口定义
/**
 跟踪客户自定义事件

 @param eventId 在 DM Hub 中新建的自定义事件的事件 Id
 @param properties 事件的自定义属性，必须以在 DM Hub 中新建自定义事件时添加的自定义属性作为 key
 */
+ (void)trackWithEventId:(NSString *)eventId
              properties:(NSDictionary *)properties;
  • 代码示例
@implementation YourViewController

- (IBAction)valueTextFieldEditingChanged:(UITextField *)sender {
    if (self.typeTextField.text.length > 0 && self.valueTextField.text.length > 0) {
        self.setIdentityBtn.enabled = YES;
        [DMHubSDK trackWithEventId:@"c_search" properties:@{
            @"c_keyWords": self.typeTextField.text
        }];
    } else {
        self.setIdentityBtn.enabled = NO;
    }
}
@end

5.2 跟踪进入、离开视图事件

如果设置了自动跟踪进入、离开视图事件，则不需要在调用以下两个 API 进行跟踪。

  • 接口定义
/**
 跟踪进入视图事件

 @param viewName 视图的名称，客户时间轴上的显示为：'进入手机视图 ${viewName}'
 */
+ (void)trackOpenView:(NSString *)viewName;

/**
 跟踪离开视图事件

 @param viewName 视图的名称，客户时间轴上的显示为：'离开手机视图 ${viewName}'
 */
+ (void)trackExitView:(NSString *)viewName;
  • 代码示例
@implementation YourViewController

- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    
    // 跟踪进入视图事件
    [DMHubSDK trackOpenView:@"<viewName>"];
}

- (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    
    // 跟踪离开视图事件
    [DMHubSDK trackExitView:@"<viewName>"];
}

@end

5.3 跟踪通知推送相关事件

如果您使用了 DM Hub 平台提供的通知推送功能，则可以调用 SDK 提供的相关 API 对来自 DM Hub 平台的通知推送相关事件进行跟踪。

注意：推送事件跟踪需要确保是通过 DM Hub 平台进行的推送，对于非 DM Hub 平台进行推送的通知SDK将不进行推送跟踪，如需跟踪第三方平台推送消息，可通过自定义客户事件上报。

5.3.1 设置消息推送相关信息

为了采集消息推送相关信息，跟踪来自 DM Hub 平台的通知推送相关事件，DMHubSDK 需要获取您在推送服务商注册应用时获得的 AppKey，以及推送服务商分配给设备的标识（极光的 registrationID、个推的 clientId）。

  • 接口定义
/**
 设置消息推送的相关信息，以便通过 DM Hub 对客户进行 App 消息推送

 @param appKey 在推送服务商注册应用时获得的 AppKey
 @param provider 推送服务商，目前支持极光（@"jpush"）和个推（@"getui"）
 */
+ (void)setAppKey:(NSString *)appKey
      forProvider:(NSString *)provider;

/**
 设置消息推送的相关信息，以便通过 DM Hub 对客户进行 App 消息推送

 @param appKey 在推送服务商注册应用时获得的 AppKey
 @param pushId 推送服务商分配给设备的标识，极光的 registrationID 或个推的 clientId
 @param provider 推送服务商，目前支持极光（@"jpush"）和个推（@"getui"）
 */
+ (void)setAppKey:(NSString *)appKey
           pushId:(NSString *)pushId
      forProvider:(NSString *)provider;

5.3.2 跟踪 JPush 推送相关事件

  • 接口定义
/**
 跟踪收到 JPush 自定义消息事件

 @param notification JPush 收到自定义消息的回调方法中传入的 notification
 */
+ (void)trackReceiveJPushMessage:(NSNotification *_Nonnull)notification;
  • 代码示例
// 收到 JPush 自定义消息的回调
- (void)didReceiveJPushMessage:(NSNotification *)notification {
    [DMHubSDK trackReceiveJPushMessage:notification];
}

5.3.3 跟踪 GeTui 推送相关事件

  • 接口定义
/**
 跟踪收到 GeTui 透传消息事件

 @param payloadData GeTui 收到透传消息的回调方法中传入的 payloadData
 @param offLine GeTui 收到透传消息的回调方法中传入的 offLine
 */
+ (void)trackReceiveGeTuiPayloadData:(NSData *_Nonnull)payloadData offLine:(BOOL)offLine;
  • 代码示例
// 收到 GeTui 透传消息的回调
- (void)GeTuiSdkDidReceivePayloadData:(NSData *)payloadData andTaskId:(NSString *)taskId andMsgId:(NSString *)msgId andOffLine:(BOOL)offLine fromGtAppId:(NSString *)appId {
    [DMHubSDK trackReceiveGeTuiPayloadData:payloadData offLine:offLine];
}

6. 设置全局参数

如果一个应用设置的追踪代码较多，而且他们之间有一些公共的参数，如果在每个追踪点都分别设置这些参数，会给代码维护带来不便。为此，DMHubSDK引入了push方法，用来设置应用全局的参数。通过push方法设置的参数，在该应用后续的track方法调用时，会自动传递。

例如下面的代码：

[DMHubSDK push:@{@"campaign":@"8月促活"}];