APP转化数据API接入流程（旧链路）
目录
STEP1：账户配置授权
STEP2：创建数据源
STEP3：上报用户行为数据
STEP4：查看数据报表
1. 用户行为数据源和上报转化数据之间有什么关系
2. 上报行为如何自定义去重
3. 如何传自定义参数
4. 如何上报激活时间/下单时间
5. 如何上报下单金额，如何处理金额的单位
1. Marketing API不同类型账户请求授权结果
2. Marketing API上报的action_type，对应投放端的指标
3. 转化上报常用参数列表（action_param）
4. 设备标识获取方式
一. Marketing API方案介绍
通过API进行APP数据接入适合内部归因逻辑较复杂，且开发能力强的广告主。广告主有两种方案可以选择：
● 方案一：适合自身数据处理能力较强的广告主
广告主先将转化数据与获取到的点击数据进行关联，然后将关联到的转化数据上报给腾讯广告，腾讯广告进行归因处理。选择此方案的广告主需要在上报数据前，先进行点击转发配置。
● 方案二：适合数据处理能力较弱，或通过第三方对接数据的广告主
广告主将所有数据上报给腾讯广告，腾讯广告与点击数据进行关联，并归因处理。
注：如果广告主分别通过eqq与mp平台投放广告，可以只选择一个平台进行数据接入。
↓
STEP2：创建数据源
↓
STEP3：上报用户行为数据
↓
STEP4：查看数据报表
STEP1： Marketing API账户配置授权
1.1 注册开发者和创建应用
开发者可以是客户（代理商、直客、子客）本身，也可以是第三方的技术公司；一个企业主体只能对应创建一个开发者。
创建应用程序的目的是为了获取所需接口的调用权限，不需要重复创建同样接口权限的应用程序。
详情参考：
注册开发者和创建应用
1.2 授权认证
指开发者申请操作腾讯广告投放账号的过程，一个开发者的应用程序可以获得多个投放帐号的授权。
1.2.1 如何通过 OAuth 2.0 获得 access_token
首先，完成OAuth2.0认证后并获得authorization_code
获得 authorization_code 需要完成 OAuth 2.0 的认证。调用 OAuth 2.0 授权页面的URL形如：
|
https://developers.e.qq.com/oauth/authorize?client_id=123456&redirect_uri=https://www.example.com |
其中：
client_id: 开发者创建的应用程序的唯一标识id，必填，可通过【应用程序管理页面】查看
redirect_uri: 回调地址，由开发者自行提供和定义（地址主域需与开发者创建应用程序时登记的回调主域一致），用于跳转并接收
authorization_code，必填，该字段需要做UrlEncode，确保后续跳转正常
state: 开发者自定义参数，可用于验证请求有效性或者传递其他自定义信息，回调的时候会原样带回，可选
scope: 授权的能力范围，可选，不传时表示授权范围为当前应用程序所拥有的所有全部权限
account_type: 授权用的账号类型，可选，包括QQ号和微信号，不传时默认为QQ号
然后，开发团队使用authorization_code 获得 access_token 和 refresh_token
1.2.2 定期刷新access_token
获得 access_token 后，可以调用Marketing API进行转化数据上报。
一旦 access_token 失效，将无法调用接口。access_token 和 refresh_token 的有效期可以通过 oauth/token 接口的返回字段获取，默认情况下 access_token 和 refresh_token 的有效期如下：
access_token：默认有效期为24小时
refresh_token：默认有效期为30天
注：每次刷新access_token时， refresh_token会自动续期。
详情内容参考：
授权认证流程
2.1 创建APP用户行为数据源
用户行为数据源是APP用户行为数据的容器，针对一个APP，只需要创建一次即可（Android和iOS需要分开创建）。后续需要将用户行为数据上报到用户行为数据源中。
可以在DMP系统（dmp.qq.com）的“数据接入”模块里创建APP用户行为数据源；
或者调用接口 创建用户行为数据源 进行创建。
STEP3：上报用户行为数据
3.1 点击转发配置（针对方案一）
如果广告主决定选用方案一上报数据（广告主先将转化数据与获取到的点击数据进行关联，然后将关联到的转化数据上报给腾讯广告，腾讯广告进行归因处理），需要先进行点击转发配置。
点击转发配置步骤：
登录 腾讯广告官网 → 投放管理平台 → 工具箱 → 效果分析 → 点击监测
如您需要获取账户内某个APP对应的广告产生的点击数据，则选择对应的移动平台，并填写应用ID和feedback URL。如果您想获取更多点击转发维度信息，请联系运营协助申请。
3.2 获取用户标识
a. 获取设备号信息并加密
【Android】
获取IMEI信息，IMEI原始信息为14或15位，由数字+字母或纯数字组成；
加密方式：IMEI 号(需转小写)，进行 md5 以后得到的 32 位全小写的字符串。
示例：原始 IMEI 号：354649050046412
加密之后：b496ec1169770ea274a2b4f42ca4fb71
【iOS】
需要获取IDFA信息，IDFA原始信息为36位，由数字+字母串+『-』分隔符组成；
加密方式：IDFA码(需转大写)，进行 md5 以后得到的 32 位全小写的字符串。
示例：原始IDFA码：1E2DFA89-496A-47FD-9941-DF1FC4E6484A
加密之后：40c7084b4845eebce9d07b8a18a055fc
b. 如果想更准确的归因，可以额外上传以下非必填字段。
|
名称
|
是否必填
|
类型
|
描述
|
|
|
user_id
|
||||
|
hash_imei
|
Android 必填
iOS 不填
|
string
|
IMEI 设备号保持小写，进行 md5 编码
字段长度为 32 字节
|
|
|
hash_idfa
|
iOS 必填
Android 不填
|
string
|
IDFA 设备号保持大写，进行 MD5 编码
字段长度为 32 字节
|
|
|
hash_phone
|
选填
|
string
|
电话号码直接 MD5 编码，如 md5(13500000000)
字段长度为 32 字节
|
|
|
|
|
|
移动安全联盟（简称MSA）制定的匿名设备标识符，保留原始值，不需要MD5编码。具体OAID介绍以及最新覆盖厂商范围请详见MSA官网
|
|
|
hash_android_id
|
Android选填
iOS不填
|
string
|
对 android_id 进行 MD5 编码
字段长度为 32 字节
|
|
|
trace
|
click id
|
|
string
|
可以通过feedback url回传的点击数据里匹配获取
|
附：MSA网站获取oaid具体步骤：
1. 登录MSA官网；
2. 注册成为网站会员；
3. 进入移动智能设备标识公共服务平台模块；
4. 拉至页面最下方，阅读开发者说明，并下载安装SDK；
3.3 确定行为类型
在行为数据接口的action_type字段中，填写需要上报的转化行为类型。
完整转化行为参考 Action_type标准行为类型枚举
|
常用转化行为
|
行为类型(action_type)
|
说明
|
|
激活
|
ACTIVATE_APP
|
30天内第一次打开APP
|
|
注册
|
REGISTER
|
用户点击广告后注册成为APP的新用户
|
|
下单
|
COMPLETE_ORDER
|
用户点击下单生成订单
|
|
购买
|
PURCHASE
|
用户完成付费
|
|
加入购物车
|
ADD_TO_CART
|
用户将商品加入购物车
|
|
次日留存
|
START_APP
|
用户激活后第二天打开APP的行为
|
如需上报转化价值，可在action_param里使用value字段：
|
参数名
|
类型
|
是否必填
|
说明
|
|
value
|
integer
|
no
|
转化行为的价值，如下单金额，购买金额。单位为分，100表示1元
|
如果需要上报次日留存数据，需要在action_param里传入字段length_of_stay=1
|
用户行为说明
|
DMP标准行为(action_type)
|
标准行为名称
|
行为参数 action_param
|
|
用户激活APP后第二个自然日打开
|
START_APP
|
次日留存
|
length_of_stay=1
|
3.4 获取数据源 ID
按照STEP2内容完成数据源创建后，可以在DMP系统（dmp.qq.com）的“数据接入”模块里获取行为数据源ID，或者调用接口 获取用户行为数据源，获取行为数据源的信息及数据接入的情况。
3.5 构造请求上报行为数据，需要确保请求成功
【构造数据上报请求前须了解】
Marketing API通用参数，完整说明参考 请求通用参数
|
名称
|
类型
|
必填
|
限制
|
描述
|
|
access_token
|
string
|
是
|
以Query Parameter方式在请求路径中传递。
|
|
|
timestamp
|
timestamp
|
是
|
以Query Parameter方式在请求路径中传递。
|
当前的时间戳，单位为秒，允许客户端请求最大时间误差为300秒。MarketingAPI 所使用的时间戳，若无特殊说明，均为秒级时间戳MarketingAPI 所使用的时区为GMT+8，例如当时间戳为1494840119时，表示 2017-05-15 17:21:59
|
|
nonce
|
string
|
是
|
以Query Parameter方式在请求路径中传递。
|
随机字串标识，不超过32个字符，由调用方自行生成，需保证全局唯一性。
|
接口调用限制
|
|
|
|
接口功能
|
不同应用程序在接口功能上可能存在差异，由开发者创建应用的时候根据应用的使用场景进行选择
|
|
调用天频次
|
1、系统对每个应用程序调用每个接口都有调用天频次限制，不同应用等级下的调用次数不同，具体可通过应用程序管理页面了解
2、达到限制后，您当日将无法继续调用超限的接口，第二天可自动恢复正常
3、如需要调整限制可以联系您的运营接口人
|
|
调用分钟频次
|
1、系统对每个应用程序调用每个接口都有调用分钟频次限制，不同应用等级下的调用次数不同，具体可通过应用程序管理页面了解
2、达到限制后，您需要暂停对该接口的调用，5分钟后可自动恢复正常
3、如需要调整限制可以联系您的运营接口人
|
【构造数据上报请求】
通过用户行为数据上报接口上报用户行为数据。接口详情：
用户行为数据上报接口 user_actions/add
示例：
|
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“oaid”: “<oaid>” //Android选填，推荐使用
}’
|
|
click_idhash_imei参数更换为 hash_idfa，另外iOS不支持hash_android_id）
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“actions”: [
{
“action_time”: <action_timestamp>,
“user_id”: {
“hash_imei”: “<MD5_hash_imei>“,
“oaid”: “<oaid>” //Android选填，推荐使用
},
“action_type”: “ACTIVATE_APP”
}
]
}’
|
|
）
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“actions”: [
{
“action_time”: <action_timestamp>,
“user_id”: {
“hash_imei”: “<MD5_hash_imei>“,
“oaid”: “<oaid>” //Android选填，推荐使用
},
“action_type”: “PURCHASE”,
“action_param”:{
“value”: <purchase_value>
}
}
]
}’
|
|
上报 Android 数据示例，红色部分需要替换成对应的真实信息（上报iOS激活数据需要将 user_id 中参数更换为 hash_idfa）
|
|
curl
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“actions”: [
{
“action_time”: <action_timestamp>,
“user_id”: {
“hash_imei”: “<MD5_hash_imei>“,
“oaid”: “<oaid>” //Android选填，推荐使用
},
“action_param”:{
“length_of_stay”:
}
}
]
}’
|
上报成功应答示例：
|
{
“code”: 0,
“message”: “”
}
|
对应的DMP行为数据源可以看到请求成功次数统计：
有三中方式可以查看数据接入监测报表，任选其一即可：
- 登录DMP系统，在“数据接入”模块下查看App数据的接入情况，pv可视为成功的上报量；
- 通过调用Marketing API 获取用户行为数据源报表 接口，获取数据；
- 通过登录投放后台查看账户广告归因转化数据，建议隔天查看。
FAQ
1. 用户行为数据源和上报转化数据之间有什么关系
数据源是广告主所上报的一方数据的集合，广告主可以向创建好的数据源中上报数据、查看报表，或将数据源授权给其他账号。
用户行为数据源相当于承载某个APP用户行为数据的容器，针对一个APP，只需要创建一次即可（Android和iOS需要分成两个）。创建完成用户行为数据源后，再将转化数据上报到这个行为数据源中。
场景：多个推广账户推广同一个APP，通常仅需要在其中一个DMP中创建一个APP数据源即可；
2. 上报行为如何自定义去重
Marketing API可以在actions内加入external_action_id参数进行自定义去重。
| 参数名称 | 参数名称 | 描述 |
|---|---|---|
| external_action_id | string | 字段长度最小1字节，最大长度255字节，且只能为数字，字母，下划线，连接符组成。 去重标识，平台会基于user_action_set_id，external_action_id>去重标识，平台会基于user_action_set_id，external_action_id 和action_type三个字段做去重 ，如果历史上报数据中存在某条数据的这三个字段与当前上报数据完全一样的，则当前数据会被过滤掉 |
|
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“external_action_id”: “f9efca36a3c30e1cf28170d86ecbf5e9_complete_order_1492991000_< ACCOUNT_ID>_< USER_ACTION_SET_ID>”,
}’
|
|
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
}’
|
|
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
}’
|
|
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
}’
|
附录
一. Marketing API不同类型账户请求授权结果：
如果请求授权的是代理商帐号，代理商用开户 QQ 登录并同意授权，完成 OAuth 2.0 后应用获得access_token，该应用会获得当前代理商所有子客户的推广帐号的操作权限。
如果请求授权的是直客帐号，客户用开户 QQ 登录并同意授权，完成 OAuth 2.0 后应用获得 access_token，该用户会获得当前客户推广帐号的操作权限。
如果请求授权的是代理商子客户，用子客户的自理管理员 QQ（由代理商分配）登录并同意授权，完成 OAuth 2.0 后应用获得 access_token，该应用会获得当前子客户推广帐号的操作权限。
二. Marketing API 上报的action_type，对应投放端的指标
|
典型用户行为
|
DMP标准行为（action_type） |
标准行为名称
|
数据源类型 |
行为参数
|
投放端效果栏 |
投放端指标
|
是否支持作为OCPA优化目标
|
OCPA优化目标 |
|---|---|---|---|---|---|---|---|---|
| 落地页下单 | COMPLETE_ORDER | 下单 | WEB | 无 | 网页栏 | 下单量 | 支持 | 下单 |
| 落地页填单留资 | RESERVATION | 预约 | WEB | 无 | 网页栏 | 表单预约量 | 支持 | 表单预约 |
| 用户在落地页上留资后下载APP，在APP内注册登录/跳转到网页注册页面，完成网站用户注册 | REGISTER | 注册 | WEB | 无 | 网页栏 | 注册量 | 支持 | 注册 |
| 用户在线上或线下实际完成付费购买行为并成交 | PURCHASE | 购买 | WEB | 无 | 网页栏 | 付费行为量 | 支持 | 付费 |
| 用户通过在一级页面上点击按钮，跳转到广告主指定二级页面并浏览 | VIEW_CONTENT | 关键页面访问 | WEB | object=product | 网页栏 | 商品页面浏览量 | 支持 | 商品页面浏览量 |
| 用户直接下载APP后第一次打开/在落地页上留资后下载APP后第一次打开 | ACTIVATE_APP | 激活应用 | ANDROID/IOS | 无 | APP效果栏 | 激活总量 | 支持 | 激活 |
| 用户在页面上发起网页咨询 | CONSULT | 网页咨询 | WEB | consult_type=ONLINE_CONSULT | 网页栏 | 网页咨询量 | 支持 | 网页咨询 |
| 用户在页面上发起电话咨询 | CONSULT | 电话咨询 | WEB | consult_type=MAKE_PHONE_CALL | 网页栏 | 电话直拨量 | 支持 | 电话咨询 |
| 用户访问自有落地页 | VIEW_CONTENT | 关键页面访问 | WEB | 无 | 网页栏 | 自有网页关键页面浏览量 | 支持 | 关键页面浏览 |
| 用户在落地页上下单，并且订单商品已发货 | DELIVER | 订单发货 | WEB | 无 | 网页栏 | 订单发货量 | 支持 | 发货 |
| 用户下载APP后在APP内注册 | REGISTER | 注册 | ANDROID/IOS | 无 | APP效果栏 | 注册量 | 支持 | 注册 |
| 用户在APP内将商品加入购物车 | ADD_TO_CART | 加入购物车 | ANDROID/IOS | 无 | APP效果栏 | 加入购物车量 | 支持 | 加入购物车 |
| 用户在APP内完成付费购买行为并成交 | PURCHASE | 购买 | ANDROID/IOS | 无 | APP效果栏 | 付费量 | 支持 | 付费 |
| 用户访问APP内落地页 | VIEW_CONTENT | 关键页面访问 | ANDROID/IOS | 无 | APP效果栏 | 关键页面浏览量 | 支持 | 关键页面浏览 |
| 用户在APP内通过在一级页面上点击按钮，跳转到广告主指定二级页面并浏览 | VIEW_CONTENT | 关键页面访问 | ANDROID/IOS | object=product | APP效果栏 | 商品页浏览量 | 支持 | 商品详情页浏览 |
| APP内下单 | COMPLETE_ORDER | 下单 | ANDROID/IOS | 无 | APP效果栏 | 下单量 | 支持 | 下单 |
| 用户激活APP后第二天打开应用 | START_APP | 启动应用 | ANDROID/IOS | length_of_stay=1 | APP效果栏 | 次日留存量 | 支持 | 次日留存 |
| 用户在APP内首次完成付费购买行为并成交 | PURCHASE | 购买 | ANDROID/IOS | 无 | APP效果栏 | 首次付费行为量 | 支持 | 首次付费 |
| 会员购买 | PURCHASE | 购买 | APP/WEB | 无 | 网页/APP | 首次会员购买量/ 会员购买量 | 支持 | 首此会员购买量 |
|
|
|
|
|
|
|
|
value
|
int
|
订单价值，单位：分
|
否
|
|
体现转化带来的价值，在上报COMPLETE_ORDER或PURCHASE行为时可选填
|
|
consult_type
|
string
|
咨询类型
|
否
|
^.{0,200}$
|
目前包括三种类型：MAKE_PHONE_CALL（电话咨询）、ONLINE_CONSULT（网页咨询）和RESERVE_PHONE_NUMBER（电话回拨）
|
|
object
|
string
|
行为对象
|
否
|
^.{0,200}$
|
在上报VIEW_CONTENT行为时参数填写为object=product，表示上报的是商品页面浏览行为
|
|
length_of_stay
|
int
|
停留天数，单位：天
|
否
|
|
在上报START_APP作为留存行为时必填。length_of_stay=1，表示上报的是次日留存行为。
|
|
设备号
|
描述
|
原始数据获取
|
加密方式
|
示例：原值
|
示例：MD5后
|
|
IMEI
|
（1）Android版本 < 6.0，只需要READ_PHONE_STATE静态权限（安装App时即可获取到该权限），即可通过系统API TelephonyManager#getDeviceId API获取准确值；
（2）6.0 <= Android版本 <= 9.0，READ_PHONE_STATE升级为动态权限，安装App时不会获得该权限，需要在App运行时用户在弹窗确认授权后才可以获取；
（3）Android版本 >= 10.0，设备不可变ID的隐私保护得到进一步升级，需要READ_PRIVILEGED_PHONE_STATE权限才可以获取IMEI，而该权限只有系统级别的应用才可以获得，因此一般App无法获取到IMEI。
|
TelephonyManager tm = (TelephonyManager) context.getSystemService(Context.TELEPHONY_SERVICE);
deviceId = tm.getDeviceId();
android版本>=10不获取
|
对IMEI设备号转成小写，再进行md5编码，再小写，32位
md5(imei.toLowerCase()).toLowerCase()
|
868049039501257
|
8d3ebd3654fb46a2832296669cf1b536
|
|
IDFA
|
目前iOS系统主流的广告获取设备标识符方式
用户可开启、关闭，每次切换会改变为新的取值。 10以下的版本关闭时也能取到唯一值, >=10的iOS版本关闭时取到的值为00000000000 ；系统大版本升级（如11 到 12） IDFA也会发生变化
|
|
IDFA 设备号保持大写，进行 md5 编码，再小写，32位
md5(idfa.toUpperCase()).toLowerCase()
|
|
|
|
Android ID
|
（1）Android版本 < 8.0，不需要任何权限即可使用系统API（Settings.System.getString(getContentResolver(), Settings.System.ANDROID_ID)）获取准确值；
（2）Android版本 >= 8.0，应用签名、用户（即系统上的用户账号）和设备的每个组合都具有唯一的 ANDROID_ID值，即使系统升级也不变。
|
Settings.System.getString(context.getApplicationContext().getContentResolver(),
Settings.System.ANDROID_ID);
|
对 android_id 进行 md5 编码，再小写
md5(androidId).toLowerCase()
|
f40c5cf5100f9be3
|
1995c8f7cec20632797539b68555752f
|
