Flutter集成DMHub服务插件dmhubsdk的使用

前端埋点 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

在 pubspec.yaml 文件中添加以下依赖：

dependencies:
   dmhubsdk:^1.0.9

2.2 导入包

在 Dart 文件中导入 SDK：

import 'package:dmhubsdk/dmhubsdk.dart';

3. 初始化

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

3.1 接口定义

/**
 * 在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 初始化函数。

3.2 代码示例

如果为 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());
}

3.3 禁用采集项

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

禁用 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 获取到客户身份信息时（如客户注册或登录），设置客户身份。

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

接口定义：

/**
 * 设置客户身份，用于绑定事件
 * 如果重复设置，将会使用新的客户身份进行事件绑定
 * 使用范围: 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);

代码示例：

Map<String, dynamic> maProperties = {
  'aa': '55555555',
  'bb': '66666666',
};
DMHubClient.getInstance.trackMap('trackMap-44434333', maProperties);
DMHubClient.getInstance.track('track-4434333');

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

接口定义：

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

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

代码示例：

DMHubClient.getInstance.trackOpenView('FlutterViewController');
DMHubClient.getInstance.trackExitView('FlutterViewController');

5.3 跟踪通知推送相关事件

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 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);

代码示例：

DMHubClient.getInstance.onJPushReceiveRegisterId(appKey: '自己的秘钥', clientId: '服务商返回的registrationID');
DMHubClient.getInstance.onJPushReceiveMessageData(message);
DMHubClient.getInstance.trackReceiveJPushMessage(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> payload);  

/**
 * 在自定义的 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);

代码示例：

DMHubClient.getInstance.onGeTuiReceiveClientId('注册应用时获得的AppKey', '推送服务商分配给设备的标识clientId');
DMHubClient.getInstance.trackReceiveGeTuiPayloadData(message);

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 初始化

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

示例代码

以下是一个完整的示例代码，展示如何在 Flutter 中集成 DMHub 插件：

import 'package:flutter/material.dart';
import 'dart:async';
import 'package:dmhubsdk/dmhubsdk.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  var options = DMHubOptions(
      trackUrl: 'https://xxxxx/cbe/track?tid=xxxx',
      appId: 'appId',
      appName: 'FlutterDemo');
  options.autoTrackOpenAppEvent = true;
  options.enableDebugLogging = true;
  options.flushInterval = 40;
  // 禁用 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);
  // 禁用对imei采集
  DMHubClient.getInstance.disableCollect([DMHubOptions.COLLECT_IMEI]);
  // 启用对定位的采集
  DMHubClient.getInstance.enableCollect([DMHubOptions.COLLECT_MAC]);

  DMHubClient.getInstance
      .setIdentity("身份证", "51028xxxxxxxxxxx299")
      .then((value) => null);

  Map<String, dynamic> mapPush = {
    'appKey': '4x33fbdafdif',
    'pushId': '55444378x',
    'provider': "这是测试的数据"
  };
  DMHubClient.getInstance.onGlobalParamsPush(mapPush);

  DMHubClient.getInstance.currentIdentity().then((result) {
    DMHubLog.v(result, tag: 'identityDmhub');
  });

  Map<String, dynamic> maProperties = {
    'aa': '55555555',
    'bb': '66666666',
  };
  DMHubClient.getInstance.trackMap('trackMap-44434333', maProperties);
  DMHubClient.getInstance.track('track-4434333');
  DMHubClient.getInstance.trackOpenView('FlutterViewController');
  DMHubClient.getInstance.trackExitView('FlutterViewController');

  DMHubClient.getInstance.onJPushReceiveRegisterId('443245454', 'fgfgfddfdfdf');
  Map<String, dynamic> jpushMap = {
    'aaddf': '55555555',
    'bbdfdfd': '66666666',
  };
  DMHubClient.getInstance.onJPushReceiveMessageData(jpushMap);
  jpushMap = {
    'xabbdaddf': '55555555',
    'xbbdddfdfd': '66666666',
  };
  DMHubClient.getInstance.onJPushNotificationMessageArrived(jpushMap);
  DMHubClient.getInstance.onGeTuiReceiveClientId('fdxxxx', '333334433');
  DMHubClient.getInstance.trackReceiveJPushMessage(jpushMap);
  DMHubClient.getInstance.trackReceiveGeTuiPayloadData(jpushMap);

  runApp(MyApp());
}

class MyApp extends StatefulWidget {
  [@override](/user/override)
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  String _platformVersion = 'Unknown';

  [@override](/user/override)
  void initState() {
    super.initState();
    initPlatformState();
  }

  Future<void> initPlatformState() async {
    // 初始化逻辑
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('Plugin example app'),
        ),
        body: Center(
          child: Text('Running on: $_platformVersion\n'),
        ),
      ),
    );
  }
}

gougou168 1楼•11 天前

更多关于Flutter集成DMHub服务插件dmhubsdk的使用的实战系列教程也可以访问 https://www.itying.com/category-92-b0.html

要在Flutter项目中集成DMHub服务插件 dmhubsdk，你需要按照以下步骤进行操作。假设你已经有一个Flutter项目，并且你希望将 dmhubsdk 插件集成到你的项目中。

1. 添加依赖

首先，你需要在 pubspec.yaml 文件中添加 dmhubsdk 插件的依赖。

dependencies:
  flutter:
    sdk: flutter
  dmhubsdk: ^1.0.0  # 请根据实际情况填写版本号

然后运行 flutter pub get 来获取依赖。

2. 初始化SDK

在你的Flutter应用的入口文件（通常是 main.dart）中，初始化 dmhubsdk。

import 'package:flutter/material.dart';
import 'package:dmhubsdk/dmhubsdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // 初始化DMHub SDK
  await DMHubSDK.init(
    appId: 'YOUR_APP_ID',  // 替换为你的App ID
    appKey: 'YOUR_APP_KEY',  // 替换为你的App Key
  );

  runApp(MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Flutter DMHub Demo',
      home: HomeScreen(),
    );
  }
}

3. 使用SDK功能

你可以在你的应用中使用 dmhubsdk 提供的各种功能。例如，发送事件、获取用户信息等。

import 'package:flutter/material.dart';
import 'package:dmhubsdk/dmhubsdk.dart';

class HomeScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text('DMHub SDK Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            ElevatedButton(
              onPressed: () async {
                // 发送事件
                await DMHubSDK.trackEvent(
                  eventName: 'button_click',
                  properties: {'button_name': 'demo_button'},
                );
              },
              child: Text('Track Event'),
            ),
            ElevatedButton(
              onPressed: () async {
                // 获取用户信息
                var userInfo = await DMHubSDK.getUserInfo();
                print('User Info: $userInfo');
              },
              child: Text('Get User Info'),
            ),
          ],
        ),
      ),
    );
  }
}

4. 处理平台特定配置

dmhubsdk 可能需要在Android和iOS平台上进行一些额外的配置。请参考插件的官方文档或README文件，确保你完成了所有必要的配置步骤。

5. 运行应用

完成上述步骤后，你可以运行你的Flutter应用，并测试 dmhubsdk 的功能。

flutter run