集成版 SDK 转化归因数据接入使用说明文档
1. 添加SDK需要的权限
使用 SDK 前请联系运营人员获取：行为数据源ID（UserActionSetID）和 AppSecretKey。
找到您的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.ACCESS_WIFI_STATE" /> <!-- 获取MAC地址，和设备标识一起作为用户标识 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/> <!-- 获取设备标识，标识用户 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/> <!-- 文件读取权限 -->
2. SDK要求的系统版本
SDK要求最低系统版本为API 14（Android 4.0）。
3. 混淆配置
如果您开启了混淆，请加入下面的配置：
-dontwarn com.qq.gdt.action.**
-keep class com.qq.gdt.action.** {*;}
-keepclasseswithmembers class * {
native <methods>;
}
4. SDK初始化
SDK的初始化分两步，第一步是调用GDTAction.init方法来初始化SDK；第二步是调用GDTAction.logAction(ActionType.START_APP);来上报App启动行为。下面以GDTActionSDKDemo工程为例进行说明。
4.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();
// ...
//GDTAction.init(this, "yourUserActionSetID", "yourAppSecretKey"); // 第一个参数是Context上下文;第二个参数是您在DMP上获得的行为数据源ID;第三个参数是您在DMP上获得AppSecretKey
GDTAction.init(this, "yourUserActionSetID", "yourAppSecretKey", "youChannel", "youChannelId"); // 第一个参数是Context上下文;第二个参数是您在DMP上获得的行为数据源ID;第三个参数是您在DMP上获得AppSecretKey;第四个参数是您的渠道, 选填，默认腾讯渠道包填写ChannelType.CHANNEL_TENCENT；第五个参数是您的渠道ID, 选填
}
}
注意：
- 1.调用位置：
GDTAction.init初始化方法，建议在Application类的onCreate方法中或者用户同意隐私协议以后尽早调用。（从1.3.0版本开始，SDK的GDTAction.init接口不再需要获取动态权限，只需要确保调用位置正确。如果没有在指定位置调用init方法，SDK会输出错误日志。） - 2.调用顺序：
GDTAction.init初始化方法，必须在GDTAction.logAction行为上报方法的调用之前成功调用，否则GDTAction.logAction不会上报行为。
4.2 上报App启动
找到Activity类（这里以GDTActionLauncherActivity类为例）的onResume()方法，调用下面的代码来上报App启动行为。
GDTAction.logAction(ActionType.START_APP); // 传入的actionType参数必须是ActionType.START_APP
注意：
- 1.如果您的App适配了Android6.0（API >= 23），调用
logAction时，需要处理Android6.0动态权限的兼容问题。具体做法是，先检查App是否获得了android.permission.READ_PHONE_STATE权限，如果获得了这项权限，可以直接调用上面这段代码上报App启动行为；如果没有获得权限，那么可以调用requestPermissions方法来向用户申请权限（建议获得android.permission.READ_PHONE_STATE权限，上报数据会更准确，不强制要求）。在我们SDK的Demo工程中有相应示例。 - 2.SDK要求在Activity的
onResume方法中，而不是onCreate方法中去上报App启动行为，是因为当用户按下home键使应用退到后台，再恢复到前台时，可能不会执行onCreate方法。 - 3.为确保激活、启动行为的准确上报，请务必在App的入口
Activity的onResume方法中都调用GDTAction.logAction(ActionType.START_APP)这段代码。（入口Activity是指AndroidManifest.xml中action为android.intent.action.MAIN，category设置为android.intent.category.LAUNCHER的Activity，具体可以参考Demo示例。）
4.3 设置软ID
设置用户软ID，可以和数据源进行关联
GDTAction.setUserUniqueId("yourUserUniqueId"); // 参数是用户软ID
5. 上报行为数据
在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》这一节有详细说明。
6. 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
7. 其他注意事项
7.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会按照通用的逻辑，自主判断这次行为是激活行为还是启动行为。
7.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这个参数。