接口文档SDK业务专题开发者工具

转化数据接入SDK方案

一. SDK方案优势

1. 数据更稳定更实时回传不受上报服务器环境影响,80%的数据不一致问题都是因为广告主上报服务器不稳定造成的数据波动。
2. 数据稳定性和及时性对oCPA的影响oCPA优化的是转化回流后的转化成本,转化数据回流的及时性和稳定性对oCPA控制转化成本影响很大,如果数据回流不稳定,模型将需要更多的时间稳定;如果数据回流不及时,一些实时控制转化成本的策略就不会生效,控制成本的难度会更大。
3. 数据追踪更完善
支持用QAID方案,减少设备号无法收集的case,增加数据追踪准确性。当前Device ID获取的限制问题:
Apple系统在iOS10之后,如果用户开启了【限制广告追踪】的开关,则无法获取到IDFA;
Android 6.0以下可以获取到设备的IMEI号,6.0以上需要弹框用户授权电话权限后才可以获取到。
目前流量侧(XQ、XS、联盟)获取不到设备号的比例大概有5%左右,且比例还会不断提升,可能导致您的成本偏高。SDK可以通过构建QAID设备标识,来补充获取不到IDFA/IMEI时的设备识别问题,让您的效果数据追踪更准确,oCPA模型更准确。


二. SDK 接入方式

流程说明:
 创建DMP行为数据源

下载并导入SDK

添加SDK所需权限

SDK初始化

上报行为数据
1. 创建DMP行为数据源
SDK 接入方案需要先创建APP用户行为数据源,用户行为数据源是APP用户行为数据的容器,每个APPID创建一个行为数据源。

登录进入DMP系统(de.qq.com,腾讯广告广告主与微信公众平台广告主相同),

    创建数据源:如图所示。无需appID即可创建数据源

    注:针对未上架的ios app创建数据源,详情参考 https://de.qq.com/news-ios/

创建好数据源之后,您会看到DMP给您的App数据源分配了两个ID,一个是行为数据源ID(UserActionSetID),另一个是数据源接入密钥(AppSecretKey)

2. 下载sdk与接入文档,开发同学根据场景部署SDK

SDK 平台
资源和说明文档下载
更新日志下载
Android 1.6.9 SDK
点击下载更新日志
iOS 2.0.1 SDK
点击下载更新日志
后续步骤(下载并导入SDK,添加SDK所需权限,SDK初始化,上报行为数据)请查看接入文档

完整转化行为参考 Action_type标准行为类型枚举

常用转化行为
行为类型(action_type)
说明
激活
ACTIVATE_APP
30天内第一次打开APP
注册
REGISTER
用户点击广告后注册成为APP的新用户
下单
COMPLETE_ORDER
用户点击下单生成订单
购买
PURCHASE
用户完成付费
加入购物车
ADD_TO_CART
用户将商品加入购物车
次日留存
START_APP
用户激活后第二天打开APP的行为
注:广告主开发者需要在APP启动时上报APP启动行为,SDK会自主判断这次行为是激活行为还是启动行为。
上报APP启动需要找到Activity类(这里以GDTActionLauncherActivity类为例)的onResume()方法,调用下面的代码来上报App启动行为。
GDTAction.logAction(ActionType.START_APP);
// 传入的actionType参数必须是ActionType.START_APP


三. 联调工具

保证数据接入的正确性(仅支持白名单用户,需要找运营开权限)
联调第一步——补充联调信息

1. 提示在该优化目标下您需要联调的行为;
2. 配置信息部分供优化师截图给开发确认配置信息;
3. 您可根据实际情况补充联调信息,如渠道包-建议根据投放的实际情况选择对应的渠道包进行联调;
保证数据接入的正确性(仅支持白名单用户,需要找运营开权限)
联调第二步——打开检测页面

扫描二维码后,在手 Q 浏览器上打开如下页面,需要用户获取自己的设备号并数据,生成“AMS 联调测试广告”;

●Android 手机可以通过拨号输入#06#获取 IMEI 号;

●iOS 手机可以通过 appstore 下载 MyIDFA 获取 IDFA 号;

联调第三步——生成联调广告:
广告生成大约需要 2 分钟,请耐心等待;

●出现联调广告后,对于 APP 场景若依赖 SDK 回传:

您需要点击“AMS 联调测试广告”,下载并安装应用,并且触发您想要检测的行为发生;您需要根据点击数据接收情况来看您的点击接收情况;同时在触发行为后查看 SDK 的上报情况;

联调第四步——检测转化上报:

1. 若未配置点击转发,将不会进行此步检测;

2. 系统会依次检测是否进行了点击下发和数据上报,其中,数据上报会检测您选择的优化目标;

3. 若您进行了操作,但未检测到,可能有以下原因,请您仔细检查:

    ●未向指定的地址发送数据
    ●上报的行为类型不是您联调的行为类型
    ●回调的 CallbackURL 有误,无法解析。


四. SDK接入的常见问题

1. 用户行为数据源和上报转化数据之间有什么关系

数据源是广告主所上报的一方数据的集合,广告主可以向创建好的数据源中上报数据、查看报表,或将数据源授权给其他账号。
用户行为数据源相当于承载某个APP用户行为数据的容器,针对一个APP,只需要创建一次即可(Android和iOS需要分成两个)。创建完成用户行为数据源后,再将转化数据上报到这个行为数据源中。
场景:多个推广账户推广同一个APP,通常仅需要在其中一个DMP中创建一次APP数据源即可

2. 如何判断SDK上报数据是否成功

(1) 启动android studio, log会输出“GDTAction初始化成功”字样
(2) SDK会校验包名:安装SDK的包和上传到应用宝的包,如果包名不一致,会返回报错 ‘51000 package name check failed’
(3) 广告主侧技术人员抓包测试,正确部署的情况下会有a.gdt.qq.com请求发出,因为调用了logActin方法
(4) 监测DMP后台是否有数据传入
在DMP系统(http://de.qq.com)的“数据接入”模块,对应的行为数据源可以看到上报成功次数统计

3. 同时推广微信及非微信流量,SDK是否通用

SDK可以通用。
另外请注意,使用了SDK上报则不建议再使用API进行数据上报,防止数据被重复上报,导致归因结果和实际转化行为数据不符。

4. 上报行为如何去重

对于需要做自定义去重的广告主,可以在调用logAction(actionType, actionParams)上报行为时,在actionParams中传入keyouter_action_id的参数,如去重付费人数,具体参考 附录-2

5. 客户如何判断自己接的SDK是否是旧版

抓包请求时,请求domain为a.gdt.qq.com为新版SDK;请求domain为t.gdt.qq.com为旧版SDK

6. 安卓接入时,有渠道包的情况下,是否只需要接主包就可以了,渠道包不用接sdk

理论上推荐所有包都接入SDK。实际投放中如果广告推广使用的是渠道包,可以仅在渠道包中部署SDK(注:仅在渠道包中部署SDK会有遗漏转化行为的可能出现。例如用户点击广告后没有第一时间下载app,而是后续30天内自行前往应用商店下载并激活。安装腾讯广告归因逻辑这一激活应该被诡异给此广告点击,但是如果仅在渠道包部署了SDK,会统计不到此次激活)

7. APP能否同时接入sdk和api,该如何从api切换到sdk?

可以同时接入SDK和API,但我们不推荐这样来做。
目前平台在归因时,只有激活数据会去重,其他行为数据如果同时使用API和SDK上传,会造成三个月后月上报重复,影响数据准确性。如果必须要同时使用API和SDK,要确保一个转化行为仅被其中一种方案进行上报。
 
从API切换到SDK没有特殊要求,切换过程中需要确保一个转化行为仅被其中一种方案进行上报。

8. 以下描述适用于广告主非拉新广告场景:

在切换过程中,广告主需要上线发布带有SDK版本的APP(新版APP),但同时没部署SDK版本的APP(老版APP)也并行存在;相应的对于用户来说,会有部分用户在使用没有部署SDK版本的APP(老版本APP)和部署了SDK版本的APP(新版APP)。
对于使用老版APP的这些用户的转化行为数据,如果需要上报的话,依然需要通过API上报;对于已经使用了部署SDK的新版APP的用户,SDK会根据部署的情况自动上报对应的行为。这里需要开发者对于用户使用的APP带来的转化行为进行对应版本的监控识别,来判断哪些需要通过API进行上报。

9. API切换SDK后激活行为新老用户判定问题

适用于广告主想自主判断是激活行为还是打开行为的场景。
一般情况下,在调用SDK logAction(ActionType.START_APP) 上报行为时,SDK会自主判断这次行为是激活行为还是启动行为。
若广告主是从API切换到SDK做数据上报,可能会需要自主确定这次行为是激活还是启动行为,这时可以在行为参数 actionParam 中添加一个参数AUDIENCE_TYPE,具体代码如下:

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会按照通用的逻辑,自主判断这次行为是激活行为还是启动行为。


五. 附录


1. 常用标准转化行为说明(action_type)

典型用户行为
DMP标准行为(action_type)
标准行为名称
行为参数
投放端效果栏
投放端指标
是否支持作为OCPA优化目标
用户点击广告后,到达商品详情页页面发生的浏览行为
VIEW_CONTENT
关键页面访问
object=product
APP效果栏
商品页浏览量
已支持
用户直接下载APP后第一次打开
ACTIVATE_APP
激活应用
APP效果栏
激活总量
已支持
用户点击广告后,到达关键页面发生的浏览行为
VIEW_CONTENT
关键页面访问
APP效果栏
关键页面访问量
暂不支持
用户下载APP并在激活后完成注册
REGISTER
注册
APP效果栏
注册量
已支持
用户将商品加入购物车
ADD_TO_CART
加入购物车
APP效果栏
加入购物车量
已支持
用户在线上或线下实际完成付费购买行为并成交
PURCHASE
购买
可选填value
APP效果栏
付费行为量
已支持
用户进行业务申请(如贷款、信用卡等,金融类广告主常用)
APPLY
申请
APP效果栏
完件量
暂不支持
APP内下单
COMPLETE_ORDER
下单
可选填value
APP效果栏
下单量
已支持
用户激活APP后第二个自然日打开
START_APP
次日留存
length_of_stay=1 (必填)
APP效果栏
次日留存量
已支持
用户在页面上发起网页咨询
CONSULT
网页咨询
consult_type=ONLINE_CONSULT
网页栏
网页咨询量
支持
用户在页面上发起电话咨询
CONSULT
电话咨询
consult_type=MAKE_PHONE_CALL
网页栏
电话直拨量
支持
用户在页面上留资后,广告主进行电话回拨并成功
CONSULT
电话回拨
consult_type=RESERVE_PHONE_NUMBER
网页栏
电话回拨量
暂不支持
用户申请并通过审核后,拿到的贷款额度
CREDIT
授信
APP栏
授信量
暂不支持
用户通过授信,拿到贷款额度后,提现到银行卡
WITHDRAW_DEPOSITS
提现
APP栏
授信量
暂不支持
用户在游戏中创建角色(游戏客户专用)
CREATE_ROLE
创角
APP栏
创角量
暂不支持
用户在游戏中完成授权(游戏客户专用)
ACCREDIT
授权
APP栏
授权量
暂不支持
用户在游戏中完成新手教程
TUTORIAL_FINISH
完成新手教程
APP栏
完成新手教程量
暂不支持

2. 转化常用参数列表(action_param)

参数名
类型
描述
是否必填
备注
代码示例
value
int
订单价值
单位:分
用户发生购物行为时,体现转化带来的价值。
// 用户发生购物行为时,可以用GDTAction.logAction上报用户的这次行为,并将价格等行为参数一起带上
JSONObject actionParam = new JSONObject();
actionParam.put(“value”, 6800);
GDTAction.logAction(ActionType.PURCHASE, actionParam);
LENGTH_OF_STAY
int
停留天
单位:天
可以在调用logAction(ActionType.START_APP, actionParams)时,在actionParams中传入keylength_of_stay的参数,取值为1
SDK版本为Android 1.5.0和iOS 1.1.0,不需要传入
JSONObject actionParam = new JSONObject();
actionParam.put(ActionParam.Key.LENGTH_OF_STAY, 1); // 传入值为1的length_of_stay参数
GDTAction.logAction(ActionType.START_APP, actionParam); // 上报START_APP行为时带上该参数
OUTER_ACTION_ID
string
自定义去重参数
在调用logAction(actionType, actionParams)上报行为时,在actionParams中传入keyouter_action_id的参数
JSONObject actionParam = new JSONObject();
actionParam.put(ActionParam.Key.OUTER_ACTION_ID, “yourOuterActionId”); // 传入outer_action_id
actionParam.put(“value”, 3400);
GDTAction.logAction(ActionType.PURCHASE, actionParam); // 此处以上报付费这个行为为例
 

3. SDK主要方法说明

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
logAction(String actionType)
行为上报接口
@param actionType : 行为类型,分为两类,一类是在DMP上定义的标准行为类型,具体见com.qq.gdt.action.ActionType类;另一类是您自己自定义的行为类型,可以传入一个字符串类型的参数,要求:这个字符串只能包含字母、数字和下划线,必须以字母开头,长度不能超过255
logAction(String actionType, JSONObject actionParam)
行为上报接口,支持上报行为参数
@param actionType : 行为类型,详细描述同上
@param actionParam : 行为参数,行为参数是”Key-Value”类型,Key只可以为String类型,只能包含字母、数字和下划线,必须以字母开头,长度不能超过255;Value可以是String/Number/Boolean/JSONArray其中一种,当Value为JSONArray时,它的元素只能为String/Number/Boolean中的一种,且所有元素必须是同一个类型
 

4. 具体场景示例说明

付费行为
// 用户发生购物行为时,可以用GDTAction.logAction上报用户的这次行为,并将价格等行为参数一起带上
JSONObject actionParam = new JSONObject();
actionParam.put(“value”, 6800); //转化价值单位为分,整型
GDTAction.logAction(ActionType.PURCHASE, actionParam);
次日留存行为
// 用户次日留存,可以用GDTAction.logAction上报用户的这次行为,并将参数一起带上
JSONObject actionParam = new JSONObject();
actionParam.put(ActionParam.Key.LENGTH_OF_STAY, 1); //必填
actionParam.put(ActionParam.Key.CLAIM_TYPE, 4); //选填,次留关联到激活
GDTAction.logAction(ActionType.START_APP, actionParam);