dmhubsdk 1.0.9

Dmhub Flutter project.

---

前端埋点 Flutter Sdk 集成使用指南

1. 使用说明

• 本文是 DMHub Flutter SDK 标准的开发指南文档，用以指导 SDK 的集成和使用，默认读者已经具备一定的 Flutter 开发能力。
• 本篇指南使用了 DMHub Android SDK 版本为： v3.0.9 和 DMHub IOS SDK版本为:v3.0.9 作为标准。
• DMHub Flutter SDK v1.0.9 要求 Flutter >=2.12.0 <3.0.0 。

2. SDK导入

2.1 在yaml中添加 SDK

dependencies:
   dmhubsdk:^1.0.9

2.2 导入包

import 'package:dmhubsdk/dmhubsdk.dart';

3. 初始化

使用 SDK 记录事件之前需要先进行初始化，在整个应用程序全局，只需要进行一次初始化。

• 接口定义

/**
 * 在main.dart中,只需要进行一次初始化
 * 使用范围:  android|ios
 */
DMHubClient.getInstance.init(DMHubOptions options);  
/**
 * 初始化SDK 指定[options] 
 * 在main.dart中,只需要进行一次初始化
 * 使用范围: only ios
 */
DMHubClient.getInstance.initWithOptions(DMHubOptions options);

确保App首次冷启动时，在用户阅读您的《隐私政策》并取得用户授权之后，才调用正式初始化函数DMHubSDK.init初始化统计SDK，此时SDK才会真正采集设备信息并上报数据。反之，如果用户不同意《隐私政策》授权，则不能调用DMHubSDK.init初始化函数。

• 代码示例
  如果为 Flutter Application，可在 main.dart 中开启调试模式并进行初始化：

void main() {
  var options = DMHubOptions(
      trackUrl: 'https://xxxxxxxx/cbe/track?tid=1608893914', // 部署方确认地址
      appId: 'xxxxx', // 通过后台系统获取
      appName: 'xxx'); // 所上报的应用名
      
  options.autoTrackOpenAppEvent = true; //是否自动记录进入、离开视图事件，默认值：NO
  
  options.enableDebugLogging = true; //是否打印日志，默认值：YES
  
  options.flushInterval = 30;  //上传数据的时间间隔（单位：秒），默认值：30 
  
  // 应用时长上报需满足： minimumActiveDuration <= 应用时长 <= activeTimeoutDuration
  options.minimumActiveDuration =  1 * 1000; // 影响上报应用活跃时长，应用时长需满足最小该值才运行进行上报, 单位 毫秒
  
  options.activeTimeoutDuration = 6 * 60 * 60 * 1000; // 影响上报应用活跃时长，应用如时长如果超过该时长，则不允许上报, 单位 毫秒  
  
  options.maximumBackgroundDuration = 10 * 1000; // 影响上报应用打开事件，如果应用置于后台超过该时间，则认定为新打开应用周期, 单位 毫秒  
  
  // 禁止 androidId、idfa、location信息（定位）、mac 的采集
  options.disableCollect = [
    DMHubOptions.COLLECT_ANDROID_ID,
    DMHubOptions.COLLECT_IDFA,
    DMHubOptions.COLLECT_LOCATION,
    DMHubOptions.COLLECT_MAC
  ];
  DMHubClient.getInstance.init(options).then((value) => null);  
  runApp(MyApp());
}

• tid ：在 设置中心 > 网站设置 中可以查看{YOUR_TID}
• appId ：应用的唯一标识，同一应用的不同版本（iOS/Android）appId 可保持一致
• appName ：在时间轴中显示的应用名
  如果为混合开发应用，在原生端初始化后将不再重新进行初始化。

3.1 禁用采集项

SDK 默认对采集开关为启用状态，当满足已被系统授权状态时，SDK会对采集项进行上报。

SDK 不会主动触发用户授权，仅在被动授权完成后，SDK才会触发采集行为。

初始化时，通过对 DMHubOptions disableCollect 属性进行配置，以下为禁用 androidId、idfa、location信息（定位）、mac 的采集例子：

  // 禁用 androidId、idfa、location信息（定位）、mac 的采集
  options.disableCollect = [
    DMHubOptions.COLLECT_ANDROID_ID,
    DMHubOptions.COLLECT_IDFA,
    DMHubOptions.COLLECT_LOCATION,
    DMHubOptions.COLLECT_MAC
  ];
  DMHubClient.getInstance.initWithOptions(options).then((value) => null);

由于Android、iOS 平台在采集项上的差异性，对于不同的配置项所生效的目标平台不一样，以下为支持的禁用枚举值：

枚举值	说明	支持平台
DMHubOptions.COLLECT_IDFA	idfa 信息	iOS
DMHubOptions.COLLECT_BLUETOOTH	蓝牙信息	Android
DMHubOptions.COLLECT_MAC	网卡Mac信息	android
DMHubOptions.COLLECT_ANDROID_ID	android id	Android
DMHubOptions.COLLECT_IMEI	imei	Android
DMHubOptions.COLLECT_LOCATION	经纬定位信息	iOS、Android
DMHubOptions.COLLECT_NETWORK_STATE	网络状态	iOS、Android
DMHubOptions.COLLECT_NETWORK_OPERATOR	网络运营商	iOS、Android

4. 客户身份

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

4.1 设置客户身份

为了将客户事件以及客户相关信息与客户绑定，需要在 App 获取到客户身份信息时（如客户注册或登录），设置客户身份。
多次调用设置身份接口，新的身份将会覆盖旧的身份，此后产生的客户事件将与新身份对应的客户绑定。
客户在未设置客户身份期间产生的事件将会作为匿名事件进行记录，匿名事件会保存 30 天。

• 接口定义

/**
 * 设置客户身份，用于绑定事件
 * 如果重复设置，将会使用新的客户身份进行事件绑定
 * 使用范围: android|ios
 */
DMHubClient.getInstance.setIdentity(String identityType, String identityValue);

4.2 当前客户身份

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

• 接口定义

/**
 * 获取当前设置的客户身份
 * @return 如果当前还未设置过有效的客户身份，返回 null
 * 使用范围: android|ios
 */
DMHubClient.getInstance.currentIdentity().then((result){
  DMHubLog.v(result, tag: 'identityDmhub');
});

4.3 清除客户身份

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

• 接口定义

/**
 * 清除当前设置的客户身份
 * @return 当前设置的客户身份，如果当前还未设置过有效的客户身份，返回 null
 * 使用范围: android|ios
 */
DMHubClient.getInstance.clearIdentity().then((result){
  DMHubLog.v(result, tag: 'identityDmhub');
});

5. 跟踪客户事件

5.1 跟踪自定义客户事件

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

• 接口定义

/**
 * 跟踪自定义客户事件
 *
 * @param eventId    在 DM Hub 中新建的自定义事件的事件 Id
 * @param properties 事件的自定义属性，必须以在 DM Hub 中新建自定义事件时添加的自定义属性作为 key
 * 使用范围: android|ios
 */
DMHubClient.getInstance.trackMap(String eventId, Map<String, dynamic> properties);  
/**
 * 跟踪自定义客户事件
 *
 * @param eventId 在 DM Hub 中新建的自定义事件的事件 Id
 * 使用范围: only android
 */
DMHubClient.getInstance.track(String eventId);

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

• 接口定义

/**
 * 跟踪进入视图事件
 *
 * @param viewName 视图的名称，客户时间轴上的显示为：'进入手机视图 ${viewName}'
 * 使用范围: android|ios
 */
DMHubClient.getInstance.trackOpenView(String viewName);  
/**
 * 跟踪离开视图事件
 *
 * @param viewName 视图的名称，客户时间轴上的显示为：'离开手机视图 ${viewName}'
 * 使用范围: android|ios
 */
DMHubClient.getInstance.trackExitView(String viewName);

• 代码示例

/// 当应用生命周期导致页面发生变化时，作为页面进入退出场景
  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    super.didChangeAppLifecycleState(state);
    print("当前的应用生命周期状态 : ${state}");
    if(state == AppLifecycleState.paused){
      print("应用进入后台 paused");
         DMHubClient.getInstance.trackExitView('');
    }else if(state == AppLifecycleState.resumed){
      print("应用进入前台 resumed");
         DMHubClient.getInstance.trackOpenView('');
    }else if(state == AppLifecycleState.inactive){
      // 应用进入非活动状态 , 如来了个电话 , 电话应用进入前台
      // 本应用进入该状态
      print("应用进入非活动状态 inactive");
    }else if(state == AppLifecycleState.detached){
      // 应用程序仍然在 Flutter 引擎上运行 , 但是与宿主 View 组件分离
      print("应用进入 detached 状态 detached");
    }
  }

5.3 跟踪通知推送相关事件

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

5.3.1 跟踪 JPush 推送相关事件

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

• 接口定义

/**
 *@description 设置消息推送的相关信息，以便通过 DM Hub 对客户进行 App 消息推送
 *@param appKey 在推送服务商注册应用时获得的 AppKey
 *@param provider 推送服务商，目前支持极光（@"jpush"）和个推（@"getui"）
 * 使用范围: only ios
 */
DMHubClient.getInstance.setAppKey(String appKey, String provider);  
/**
 *@description 设置消息推送的相关信息，以便通过 DM Hub 对客户进行 App 消息推送
 *@param appKey 在推送服务商注册应用时获得的 AppKey
 *@param @param pushId 推送服务商分配给设备的标识，极光的 registrationID 或个推的 clientId
 *@param provider 推送服务商，目前支持极光（@"jpush"）和个推（@"getui"）
 * 使用范围: only ios
 */
DMHubClient.getInstance.setAppKeyWithPushId(String appKey, String pushId, String provider);  
/**
 *@description 设置消息推送的相关信息，以便通过 DM Hub 对客户进行 App 消息推送
 *@param appKey 在推送服务商注册应用时获得的 AppKey
 *@param clientId 推送服务商分配给设备的标识，极光的registrationID
 * 使用范围: android|ios
 */
DMHubClient.getInstance.onJPushReceiveRegisterId(String appKey, String clientId);  
/**
 * 当自定义的 JPush 广播接收器收到来自 JPush 的广播时调用
 *
 * @param bundle JPUSH回调事件接收到的message数据
 * 使用范围: android|ios
 */
DMHubClient.getInstance.onJPushReceiveMessageData(Map<String, Object> bundle)  
 /**
 * 当自定义的 JPush 广播接收器收到来自 JPush 的广播时调用
 *
 * @param bundle JPUSH回调事件接收到的message数据
 * 使用范围: android|ios
 */
DMHubClient.getInstance.onJPushNotificationMessageArrived(Map<String, Object> bundle)  
/**
 * 跟踪收到 JPush 自定义消息事件
 *
 * @param userInfo Flutter JPush回调onReceiveNotification方法中接收到的参数
 * 使用范围: only ios
 */
DMHubClient.getInstance.trackReceiveJPushMessage(Map<String, dynamic> userInfo);

• 代码示例

    ///以JPush极光推送为例: 配置jpush(省略）
    ///debug就填debug:true，我这是生产环境所以production:true
    jpush.setup(appKey: '自己的秘钥' ,channel: 'developer-default',production: true,debug: false);
    //调用
    DMHubClient.getInstance.onJPushReceiveRegisterId(appKey: '自己的秘钥',clientId:'服务商返回的registrationID');  
    /// 监听jpush
    jpush.applyPushAuthority(
        new NotificationSettingsIOS(sound: true, alert: true, badge: true));
    jpush.addEventHandler(
      onReceiveNotification: (Map<String, dynamic> message) async {
        //android|ios
        DMHubClient.getInstance.onJPushReceiveMessageData(message);
        //或在IOS也可以调用如下接口
        DMHubClient.getInstance.trackReceiveJPushMessage(message);
      },
      onOpenNotification: (Map<String, dynamic> message) async {
        /// 点击通知栏消息，在此时通常可以做一些页面跳转等
         DMHubClient.getInstance.onJPushNotificationMessageArrived(message);
      },
    ); 

5.3.2 跟踪 GeTui 推送相关事件

• 接口定义

/**
 * 在自定义的 GTIntentService 的 onReceiveClientId 方法中调用
 * @param appKey 在推送服务商注册应用时获得的 AppKey
 * @param clientId 推送服务商分配给设备的标识，GeTui的 clientId
 * 使用范围: android|ios
 */
DMHubClient.getInstance.onGeTuiReceiveClientId(String appKey,String clientId);  
/**
 * 在自定义的 GTIntentService 的 onReceiveMessageData 方法中调用
 *
 * @param taskId    GTTransmitMessage 中携带的 taskId
 * @param messageId GTTransmitMessage 中携带的 messageId
 * @param payload   GTTransmitMessage 中携带的 payload
 * 使用范围: only android
 */
DMHubClient.getInstance.onGeTuiReceiveMessageData(String taskId, String messageId, Map<String, dynamic> playload);  
/**
 * 在自定义的 GTIntentService 的 onNotificationMessageArrived 方法中调用
 *
 * @param taskId    GTNotificationMessage 中携带的 taskId
 * @param messageId GTNotificationMessage 中携带的 messageId
 * 使用范围: only android
 */
DMHubClient.getInstance.onGeTuiNotificationMessageArrived(String taskId, String messageId);
/**
 * 跟踪收到 GeTui 透传消息事件
 *
 * @param userInfo Flutter GeTui回调onReceivePayload方法中接收到的参数
 * 使用范围: only ios
 */
DMHubClient.getInstance.trackReceiveGeTuiPayloadData(Map<String, dynamic> userInfo);

• 代码示例

// 初始化GeTui
DMHubClient.getInstance.onGeTuiReceiveClientId('注册应用时获得的AppKey','推送服务商分配给设备的标识clientId');
//监听事件
Getuiflut().addEventHandler(
  onReceiveClientId: (String clientid) async {
    print("flutter onReceiveClientId: $clientid");
    DMHubClient.getInstance.onGeTuiReceiveClientId(clientid);
  },
  onReceiveMessageData: (Map<String, dynamic> msg) async {
    print("flutter onReceiveMessageData: $msg");
    DMHubClient.getInstance.onGeTuiReceiveMessageData(msg['taskId'],msg['messageId'],msg['payload']);
  },
  onReceivePayload: (Map<String, dynamic> msg) async {
    print("flutter onReceivePayload: $msg");
    DMHubClient.getInstance.trackReceiveGeTuiPayloadData(msg);
  },
  onNotificationMessageArrived: (Map<String, dynamic> msg) async {
    print("flutter onNotificationMessageArrived");
    DMHubClient.getInstance.onGeTuiNotificationMessageArrived(msg['taskId'],msg['messageId']);
  }
 }

6. 设置全局参数

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

/**
 * 全局参数设置
 *
 * @param 公共的参数map    
 * 使用范围: android|ios
 */
DMHubClient.getInstance.onGlobalParamsPush(Map<String, dynamic> params);

7. 混合开发

7.1 SDK导入

Flutter SDK 本身内置了 Android/IOS 的原生SDK，Android原生代码中可以直接调用原生SDK的方法，IOS的原生代码中使用原生SDK方法时需要引入头文件。（请参考IOS原生SDK的说明文档）

7.2 初始化

如果为混合开发应用，在原生端初始化后，无需重新进行初始化。