Android iOS Unity JS API Media API 常见问题

集成版 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, 选填
  }
}

注意:

4.2 上报App启动

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

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

注意:

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。以下为常见的几种日志输出:

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

6. SDK主要API

方法名 功能
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

这个类里面定义了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 商品推荐,动态创意客户直接传算好的推荐结果时使用

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

方法名 参数 建议调用时机
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);

7.2 行为上报自定义去重(高级功能,非必选)

对于需要做自定义去重的广告主,可以在调用logAction(actionType, actionParams)上报行为时,在actionParams中传入keyouter_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这个参数。

Copyright © 1998 - 2020 Tencent Inc. All Rights Reserved.
腾讯公司 版权所有 | 加入优量汇