接入文档

前置条件

请在 DataNexus -<数据接入>-<数据源>中新建数据源，参考[新建数据源]。

1. 下载和导入广点通转化 SDK

登录 DataNexus 获取 SDK，下载 Android SDK 的压缩包，压缩包中的GDTActionSDK.min.x.x.x.aar文件为您的App需要嵌入的SDK，压缩包中的GDTActionSDKDemo是我们提供的SDK接入示例工程。注意，本文档提到的GDTActionSDK.min.x.x.x.aar中的x.x.x指的是您实际下载的SDK版本号，如1.8.2。

导入 Android Studio

1. 找到您的 App 工程下的libs文件夹，将下载到的SDK的jar包GDTActionSDK.min.x.x.x.aar拷贝到该目录下。

2. 然后在项目根目录下面的build.gradle文件中，添加本地的libs目录作为本地仓库，如下所示。

repositories {
    flatDir {
        dirs 'libs'
    }
}

3. 最后在 Android Studio 中找到您的App所在的module目录，修改它的build.gradle文件，在 dependencies 下面添加 SDK 的依赖，如下所示。

...
dependencies {
    implementation(name: 'GDTActionSDK.min.1.8.2', ext: 'aar')
}
...

如果您使用的Android Studio版本低于3.0，那么请按照下面的方式修改App所在Module的build.gradle文件。

...
dependencies {
    compile files('libs/GDTActionSDK.min.1.8.2.aar')
}
...

2. 添加SDK需要的权限

找到您的 App 所在 module 的目录，修改AndroidManifest.xml文件，添加权限：

<uses-permission android:name="android.permission.INTERNET" /> <!-- 允许联网 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/> <!-- 检测联网方式，区分设备当前网络是2G、3G、4G还是WiFi -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/> <!-- 获取设备标识，标识用户 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/> <!-- 文件读取权限 -->

3. SDK要求的系统版本

SDK要求最低系统版本为API 14（Android 4.0）。

4. 混淆配置

如果您开启了混淆，请加入下面的配置：

-dontwarn com.qq.gdt.action.**
-keep class com.qq.gdt.action.** {*;}
-keep public class com.tencent.turingfd.sdk.**

-keepclasseswithmembers class * {
native <methods>;
}

5. SDK初始化

SDK的初始化分两步，第一步是调用GDTAction.init方法来初始化SDK；第二步是调用GDTAction.logAction(ActionType.START_APP);来上报App启动行为。下面以GDTActionSDKDemo工程为例进行说明。

5.1 初始化（可选）

找到您的 App 的 Application 类（这里以GDTActionApplication类为例），建议您在onCreate()方法中调用下面这段代码来初始化 SDK，初始化相关的信息在Logcat会输出，请开发者关注。

package com.qq.gdt.action.demo;

import android.app.Application;
import com.qq.gdt.action.GDTAction;

public class GDTActionApplication extends Application {

  @Override
  public void onCreate() {
    super.onCreate();
    // ...
    /**
    * 从1.7.6版本起，如果没有指定数据源来上报数据并查看的需求，并且没有渠道号的需求，可以不调用此方法，直接调用    GDTAction.logAction发送行为方法
    * @param context  Context上下文
    * @param userActionSetId 您在DMP上获得的行为数据源ID，选填
    * @param appSecretKey 您在DMP上获得AppSecretKey，选填
    * @param channel 您的渠道, 选填，默认腾讯渠道包填写ChannelType.CHANNEL_TENCENT
    * @param channelId 您的自定义渠道ID, 选填
    */
    GDTAction.init(this, "yourUserActionSetID", "yourAppSecretKey", "yourChannel", "yourChannelId");
  }
}

注意：

1.数据源ID和AppSecretKey设置：从1.7.6版本起，如果没有指定数据源来上报数据并查看的需求，您可以选填这两个字段（需要接入完整的GDTActionSDK.min.1.x.x.aar依赖包），如果需要调用初始化方法，请参考如下“1.1调用位置”，“1.2 调用顺序”

• 调用位置：GDTAction.init初始化方法，建议在Application类的onCreate方法中或者用户同意隐私协议以后尽早调用。（从1.3.0版本开始，SDK的GDTAction.init接口不再需要获取动态权限，只需要确保调用位置正确。如果没有在指定位置调用init方法，SDK会输出错误日志。）
• 调用顺序：GDTAction.init初始化方法，必须在GDTAction.logAction行为上报方法的调用之前成功调用，否则GDTAction.logAction不会上报行为。

2.渠道ID设置：您可以通过GDTAction.init方法传入渠道ID（ "yourChannelId"），也可以通过在AndroidManifest.xml文件meta-data中通过gdt_action_channel_id字段进行配置渠道ID

<application>
   <meta-data
        android:name="gdt_action_channel_id"
        android:value="yourChannelId" />
</application>

3.多进程： 目前SDK已支持多进程，在任意一个进程初始化即可，无需多个进程重复初始化（需要接入完整的GDTActionSDK.min.1.x.x.aar依赖包）

4.隐私信息控制开关：您可以通过GDTAction.setPrivateController方法传入自定义的隐私信息开关，目前支持IMEI的开关和设置

public abstract class PrivateController {`

  /**
   * 是否允许SDK主动使用手机硬件参数，如：imei
   *
   * @return true可以使用，false禁止使用。默认为true
   */
  public boolean isCanUsePhoneState() {
      return true;
  }

  /**
   * 当isCanUsePhoneState=false时，可传入imei信息，转化sdk使用您传入的imei信息
   *
   * @return imei信息
   */
  public String getDevImei() {
      return null;
  }

}

4.1. 示例

GDTAction.setPrivateController(new PrivateController() {

  @Override
  public boolean isCanUsePhoneState() {
    return false;
  }

  @Override
  public String getDevImei() {
    return "yourimei";
  }

});

注意：重写getDevImei()之前需要先设置isCanUsePhoneState()

5.2 上报 App 启动

找到Activity类（这里以GDTActionLauncherActivity类为例）的onResume()方法，调用下面的代码来上报App启动行为。

GDTAction.logAction(ActionType.START_APP); // 传入的actionType参数必须是ActionType.START_APP

注意：

• 如果您的App适配了Android6.0（API >= 23），调用logAction时，需要处理Android6.0动态权限的兼容问题。具体做法是，先检查App是否获得了android.permission.READ_PHONE_STATE权限，如果获得了这项权限，可以直接调用上面这段代码上报App启动行为；如果没有获得权限，那么可以调用requestPermissions方法来向用户申请权限（建议获得android.permission.READ_PHONE_STATE权限，上报数据会更准确，不强制要求）。在我们SDK的Demo工程中有相应示例。
• SDK要求在Activity的onResume方法中，而不是onCreate方法中去上报App启动行为，是因为当用户按下home键使应用退到后台，再恢复到前台时，可能不会执行onCreate方法。
• 为确保激活、启动行为的准确上报，请务必在App的入口Activity的onResume方法中都调用GDTAction.logAction(ActionType.START_APP)这段代码。（入口Activity是指AndroidManifest.xml中action为android.intent.action.MAIN，category设置为android.intent.category.LAUNCHER的Activity，具体可以参考Demo示例。）

5.3 设置软ID

设置用户软ID，可以和数据源进行关联

GDTAction.setUserUniqueId("yourUserUniqueId"); // 参数是用户软ID

6. 上报行为数据

在 App 内发生转化行为时（如某一个Button组件的onClick(View view)方法），可以调用下面的代码上报行为数据。

// 用户发生购物行为时，可以用GDTAction.logAction上报用户的这次行为，并将价格等行为参数一起带上
JSONObject actionParam = new JSONObject();
actionParam.put("value", 6800);
actionParam.put("name", "Pixel 2 XL");
GDTAction.logAction(ActionType.PURCHASE, actionParam);

上报数据后，您可以登录DMP系统，在App数据接入页面下查看您App数据的接入情况。

特别重要：SDK会以info级别的日志输出上报的行为和参数，日志的TAG名称为gdt_action。以下为常见的几种日志输出：

• 如果SDK未进行初始化，会有GDTAction未进行初始化，请先调用GDTAction的init方法成功初始化SDK后，再调用其他数据上报方法！的日志输出
• 如果数据上报失败，会有LogAction failedXXX的日志输出
• 如果数据上报成功，会有LogAction successXXX的日志输出，一定要看到此日志才代表行为数据上报成功

关于行为类型（actionType）和行为参数（actionParam）的类型，在《SDK主要API》这一节有详细说明。

7. SDK 主要 API

• com.qq.gdt.action.GDTAction

方法名	功能
init(Context context, String userActionSetId, String appSecretKey)	初始化方法（可选），建议在App的入口调用一次 @param context : App的上下文信息，一般是Application/Activity @param userActionSetId : 您在DMP数据接入获得的行为数据源ID @param appSecretKey : 您在DMP数据接入获得的行为数据源Secret ID
init(Context context, String userActionSetId, String appSecretKey, ChannelType channel, String channelId)	初始化方法（可选），建议在App的入口调用一次 @param context : App的上下文信息，一般是Application/Activity @param userActionSetId : 您在DMP数据接入获得的行为数据源ID @param appSecretKey : 您在DMP数据接入获得的行为数据源Secret ID @param channel : 您的渠道信息，只能从com.qq.gdt.action.ChannelType枚举类中选择已定义好的渠道 @param channelId : 您的渠道ID
logAction(String actionType)	行为上报接口 @param actionType : 行为类型，分为两类，一类是在DMP上定义的标准行为类型，具体见com.qq.gdt.action.ActionType类；另一类是您自己自定义的行为类型，可以传入一个字符串类型的参数，要求：这个字符串只能包含字母、数字和下划线，必须以字母开头，长度不能超过64
logAction(String actionType, JSONObject actionParam)	行为上报接口，支持上报行为参数 @param actionType : 行为类型，详细描述同上 @param actionParam : 行为参数，行为参数是"Key-Value"类型，Key只可以为String类型，只能包含字母、数字和下划线，必须以字母开头，长度不能超过64，且不得以ams_reserved_开头（SDK内置参数将以它开头）；Value可以是String/Number/Boolean/JSONArray其中一种，当Value为JSONArray时，它的元素只能为String/Number/Boolean中的一种，且所有元素必须是同一个类型
setUserUniqueId(String userUniqueId)	设置用户软ID @param userUniqueId : 用户软ID

• com.qq.gdt.action.ActionType

这个类里面定义了DMP当前版本支持的标准行为类型，除了这些行为以外，如果您需要上报自定义行为，可以直接给logAction(String actionType)方法的actionType参数传入一个字符串即可。 更多标准actionType可以参考开发者官网文档，新增行为类型不需要升级SDK。

常量名	值	含义
START_APP	START_APP	应用启动
PAGE_VIEW	PAGE_VIEW	页面浏览
REGISTER	REGISTER	注册
VIEW_CONTENT	VIEW_CONTENT	内容浏览
CONSULT	CONSULT	咨询
ADD_TO_CART	ADD_TO_CART	加入购物车
PURCHASE	PURCHASE	付费购买
SEARCH	SEARCH	搜索
ADD_TO_WISHLIST	ADD_TO_WISHLIST	加入收藏
INITIATE_CHECKOUT	INITIATE_CHECKOUT	开始结算
COMPLETE_ORDER	COMPLETE_ORDER	下单
DOWNLOAD_APP	DOWNLOAD_APP	下载应用
RATE	RATE	评分
RESERVATION	RESERVATION	预订
SHARE	SHARE	分享
APPLY	APPLY	申请，用于金融广告主的申请贷款、开卡等
CLAIM_OFFER	CLAIM_OFFER	领取卡券，用于web落地页领取卡券等优惠信息的行为
NAVIGATE	NAVIGATE	导航，用于web落地页点击跳转到地图的行为
PRODUCT_RECOMMEND	PRODUCT_RECOMMEND	商品推荐，动态创意客户直接传算好的推荐结果时使用

• com.qq.gdt.action.ActionUtils

这个类中预定义了一些行为事件上报接口，例如登录、注册、游戏升级等，接入方可以在恰当的时机调用这些接口。

方法名	参数	建议调用时机
onRegister(String method, boolean success)	@param method 注册方式，可以是任意可唯一标识注册方式的值；如注册方式为手机号：method = "Mobile" QQ号注册：method = "QQ"等 @param success 是否注册成功	注册完成时
onLogin(String method, boolean success)	@param method 同onRegister方法 @param success 是否登录成功	登录完成时
onBindAccount(String method, boolean success)	@param method 同onRegister方法 @param success 是否绑定成功	绑定账号时
onQuestFinish(String id, String type, String name, int number, String desc, boolean success)	@param id 事件标识符 @param type 事件类型 @param name 事件名称 @param number 第几个任务/事件 @param desc 事件描述 @param success 事件是否完成	完成关键事件（如新手教学）时
onCreateRole(String role)	@param role 游戏角色名称	创建游戏角色时
onUpdateLevel(int level)	@param level 升级后的等级	游戏升级时
onShare(String channel, boolean success)	@param channel 可用于区分分享渠道的任意字符串，例如分享到微信朋友圈 channel = "WeChatCircle" @param success 是否分享成功	分享时
onRateApp(float value)	@param value 用户给出的评分值	用户对App评分时
onViewContent(String type, String name, String id)	@param type 内容/商品类型，如"装备"、"皮肤"等 @param name 内容/商品名称 @param id 内容/商品的标识符	查看内容/商品详情时
onAddToCart(String type, String name, String id, int number, boolean success)	@param type 商品类型如“装备”、“皮肤” @param name 商品名称 @param id 商品标识符 @param number 商品数量 @param success 加入购物车是否成功	加入购物车时
onCheckout(String type, String name, String id, int number, boolean isVirtualCurrency, String virtualCurrencyType, String currency, boolean success)	@param type 商品类型如"装备"、"皮肤" @param name 商品名称 @param id 商品标识符 @param number 商品数量 @param isVirtualCurrency 是否使用虚拟货币 @param virtualCurrencyType 虚拟货币类型，如"钻石"、"金币"等 @param currencyType 真实货币类型，ISO 4217代码，如："CNY" @param success 提交购买/下单是否成功	提交购买/下单时
onPurchase(String type,String name, String id, int number, String channel, String currency, int value, boolean success)	@param type 商品类型如"装备"、"皮肤" @param name 商品名称 @param id 商品标识符 @param number 商品数量 @param channel 支付渠道名，如支付宝、微信等 @param currency 真实货币类型，ISO 4217代码，如："CNY" @param value 本次支付的真实货币的金额，单位分 @param success 支付是否成功	用户支付时
onAddPaymentChannel(String channel, boolean success)	@param channel 支付渠道名，如支付宝、微信等 @param success 添加支付渠道是否成功	添加支付渠道时

注意：

ActionUtils中的方法封装了GDTAction.logAction，对于同一个行为不要同时调用ActionUtils.XXX和GDTAction.logAction

8. 其他注意事项

8.1 从API切换到SDK上报（高级功能，非必选）

一般情况下，在调用logAction(ActionType.START_APP)上报行为时，SDK会自主判断这次行为是激活行为还是启动行为。

若广告主是从API切换到SDK做数据上报，可能会需要控制这次行为是激活还是启动行为，这时可以在行为参数actionParam中添加一个参数，具体代码如下：

JSONObject actionParam = new JSONObject();
actionParam.put(ActionParam.Key.AUDIENCE_TYPE, ActionParam.Value.AUDIENCE_TYPE_USED);
GDTAction.logAction(ActionType.START_APP, actionParam);

• 如果AUDIENCE_TYPE为AUDIENCE_TYPE_USED，SDK会认为这次行为是老客户的启动行为，而不是新用户的激活行为。

• 如果AUDIENCE_TYPE为AUDIENCE_TYPE_NEW，SDK会按照通用的逻辑，自主判断这次行为是激活行为还是启动行为。

8.2 行为上报自定义去重（高级功能，非必选）

对于需要做自定义去重的广告主，可以在调用logAction(actionType, actionParams)上报行为时，在actionParams中传入key为outer_action_id的参数，具体代码如下：

JSONObject actionParam = new JSONObject();
actionParam.put(ActionParam.Key.OUTER_ACTION_ID, "yourOuterActionId"); // 传入outer_action_id
GDTAction.logAction(ActionType.COMPLETE_ORDER, actionParam); // 此处以上报下单这个行为为例

SDK内部会自动处理outer_action_id这个参数并将它从actionParams中移除，广告主也不会在DMP-Web页面上的行为参数中看到这个outer_action_id这个参数。

8.3 支付回调逻辑处理

为了避免因为支付回调延时而导致的付费数据缺失，建议开发者在用户支付成功后，采用轮询支付结果的方式决定是否调用腾讯SDK进行付费上报。

具体方案如下： 首先，在用户付款时，使用以下逻辑处理支付行为：客户端拉起支付 > 拉起支付的5分钟内每10秒查询一次支付结果 > 查询到支付成功并调用腾讯SDK进行上报；若超过5分钟仍未查询到支付成功的回调，则在下次启动时，客户端的归因上报模块再次查询上次失败的订单，如果查询到支付成功则上报。