安卓SDK使用指南 | DM Hub API 文档

1. 使用说明

本文是 DMHub Android SDK 标准的开发指南文档，用以指导 SDK 的集成和使用，默认读者已经具备一定的 Android 开发能力。
本篇指南匹配的 DMHub Android SDK 版本为： v3.0.9 。
DMHub Android SDK v3.0.9 要求 Java >= 1.7 & Android API >= 14 。

2. 导入 SDK

2.1 下载 SDK

2.2 添加 jar 包

下载解压后复制 dmhubsdk-android-3.0.9.jar 文件到工程主 module 的 libs 目录下，右键 jar 包，选择 Add As Library... ，将 jar 包作为 Library 添加到主 module 中。

2.3 配置 AndroidManifest.xml

配置 SDK 所需权限

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.BLUETOOTH" />

3. 初始化

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

接口定义

/**
 * 在自定义的 Application 中初始化 DMHubSDK
 * 在整个应用程序全局，只需要进行一次初始化
 */
public static void init(Context context, Configuration configuration);

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

代码示例

在自定义的 Application 中的 onCreate 方法中开启调试模式并进行初始化：

public class YourApp extends Application {
    
    @Override
    public void onCreate() {
        super.onCreate();

        // 初始化 DMHubSDK
        DMHubSDK.init(this, Configuration.create(
                TRACK_URL,
                APP_ID,
                APP_NAME
        ).enableDebugLogging(true).setAutoTrackOpenAppEvent(true));
    }
}

SDK 设备信息收集

请参考采集详情

4. 客户身份

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

4.1 设置客户身份

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

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

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

接口定义

/**
 * 设置客户身份，用于绑定事件
 * 如果重复设置，将会使用新的客户身份进行事件绑定
 */
public static void setIdentity(final String identityType, final String identityValue);

代码示例

DMHubSDK.setIdentity("mobile", "18611110000");

4.2 当前客户身份

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

接口定义

/**
 * 获取当前设置的客户身份
 * @return 如果当前还未设置过有效的客户身份，返回 null
 */
public static DMHubIdentity currentIdentity();

代码示例

 DMHubIdentity currentIdentity = DMHubSDK.currentIdentity();
 String type = currentIdentity.getType();
 String value = currentIdentity.getVAlue();

4.3 清除客户身份

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

接口定义

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

5. 跟踪客户事件

5.1 跟踪自定义客户事件

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

接口定义

/**
 * 跟踪自定义客户事件
 *
 * @param eventId    在 DM Hub 中新建的自定义事件的事件 Id
 * @param properties 事件的自定义属性，必须以在 DM Hub 中新建自定义事件时添加的自定义属性作为 key
 */
public static void trackMap(final String eventId, final Map<String, Object> properties);

/**
 * 跟踪自定义客户事件
 *
 * @param eventId    在 DM Hub 中新建的自定义事件的事件 Id
 * @param properties 事件的自定义属性，必须以在 DM Hub 中新建自定义事件时添加的自定义属性作为 key
 */
public static void track(final String eventId, JSONObject properties);

/**
 * 跟踪自定义客户事件
 *
 * @param eventId 在 DM Hub 中新建的自定义事件的事件 Id
 */
public static void track(final String eventId);

代码示例

private void sendTestEvent(int count) {
    try {
        JSONObject json = new JSONObject();
        json.put("text_attr1", "test_text");
        json.put("number_attr1", "test_number");
        json.put("amount_attr1", "test_amount");
        if (count < 0) {
            count = 40;
        }
        for (int i = 0; i < count; i++) {
            Log.i(TAG, "sendTestEvent ---> 发送第几次: " + (i + 1));
            DMHubSDK.track("c_sdk_test", json);
        }
    } catch (JSONException e) {
        e.printStackTrace();
    }
}

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

接口定义

/**
 * 跟踪进入视图事件
 *
 * @param viewName 视图的名称，客户时间轴上的显示为：'进入手机视图 ${viewName}'
 */
public static void trackOpenView(final String viewName);

/**
 * 跟踪离开视图事件
 *
 * @param viewName 视图的名称，客户时间轴上的显示为：'离开手机视图 ${viewName}'
 */
public static void trackExitView(final String viewName);

代码示例

public class YourActivity extends Activity {
    
    @Override
    protected void onResume() {
        super.onResume();
        
        DMHubSDK.trackOpenView("<viewName>");
    }

    @Override
    protected void onPause() {
        super.onPause();

        DMHubSDK.trackExitView("<viewName>");
    }
}

5.3 跟踪通知推送相关事件

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

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

5.3.1 跟踪 JPush 推送相关事件

接口定义

上报来自于 BroadcastReceiver 广播的推送事件，接收参数形式为 Intent。

/**
 * 当自定义的 JPush 广播接收器继承 BroadcastReceiver 接收来自 JPush 的广播时，
 * 调用该方法接收 Intent 数据，该方法会自动处理来自极光的action不同事件，进行对应事件上报。
 *
 * @param appKey JPush app key
 * @param intent 收到的广播的 intent
 */
public static void onJPushReceiveBroadcast(String appKey, final Intent intent);

上报来自于 JPushMessageReceiver 广播的推送事件，根据提供的接口回调，使用不同方法进行事件上报。以下方法不可和 onJPushReceiveBroadcast 同时使用，否则将产生多次同一事件上报。

使用以下方法需要将 SDK 升级到 3.0.10。

/**
 * 上报  registerId 注册推送事件
 *
 * 当自定义的 JPush 广播接收器使用 JPushMessageReceiver 接收来自 JPush 的广播时，
 * 需要在 onRegister 方法中调用 ，在第一次安装App时触发
 * 需要在 onConnected 方法中调用，在每次更新 registerId 后调用上报。
 * 
 * 需 SDK >= 3.0.10
 * 
 * 注：不可和 onJPushReceiveBroadcast 共用
 *
 * @param appKey   GeTui app key
 * @param registrationId 收到的 clientId
 */
public static void onJPushReceiveRegistrationId(final String appKey, final String registrationId);


/**
 * 上报 自定义消息 到达事件
 *
 * 当自定义的 JPush 广播接收器使用 JPushMessageReceiver 接收来自 JPush 的广播时，
 * 需要在 onMessage 方法中调用
 * 
 * 需 SDK >= 3.0.10
 * 
 * 注：不可和 onJPushReceiveBroadcast 共用
 *
 * @param messageId GTTransmitMessage 中携带的 CustomMessage.messageId
 * @param message   GTTransmitMessage 中携带的 CustomMessage.message
 * @param extra   GTTransmitMessage 中携带的 CustomMessage.extra
 */
public static void onJPushCustomerMessageArrived(final String messageId, String message, String extra);


/**
 * 上报 通知消息 到达事件
 *
 * 当自定义的 JPush 广播接收器使用 JPushMessageReceiver 接收来自 JPush 的广播时，
 * 需要在 onNotifyMessageArrived 方法中调用
 * 
 * 需 SDK >= 3.0.10
 * 
 * 注：不可和 onJPushReceiveBroadcast 共用
 *
 * @param messageId GTTransmitMessage 中携带的 CustomMessage.messageId
 * @param message   GTTransmitMessage 中携带的 CustomMessage.message
 * @param extra   GTTransmitMessage 中携带的 CustomMessage.extra
 */
public static void onJPushNotificationMessageArrived(final String messageId, String message, String extra);


/**
 * 上报 通知消息 打开事件
 *
 * 当自定义的 JPush 广播接收器使用 JPushMessageReceiver 接收来自 JPush 的广播时，
 * 需要在 onNotifyMessageOpened 方法中调用
 * 
 * 需 SDK >= 3.0.10
 *
 * 注：不可和 onJPushReceiveBroadcast 共用
 * 
 * @param messageId GTTransmitMessage 中携带的 CustomMessage.messageId
 * @param message   GTTransmitMessage 中携带的 CustomMessage.message
 * @param extra   GTTransmitMessage 中携带的 CustomMessage.extra
 */
public static void onJPushNotifyMessageOpened(final String messageId, String message, String extra);


/**
 * 上报 自定义消息 打开事件
 *
 * 自定义消息响应由开发者自行处理，如果自定义消息需要支持统计点击回执，在当业务上发生该自定义消息点击行为时，应
 * 调用该方法。
 * 
 * 需 SDK >= 3.0.10
 *
 * 注：不可和 onJPushReceiveBroadcast 共用，需要确保启用了 JPush Callback 开关，如：
 * 
 *  JPushInterface.setNotificationCallBackEnable(context, true)
 * 
 * @param messageId GTTransmitMessage 中携带的 CustomMessage.messageId
 * @param message   GTTransmitMessage 中携带的 CustomMessage.message
 * @param extra   GTTransmitMessage 中携带的 CustomMessage.extra
 */
public static void onJPushCustomerMessageOpened(final String messageId, String message, String extra);

代码示例

推送事件接收器如果是继承自 BroadcastReceiver 接收事件数据时：

public class YourJPushReceiver extends BroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
        String jpushAppKey = DMHubUtil.readConfig(context.getApplicationContext(), "JPUSH_APPKEY");
        DMHubSDK.onJPushReceiveBroadcast(jpushAppKey, intent);
    }
}

推送事件接收器如果是继承自 onJPushReceiveBroadcast 接收事件数据时：

public class YourJPushReceiver extends JPushMessageReceiver {
    
    @Override
    public void onRegister(Context context, String registrationId) {
        if(null != registrationId) {
            // 读取 极光推送 AppKey
            String jpushAppKey = DMHubUtil.readConfig(context.getApplicationContext(), "JPUSH_APPKEY");
            DMHubSDK.onJPushReceiveRegistrationId(jpushAppKey,registrationId);
        }
    }

    /**
     * 该动作可选，主要目的是为了当 registrationId 发生变更时，能及时更新。也可以在 Application onCreate启动时，同步一次。
     * 注：onRegister 的触发是第一次初始化JPush SDK 时，为了保证接入DMHub SDK 后还能重新获取到 registrationId，需要额外
     * 在启动时（连接时）重新上报下。
     */
    @Override
    public void onConnected(Context context, boolean isConnected) {
        String registrationId = JPushInterface.getRegistrationID(YourAppApplication.application);
        if(null != registrationId) {
            // 读取 极光推送 AppKey
            String jpushAppKey = DMHubUtil.readConfig(context.getApplicationContext(), "JPUSH_APPKEY");
            DMHubSDK.onJPushReceiveRegistrationId(jpushAppKey,registrationId);
        }
    }

    @Override
    public void onNotifyMessageArrived(Context context, NotificationMessage message){
        if(null != message) {
            DMHubSDK.onJPushNotificationMessageArrived(message.msgId,
                    message.notificationContent,
                    message.notificationExtras);
        }
    }

    @Override
    public void onNotifyMessageOpened(Context context, NotificationMessage message) {
        if(null != message) {
            DMHubSDK.onJPushNotifyMessageOpened(message.msgId,
                    message.notificationContent,
                    message.notificationExtras);
        }
    }

    @Override
    public void onMessage(Context context, CustomMessage customMessage) {
        if(null != customMessage) {
            DMHubSDK.onJPushCustomerMessageArrived(customMessage.messageId,
                    customMessage.message,
                    customMessage.extra);
        }
    }
    
}

注意：以上两种接收器 DMHubSDK 的事件上报方式，仅选择其中一种方式接入，如果两种都接入可能会造成重复发送客户事件。

5.3.2 跟踪 GeTui 推送相关事件

接口定义

/**
 * 在自定义的 GTIntentService 的 onReceiveClientId 方法中调用
 * @param appKey push的 appKey
 * @param clientId 收到的 clientId
 */
public static void onGeTuiReceiveClientId(String appKey, String clientId);

/**
 * 在自定义的 GTIntentService 的 onReceiveMessageData 方法中调用
 *
 * @param taskId    GTTransmitMessage 中携带的 taskId
 * @param messageId GTTransmitMessage 中携带的 messageId
 * @param payload   GTTransmitMessage 中携带的 payload
 */
public static void onGeTuiReceiveMessageData(final String taskId, final String messageId, final byte[] payload);

/**
 * 在自定义的 GTIntentService 的 onNotificationMessageArrived 方法中调用
 *
 * @param taskId    GTNotificationMessage 中携带的 taskId
 * @param messageId GTNotificationMessage 中携带的 messageId
 */
public static void onGeTuiNotificationMessageArrived(final String taskId, final String messageId);

代码示例

public class YourIntentService extends GTIntentService {

    @Override
    public void onReceiveClientId(Context context, String clientid) {
         String getuiPushAppKey = DMHubUtil.readConfig(context.getApplicationContext(), "GETUIPUSH_APPKEY");
        DMHubSDK.onGeTuiReceiveClientId(getuiPushAppKey, clientid);
    }

    @Override
    public void onReceiveMessageData(Context context, GTTransmitMessage msg) {
        String taskId = msg.getTaskId();
        String messageId = msg.getMessageId();
        byte[] payload = msg.getPayload();
        DMHubSDK.onGeTuiReceiveMessageData(taskId, messageId, payload);
    }

    @Override
    public void onNotificationMessageArrived(Context context, GTNotificationMessage gtNotificationMessage) {
        String taskId = gtNotificationMessage.getTaskId();
        String messageId = gtNotificationMessage.getMessageId();
        DMHubSDK.onGeTuiNotificationMessageArrived(taskId, messageId);
    }
}

6. 设置全局参数

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

例如下面的代码：

DMHubSDK.push("campaign", "8月促活");

7. 混淆规则

在工程的混淆规则文件中添加如下规则：

# DMHubSDK
-dontwarn com.convertlab.**
-keep class com.convertlab.** { *; }