开发文档

Web转化数接入API方案

Marketing API方案
- 1.MarketingAPI账户配置授权
  - 1.1注册开发者和创建应用
  - 1.2授权认证
- 2.数据上报
  - 2.1 创建Web用户行为数据源
  - 2.2 上报用户行为数据

微信 MP OPEN API
- 1.注册成为开发者
- 2.数据上报
  - 2.1 创建Web数据源
  - 2.2 回传数据

FAQ
附录

Marketing API方案

适用于腾讯广告平台投放带来的转化数据回传对接。

1. Marketing API账户配置授权

1.1 注册开发者和创建应用

开发者可以是客户（代理商、直客、子客）本身，也可以是第三方的技术公司；一个企业主体只能对应创建一个开发者。

创建应用程序的目的是为了获取所需接口的调用权限，不需要重复创建同样接口权限的应用程序。

详情参考：

注册开发者和创建应用

1.2 授权认证

指开发者申请操作腾讯广告投放账号的过程，一个开发者的应用程序可以获得多个投放帐号的授权。

1.2.1 如何通过 OAuth 2.0 获得 access_token

Step 1：完成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号

Step 2：开发团队使用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. 数据上报

对于推广Web落地页而言，在腾讯广告推广时，每次点击都会生成一个 click_id，在跳转到落地页时，会将 click_id 作为参数传入对应的 URL 中。

当对应落地页的产生转化行为时，可以利用 API 将 click_id 和转化类型（ActionType）一并上报给腾讯广告，经过腾讯广告计算后，将最终数据呈现在投放端（e.qq.com）。

2.1 创建Web用户行为数据源

用户行为数据源是Web用户行为数据的容器，只需要创建一次即可。后续需要将用户行为数据上报到用户行为数据源中。

可以在DMP系统（de.qq.com）的“数据接入”模块里创建Web用户行为数据源；或者调用接口 创建用户行为数据源 进行创建。

2.2 上报用户行为数据

2.2.1 获取用户 click_id

获取落地页URL中的click_id，对于腾讯广告非微信流量为URL中的参数qz_gdt的值，对于微信流量为URL中的参数gdt_vid的值。

后续上报转化数据的时候click_id为必传值。

2.2.2 确定行为类型

在行为数据接口的action_type字段中，填写需要上报的转化行为类型。

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

常用转化行为	行为类型(action_type)	说明
预约	RESERVATION
注册	REGISTER
咨询	CONSULT	请在 action_param 中标识具体的咨询行为： action_param 中的 key 填写 consult_type， value 填写 ONLINE_CONSULT/MAKE_PHONE_CALL/RESERVE_PHONE_NUMBER 分别表示网页咨询/电话咨询/电话回拨
下单	COMPLETE_ORDER
购买	PURCHASE
访问关键页面	VIEW_CONTENT

如需上报转化价值，可在action_param里使用value字段：

参数名	类型	是否必填	说明
value	integer	no	转化行为的价值，如下单金额，购买金额。单位为分，100表示1元

2.2.3 获取创建时存储的数据源 ID

注：请先按照2.2.1内容完成数据源创建。

可以在DMP系统（de.qq.com）的“数据接入”模块里获取行为数据源ID；

或者调用接口 获取用户行为数据源，获取行为数据源的信息及数据接入的情况。

2.2.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、达到限制后，您当日将无法继续调用超限的接口，第二天可自动恢复正常 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>&timestamp=<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>&timestamp=<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>&timestamp=<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> } } ] }’

上报购买数据示例，红色部分需要替换成对应的真实信息

curl -X POST \

‘https://api.e.qq.com/v1.1/user_actions/add?access_token=<your_access_token>&timestamp=<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”: “” }

注：“url”参数为转化行为发生页面的url，小程序可在路径前增加”http://www.” 或直接填写 “http://www.qq.com“

2.3 查看数据接入监测报表

上报完成数据后，可以登录DMP系统(de.qq.com)，在Web数据接入模块下查看数据的接入情况；在DMP系统上，可以看到接入的pv，映射上的pv, 映射上的uv等信息。登录投放后台查看账户广告归因转化数据。也可以通过调用Marketing API 获取用户行为数据源报表 接口，获取数据。

微信 MP OPEN API

适用于微信MP平台投放带来的转化数据回传对接。

1. 注册成为开发者

在 MP 投放端（https://mp.weixin.qq.com/）的『开发』—『基本配置』中注册成为开发者，并获取开发者ID、密码和access_token。具体步骤如下

1.1 进入注册页面，点击左边栏，『开发』下『基本配置』。同意《微信公众平台开发者服务协议》后，点击『成为开发者』；

1.2 获取开发者密码。点击“重置”按钮：

1.3 弹窗提示，点击“确定重置”按钮：

1.4 点击“开始”按钮：

1.5 选择验证方式进行验证：

1.6 验证完成之后扫码绑定微信号，绑定成功后重置开发者密码。然后微信上点击确认，进行第二步密码验证：

1.7 密码验证后，即可查看开发者密码。由于开发者密码不会直接显示在MP后台，因此需要开发者保存。开发者密码为重要账号凭据，建议不要外传。

1.8 获取access_token。在开发——基本配置中点击“获取access_token”,用之前注册的开发者id和生成的开发者密码调用接口获取access_token。

在 MP 投放端（https://mp.weixin.qq.com/）的『开发』—『基本配置』中注册成为开发者。

2. 数据上报

对于推广Web落地页而言，在微信广告推广时，每次点击都会生成一个 click_id，在跳转到落地页时，会将 click_id 作为参数传入对应的 URL 中。

当对应落地页的产生转化行为时，可以利用 API 将 click_id 和转化类型（ActionType）一并上报，经过微信广告计算后，将最终数据呈现在投放端。

2.1 创建Web数据源

创建转化数据对应的数据源，获取存储数据的数据源 ID。

创建行为数据源示例，红色部分需要替换成对应的真实信息
curl -X POST \ “https://api.weixin.qq.com/marketing/user_action_sets/add?version=v1.0&access_token=<ACCESS_TOKEN>“ -H “Content-Type: application/json” -d ‘{ “type”: “WEB”, “name”: “<your_user_action_set_name>“, “description”: “<your_user_action_set_description>“ }’

创建成功应答示例：

{ “errcode”: 0, “errmsg”: “” “data”: { “user_action_set_id”: “<USER_ACTION_SET_ID>“ } }

2.2 进行对接上报回传数据