文档目录

目录

1. 使用说明

  • 本文是 DMHub react-native SDK 标准的开发指南文档，用以指导 SDK 的集成和使用，默认读者已经具备一定的 react-native 开发能力。
  • 本篇指南匹配的 DMHub iOS SDK 版本 >= v4.2.12 。

2 导入 SDK

2.1 引入并安装SDK

在react-native项目的package.json中，添加dependency

 "dependencies": {
   "converlab-rn-sdk": "^4.2.12"
 }

然后在项目根目录执行 yarn install

2.2 iOS 链接

进入项目ios 子目录，执行

pod install

这将安装SDK需要的原生依赖

3. 初始化

使用 SDK 记录事件之前需要先进行初始化，在整个应用程序全局，只需要初始化一次。建议将初始化代码放在程序的入口App.tsx中。

  • 代码示例
import { init, track, push } from 'converlab-rn-sdk';

const tenantCode = '******'
const trackingHost = '******'
const appBundleId = '******'
const appVersion = '*.*.*'

useEffect(() => {
    // 初始化SDK，并将事件通用字段通过push的方式统一维护
    init(tenantCode, trackingHost, () => {
      // @ts-ignore
      push({ appName: appBundleId, appVersion: appVersion });
    });
  }, []);

tenantCode是租户的Hash值，trackingHost是埋点服务地址。可以登录DMHub，选择需要埋点的租户，进入'系统设置' -> '营销触点' -> '网站'获取这两个值。如下图：

  • SDK 设备信息收集

请参考 采集详情

4. 客户身份

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

4.1 设置客户身份

为了将客户事件以及客户相关信息与客户绑定，需要在 App 获取到客户身份信息时（如客户注册或登录），设置客户身份。如果未设置身份，埋点记录将记录到匿名用户身上。因此需要通过设置身份，将埋点事件记录到具体客户身上。

react-native sdk通过push方法设置当前session的身份，SDK不会保存并记录身份数据。因此每次启动App并完成登录（包括后台静默登录）后，请调用push完成身份设置。

push({
   identityType:'uid',
   identityValue:'1027712'
});

5. 跟踪客户事件

5.1 跟踪客户自定义事件

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

  • 接口定义 (支持多态)
/**
 * event: 事件key
 * payload: 事件的消息体
 */
track(event: string, payload: json)

/**
 * event: 事件key
 * properties: 事件的消息体
 */
track(event: string, properties: json)

/**
 * event: 事件key
 * targetName: 事件作用于目标的标题， 例如页面的标题
 * targetId: 事件作用于目标的key，例如页面的id
 */
track(event: string, targetName: string, targetId: string)

/**
 * event: 事件key
 * targetName: 事件作用于目标的标题， 例如页面的标题
 * targetId: 事件作用于目标的key，例如页面的id
 * properties: 事件的消息体
 * cb: 事件上报成功的回调函数 () => void 
 */
track(event: string, targetName: string, targetId: string, properties: json, cb: function)
  • 接口示例
const [payload, setPayload] = useState('{"c_gender":"male"}');

<Button
    title='提交自定义事件'
    onPress={() => {
    let payloadJson = {};
    try {
        const payloadJson = payload ? JSON.parse(payload) : {};
        track('c_buy', payloadJson);
    } catch (e) {
        Alert.alert('自定义事件的上报属性应为json格式!');
    }
    }}
/>

5.2 跟踪系统预置事件

埋点时，可以选用DMHub 针对手机应用程序的系统事件, 用于记录标准的App生命周期相关的事件。

// 打开手机应用
track('open_mobile_app', 'AppNameOfRnExample');

// 进入手机视图
track('open_mobile_view', 'HomePage')

// 离开手机视图
track('exit_mobile_view', 'HomePage')

可用系统预置事件列表

事件名称事件keytargetIdtargetNameappNameappVersion时间轴中的title
打开手机应用open_mobile_app移动应用的名称bundleId移动应用的版本打开手机应用 {targetName}
首次打开手机应用first_open_mobile_app移动应用的名称bundleId移动应用的版本首次打开手机应用 {targetName}
进入手机视图open_mobile_view视图名称bundleId移动应用的版本进入手机视图 {targetName}
离开手机视图exit_mobile_view视图名称bundleId移动应用的版本离开手机视图 {targetName}
手机应用结束活跃状态mobile_app_resign_active移动应用的名称bundleId移动应用的版本手机应用结束活跃状态 {targetName}
  • 接口示例

6. 设置全局参数

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

例如下面的代码：

push({
   'model': 'iPhone14'
});