广点通转化 Android SDK 开发指引

SDK 信息

SDK名称：广点通转化 SDK
开发者：深圳市腾讯计算机系统有限公司
版本号：1.9.0
主要功能：用于广告分析、营销分析
合规使用说明：https://datanexus.qq.com/doc/develop/compliance/android/compliance_guide
个人信息处理规则：https://datanexus.qq.com/doc/develop/compliance/android/privacy_policy

1 前置条件

1.1 完成 SDK 接入流程文档阅读

查看 SDK 接入流程。

若应用尚未上架

创建数据源时可暂不填写 AppID，先正常创建数据源以便获取 SDK 接入密钥。待应用上架后请务必在数据源列表中补充 AppID 信息，否则数据源内无法正常接收数据。

1.2 SDK 要求的系统版本

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

2 接入开发

2.1 下载 SDK

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

2.2 导入SDK

这里以压缩包中的 GDTActionSDKDemo 示例程序导入 SDK 为例。

找到您的 App 工程下的 libs 文件夹，将下载到的 SDK 的 jar 包 GDTActionSDK.min.x.x.x.aar 拷贝到该目录下。
然后在项目根目录下面的 build.gradle 文件中，添加本地的 libs 目录作为本地仓库，如下所示。

repositories {
    flatDir {
        dirs 'libs'
    }
}

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

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

2.3 添加 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"/> <!-- 文件读取权限 -->

2.4 混淆配置

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

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

-keepclasseswithmembers class * {
    native <methods>;
}

2.5 初始化SDK

调用 GDTAction.init 方法完成 SDK 初始化。调用init方法不会采集个人信息，初始化完成后请尽快调用start方法启动SDK，并在合适时机上报转化行为数据。

下面以 GDTActionSDKDemo 工程为例进行说明。

2.5.1 初始化

找到您的 App 的 Application 类（这里以 GDTActionApplication 类为例），建议您在 onCreate() 方法中调用下面这段代码来初始化SDK。该接口仅进行初始化，不会获取个人信息。初始化相关的信息在 Logcat 会输出，日志TAG为gdt_action，初始化成功会打印日志 GDTAction初始化成功（sdkv: 1.x.x, sdkvc: xx），请开发者关注。

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.8.4版本起，必须先调用此init方法完成初始化后，才能调用GDTAction.logAction发送行为方法
    * @param context  Context上下文，必填
    * @param userActionSetId 您在 DataNexus 上获得的行为数据源ID，必填
    * @param appSecretKey 您在 DataNexus 上获得 secret_key ，必填
    * @param channel 您的渠道, 选填，默认腾讯渠道包填写ChannelType.CHANNEL_TENCENT
    * @param channelId 您的自定义渠道ID, 选填
    */
    GDTAction.init(this, "yourUserActionSetID", "yourAppSecretKey", "yourChannel", "yourChannelId");
  }
}

注意：

数据源ID和 secret_key 设置：通过 GDTAction.init 初始化方法设置，请参考如下“调用位置”，“调用顺序”。

调用位置：GDTAction.init 初始化方法，请在用户同意隐私协议以后尽早调用。
调用顺序：GDTAction.init 初始化方法，必须在 GDTAction.logAction 行为上报方法的调用之前成功调用，否则 GDTAction.logAction 不会上报行为。

渠道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>

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

隐私信息控制开关：您可以通过 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;
  }

}

示例

GDTAction.setPrivateController(new PrivateController() {

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

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

});

重写 getDevImei() 之前需要先设置 isCanUsePhoneState() 。

2.5.2 设置软 ID

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

GDTAction.setUserUniqueId("yourUserUniqueId"); // 参数是用户软ID，比如游戏账号ID

2.5.3 设置ANID采集开关

GDTAction.setAnidEnable(false); // 关闭采集，默认为开启状态

2.6 启动SDK

请在调用init方法后尽快调用start方法，否则影响设备号填充率，降低归因成功率。（start 为 v1.8.9 新增方法）

GDTAction.start(); // 启动SDK，允许SDK采集个人信息

2.7 按行为清单埋点上报数据

2.7.1 上报启动应用行为

找到 Activity 类（这里以 GDTActionLauncherActivity 类为例）的 onResume() 方法，调用下面的代码来上报 START_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 示例。）

2.7.2 预置行为

TICKET（心跳）
ENTER_FOREGROUND（APP进入前台）
ENTER_BACKGROUND（APP退到后台）
PAUSE（暂停页面）
RESUME（恢复页面）

以上 5 种行为无需您手动上报。

2.7.3 预定义上报方法

在 App 内发生转化行为时，可以调用预定义上报方法或通用上报方法上报行为数据，传入行为类型名称和行为参数。每个预定义上报方法包含若干个行为参数（优化广告投放所需参数），建议优先使用预定义上报方法，若预定义上报方法无法满足上报需求时，则使用通用上报方法。

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 添加支付渠道是否成功	添加支付渠道时

2.6.4 通用上报方法

方法名	功能
logAction(String actionType, JSONObject actionParam)	行为上报方法 @param actionType : 行为类型名，系统支持的actionName如下 a @param actionParam: 行为参数，actionParam格式如下 b

a. 行为类型（ActionType）

全量行为枚举值。

b. 行为参数（ActionParam）

行为参数是 "Key-Value" 类型；Key 只可以为String类型，只能包含字母、数字和下划线，必须以字母开头，长度不能超过255； Value 可以是 String/Number/Boolean/JSONArray 其中一种，当 Value 为 JSONArray 时，它的元素只能为 String/Number/Boolean 中的一种，且所有元素必须是同一个类型。
广告主在调用上报 START_APP 行为时，SDK 会自主判断此次行为是否为激活行为。若广告主需要自主控制上报激活启动行为时，可以在 ActionParam 中设置 audience_type 的 Key，Value 为1。当带有该标识的启动行为上报时，我们会默认此次行为为老客户的应用启动行为。
广告主在上报时需要做自定义去重时可以在 ActionParam 中设置 outer_action_id 的 Key，value 为任意自定义如订单号的字符串作为自定义去重 id ，系统会根据该id进行去重。
当用户需要指定上报用户次日留存指标时，可以在上报 START_APP 行为时，在 ActionParam 中设置 length_of_stay 的 key ，值为1，系统会指定该次上报为留存数据。

分行业上报行为类型和行为参数规范

为优化广告投放效果，不同行业需上报特定的行为类型，且需携带对应行为的相关参数。详见应用规范。

2.6.5 上报结果确认

SDK会以info级别的日志输出上报的结果，日志的TAG为gdt_action。以下为常见的日志输出：

如果数据上报失败，会有LogAction failed xxxx的日志输出
如果数据上报成功，会有LogAction success xxxx的日志输出

3 SDK 主要 API

com.qq.gdt.action.GDTAction

方法名	功能
init(Context context, String userActionSetId, String appSecretKey)	初始化方法（可选），建议在App的入口调用一次 @param context : App的上下文信息，一般是Application/Activity @param userActionSetId : 您在 DataNexus 获得的行为数据源ID @param appSecretKey : 您在 DataNexus 数据接入获得的行为数据源 secret_key ID
init(Context context, String userActionSetId, String appSecretKey, ChannelType channel, String channelId)	初始化方法（可选），建议在App的入口调用一次 @param context : App的上下文信息，一般是Application/Activity @param userActionSetId : 您在 DataNexus 数据接入获得的行为数据源ID @param appSecretKey : 您在 DataNexus 数据接入获得的行为数据源 secret_key ID @param channel : 您的渠道信息，只能从com.qq.gdt.action.ChannelType枚举类中选择已定义好的渠道 @param channelId : 您的渠道ID
logAction(String actionType)	行为上报接口 @param actionType : 行为类型，分为两类，一类是在 DataNexus 上定义的标准行为类型，具体见com.qq.gdt.action.ActionType类；另一类是您自己自定义的行为类型，可以传入一个字符串类型的参数，要求：这个字符串只能包含字母、数字和下划线，必须以字母开头，长度不能超过64
logAction(String actionType, JSONObject actionParam)	行为上报接口，支持上报行为参数 @param actionType : 行为类型，详细描述同上 @param actionParam : 行为参数，行为参数是"Key-Value"类型，Key只可以为String类型，只能包含字母、数字和下划线，必须以字母开头，长度不能超过64，且不得以amsreserved开头（SDK内置参数将以它开头）；Value可以是String/Number/Boolean/JSONArray其中一种，当Value为JSONArray时，它的元素只能为String/Number/Boolean中的一种，且所有元素必须是同一个类型
setUserUniqueId(String userUniqueId)	设置用户软ID @param userUniqueId : 用户软ID
setAnidEnable(boolean status)	设置ANID采集开关 @param status : 开关状态
getClickID(Context context)	获取 clickID（仅支持游戏行业 & APK包有上传到腾讯广告安卓应用管理平台 & 采用V2签名的应用） @param context : App的上下文信息，一般是Application/Activity
getChannelID(Context context)	获取渠道包标识，在腾讯广告安卓应用管理平台添加渠道包时输入的标识，支持V1和V2签名 @param context : App的上下文信息，一般是Application/Activity

com.qq.gdt.action.ActionType

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

FAQ

Q：SDK上报数据接口（a.gdt.qq.com/sdk）返回 code 码 51000

A：当开发者使用模拟器运行App通过SDK上报数据时，服务端会对上报的数据做检测，判断该数据为无效数据，接口返回 code 码 51000。

Q：按照以上步骤接入SDK后，抓包工具未发现上报数据接口请求记录

A：检查本地电脑是否有安装网络拦截工具，如果有，请查看是否有拦截SDK上报数据接口，或者直接关闭网络拦截工具并重新运行App查看SDK上报数据接口是否请求正常。

该内容是否有帮助？

广点通转化 Android SDK 开发指引

1 前置条件​

1.1 完成 SDK 接入流程文档阅读​

1.2 SDK 要求的系统版本​

2 接入开发​

2.1 下载 SDK​

2.2 导入SDK​

2.3 添加 SDK 权限​

2.4 混淆配置​

2.5 初始化SDK​

2.5.1 初始化​

2.5.2 设置软 ID​

2.5.3 设置ANID采集开关​

2.6 启动SDK​

2.7 按行为清单埋点上报数据​

2.7.1 上报启动应用行为​

2.7.2 预置行为​

2.7.3 预定义上报方法​

com.qq.gdt.action.ActionUtils​

2.6.4 通用上报方法​

a. 行为类型（ActionType）​

b. 行为参数（ActionParam）​

2.6.5 上报结果确认​

3 SDK 主要 API​

com.qq.gdt.action.GDTAction​

com.qq.gdt.action.ActionType​

FAQ​