Web转化数据API接入流程（旧链路）
目录
STEP1：账户配置授权
STEP2：创建数据源
STEP3：上报用户行为数据
STEP4：查看数据接入监测报表
1. 用户行为数据源和上报转化数据之间有什么关系
2. 上报行为如何自定义去重
3. 如何传自定义参数
4. 如何报下单金额，如何处理金额单位
5. 如何上报用户行为时间
6. 创建web数据源时，第二步需要选择半码，无码，还是全码
1. Marketing API不同类型账户请求授权结果
2. Marketing API上报的action_type，对应投放端的指标
3. 转化上报常用参数列表（action_param）
通过API进行Web数据接入适合内部归因逻辑较复杂，且开发能力强的广告主。
注：如果广告主分别通过eqq与mp平台投放广告，可以只选择一个平台进行数据接入。
二. 接入流程说明
↓
STEP2：创建数据源
↓
STEP3：上报用户行为数据
↓
STEP4：查看数据报表
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 创建Web用户行为数据源
用户行为数据源是Web用户行为数据的容器，只需要创建一次即可。后续需要将用户行为数据上报到用户行为数据源中。
可以在DMP系统的“数据接入”模块里创建Web用户行为数据源；或者调用接口 创建用户行为数据源 进行创建。
对于推广Web落地页而言，在腾讯广告推广时，每次点击都会生成一个 click_id，在跳转到落地页时，会将 click_id 作为参数传入对应的 URL 中。
当对应落地页的产生转化行为时，可以利用 API 将 click_id 和 转化类型（ActionType） 一并上报给腾讯广告，经过腾讯广告计算后，将最终数据呈现在投放端。
3.1 获取用户 click_id
获取落地页URL中的click_id，对于腾讯广告非微信流量为URL中的参数qz_gdt的值，对于微信流量为URL中的参数gdt_vid的值。
后续上报转化数据的时候click_id为必传值。
3.2 确定行为类型
在行为数据接口的action_type字段中，填写需要上报的转化行为类型。
完整转化行为参考 Action_type标准行为类型枚举
| 常用转化行为 | 行为类型(action_type) |
|---|---|
| 预约 | RESERVATION |
| 注册 | REGISTER |
| 咨询 | CONSULT |
| 下单 | COMPLETE_ORDER |
| 购买 | PURCHASE |
| 访问关键页面 | VIEW_CONTENT |
说明：当上报咨询行为时，请在 action_param 中标识具体的咨询行为： action_param 中的 key 填写 consult_type， value 填写 ONLINE_CONSULT / MAKE_PHONE_CALL / RESERVE_PHONE_NUMBER 分别表示网页咨询 / 电话咨询 / 电话回拨
如需上报转化价值，可在action_param里使用value字段：
| 参数名 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| value | integer | no | 转化行为的价值，如下单金额，购买金额。单位为分，100表示1元 |
3.3 获取创建时存储的数据源 ID
注：请先按照2.1内容完成数据源创建。
可以在DMP系统的“数据接入”模块里获取行为数据源ID；
或者调用接口 获取用户行为数据源，获取行为数据源的信息及数据接入的情况。
3.4 构造请求回传数据，需要确保回传成功
【构造数据上报请求前须了解】
Marketing API通用参数，完整说明参考 请求通用参数
| 名称 | 类型 | 必填 | 限制 | 描述 |
|---|---|---|---|---|
| access_token | string | 是 | 以Query Parameter方式在请求路径中传递。 | 授权令牌，完成 OAuth 2.0 授权后获得，参考 授权认证章节。 |
| timestamp | timestamp | 是 | 以Query Parameter方式在请求路径中传递。 | 当前的时间戳，单位为秒，允许客户端请求最大时间误差为300秒。MarketingAPI 所使用的时间戳，若无特殊说明，均为秒级时间戳MarketingAPI 所使用的时区为GMT+8，例如当时间戳为1494840119时，表示 2017-05-15 17:21:59 |
| nonce | string | 是 | 以Query Parameter方式在请求路径中传递。 | 随机字串标识，不超过32个字符，由调用方自行生成，需保证全局唯一性。 |
接口调用限制
| 类型 | 描述 |
|---|---|
| 接口功能 | 不同应用程序在接口功能上可能存在差异，由开发者创建应用的时候根据应用的使用场景进行选择 |
| 调用天频次 | 1、系统对每个应用程序调用每个接口都有调用天频次限制，不同应用等级下的调用次数不同，具体可通过应用程序管理页面了解 2、达到限制后，您当日将无法继续调用超限的接口，第二天可自动恢复正常>2、达到限制后，您当日将无法继续调用超限的接口，第二天可自动恢复正常 3、如需要调整限制可以联系您的运营接口人 |
| 调用分钟频次 | 1、系统对每个应用程序调用每个接口都有调用分钟频次限制，不同应用等级下的调用次数不同，具体可通过应用程序管理页面了解 2、达到限制后，您需要暂停对该接口的调用，5分钟后可自动恢复正常 3、如需要调整限制可以联系您的运营接口人 |
【构造数据上报请求】
通过用户行为数据上报接口上报用户行为数据。接口详情：用户行为数据上报接口 user_actions/add
上报请求示例：
|
上报预约数据示例，红色部分需要替换成对应的真实信息
|
|
curl -X POST
‘https://api.e.qq.com/v1.1/user_actions/add?access_token=<your_access_token>×tamp=<timestamp>&nonce=<nonce>‘ \
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“actions”: [
{
“url”: “<URL>“,
“action_time”: <action_timestamp>,
“action_type”: “RESERVATION”,
“trace”: {
“click_id”: “<CLICK_ID>“
}
}
]
}’
|
|
上报购买数据示例，红色部分需要替换成对应的真实信息
|
|
curl -X POST
‘https://api.e.qq.com/v1.1/user_actions/add?access_token=<your_access_token>×tamp=<timestamp>&nonce=<nonce>‘ \
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“actions”: [
{
“url”: “<URL>“,
“action_time”: <action_timestamp>,
“action_type”: “PURCHASE”,
“trace”: {
“click_id”: “<CLICK_ID>“
}
“action_param”:{
“value”: <purchase_value>
}
}
]
}’
|
上报成功应答示例：
|
{
“code”: 0,
“message”: “”
}
|
STEP4： 查看数据接入监测报表
有三中方式可以查看数据接入监测报表，任选其一即可：
1. 可以登录DMP系统(dmp.qq.com)，在“Web数据接入”模块下查看数据的接入情况，pv可视为成功的上报量。在DMP系统上，可以看到接入的pv，映射上的pv, 映射上的uv等信息；
2. 也可以通过调用Marketing API 获取用户行为数据源报表 接口，获取数据；
3. 也可以通过登录投放后台查看账户广告归因转化数据，建议隔天查看。
FAQ
1. 用户行为数据源和上报转化数据之间有什么关系
数据源是广告主所上报的一方数据的集合，广告主可以向创建好的数据源中上报数据、查看报表，或将数据源授权给其他账号。
用户行为数据源相当于承载某个APP用户行为数据的容器，针对一个APP，只需要创建一次即可（Android和iOS需要分成两个）。创建完成用户行为数据源后，再将转化数据上报到这个行为数据源中。
场景：多个推广账户推广同一个推广目标，通常仅需要在其中一个DMP中创建也Web数据源即可；
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>,
“url”: “<URL>”,
“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>,
“url”: “<URL>”,
}’
|
|
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“url”: “<URL>”,
}’
|
|
|
|
-H ‘Content-Type: application/json’ \
-d ‘{
“account_id”: “<your_account_id>“,
“user_action_set_id”: <your_user_action_set_id>,
“url”: “<URL>”,
}’
|
6. 创建web数据源时，第二步需要选择半码，无码，还是全码？
选择API上报数据时，忽略第二步，数据源创建完成即可。
附录
1. 特别说明· Marketing API不同类型账户请求授权结果
如果请求授权的是代理商帐号，代理商用开户 QQ 登录并同意授权，完成 OAuth 2.0 后应用获得access_token，该应用会获得当前代理商所有子客户的推广帐号的操作权限。
如果请求授权的是直客帐号，客户用开户 QQ 登录并同意授权，完成 OAuth 2.0 后应用获得 access_token，该用户会获得当前客户推广帐号的操作权限。
如果请求授权的是代理商子客户，用子客户的自理管理员 QQ（由代理商分配）登录并同意授权，完成 OAuth 2.0 后应用获得 access_token，该应用会获得当前子客户推广帐号的操作权限。
2. 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，表示上报的是商品页面浏览行为 |
