【H5转化API】腾讯社交广告H5转化跟踪API说明文档 V2.2

Size: px

Start display at page:

Download "【H5转化API】腾讯社交广告H5转化跟踪API说明文档 V2.2"

崎袁
5 years ago
Views:

1 H5 转化 API 腾讯社交广告 H5 转化跟踪 API 说明文档 V2.2 H5-oCPA H5 转化 API 腾讯社交广告 H5 转化跟踪 API 说明文档 V API 方案介绍 1.2 最新改动 :( 必读 ) 1.2 两种数据上报模式 :( 必读 ) 2. API 接入流程 2.1 注册成为腾讯社交广告 MarketingAPI 开发者登录已注册的 QQ 账户完善开发者资料创建转化数据上报应用 2.2 绑定需要追踪 H5 转化数据的广告主账户完成 OAuth2.0 认证操作如何更新 refresh_token: 配额和频次控制 2.3 上报网页转化行为数据转化数据类型转化数据类型示例数据上报参数说明转化数据上报请求示例返回值附录特别说明不同类型账户请求授权结果 : 特别说明永久 Token 1. API 方案介绍 1. 对于 H5 商品而言, 在腾讯社交广告推广时, 每次点击都会生成一个 click_id, 在跳转到落地页时, 会将 click_id 作为参数传入对应的 URL 中

2 2. 当对应落地页的产生转化行为时, 可以利用 API 将 click_id 和转化类型 (ActionType) 一并上报给腾讯社交广告, 经过腾讯社交广告计算后, 将最终数据呈现在投放端 (e.qq.com) 3. 目前支持的广告流量包括 : 手腾网 QQ 空间 (PC 移动流量) QQ 浏览器 QQ 天气附近的人移动联盟微信公众号其中 QQ 空间 (PC) 和微信公众号不支持 H5-oCPA 功能 1.2 最新改动 :( 必读 ) 1. 参数 pixel_id 名称变更为 user_action_set_id 2. 新增加了直接获取 user_action_set_id 的接口 3. 永久的 refresh_token 已经上线内测期间使用的接口地址为 : 目前已经全面更新为 : 新接入的开发者请使用已经完成对接的广告主建议做更新, 但也可以不做修改 1.2 两种数据上报模式 :( 必读 )

3 模式 1: 开发者用一套完成鉴权的 account id 和对应的 user_action_set_id 来上报所有账户的数据模式 2: 开发者与每一个广告主账户进行鉴权, 用各个账户的广告主 ID 作为 account id 和各自对应的 user_action_set_id 完成各自账户的数据上报 2. API 接入流程 Step 1. 注册成为腾讯社交广告 MarketingAPI ( 开发者 Step 2. 创建转化数据上报应用, 等待审核 Step 3. 绑定需要追踪 H5 转化数据的广告主账户 Step 4. 上报网页转化行为数据 2.1 注册成为腾讯社交广告 MarketingAPI 开发者要调用 Marketing API, 必须先注册成为开发者并创建应用此处的应用可以理解为一个面向其他广告主的服务, 下文将其统一定义为转化数据上报应用登录已注册的 QQ 账户

4 如果开发者已经是广点通的广告主账户 ( 代理商或广告主 ), 建议直接用代理商帐号或广告主帐号的开户 QQ 进行注册完善开发者资料完成 QQ 登录后, 将进入开发者资料填写页面 :

5 资料填写完整并手机验证通过后即完成开发者注册创建转化数据上报应用注册为开发者后, 在开发者官网登录即可进入应用程序管理面板 :

6 点击创建新应用程序进入创建转化数据上报服务界面 :

开发者需要提供应用名称应用介绍应用图标回调地址等几项内容, 应用需要审核通过后才能实际生效其中 : 应用名称最好能包含广告主或开发者的品牌应用介绍将是审核的主要参考, 请填写 : 利用 MarketingAPI 完成网页转化数据上报应用图标将显示在 OAuth 授权页面中,

7 开发者需要提供应用名称应用介绍应用图标回调地址等几项内容, 应用需要审核通过后才能实际生效其中 : 应用名称最好能包含广告主或开发者的品牌应用介绍将是审核的主要参考, 请填写 : 利用 MarketingAPI 完成网页转化数据上报应用图标将显示在 OAuth 授权页面中, 建议使用能暴露开发者品牌的图标回调地址将用于 OAuth 授权完成后的跳转及信息返回, 详情参考授权认证章节应用审核通过后, 开发者将获得一个对应的 client_id 和 client_secret ( 见下图示意 ), 并可以用此发起 OAuth 授权获得指定推广帐号的操作权限, 详情参考授权认证章节

2.2 绑定需要追踪 H5 转化数据的广告主账户 2.2.1 完成 OAuth2.0 认证操作当广告主帐号与开发者的应用完成绑定后, 在广告主需要通过开发者的应用进行帐号操作时, 开发者的应用需要先引导广告主完成至少一次 OAuth2.0 认证操作, 以便获得调用接口操作对应帐号所必须的 access_token Marketing API 的 OAuth2.

8 2.2 绑定需要追踪 H5 转化数据的广告主账户完成 OAuth2.0 认证操作当广告主帐号与开发者的应用完成绑定后, 在广告主需要通过开发者的应用进行帐号操作时, 开发者的应用需要先引导广告主完成至少一次 OAuth2.0 认证操作, 以便获得调用接口操作对应帐号所必须的 access_token Marketing API 的 OAuth2.0 遵循业界通用的规范和流程, 完成 OAuth2.0 认证 ( 当前只支持 server-side 模式 ) 需要完成以下步骤 : A. 引导广告主进入 Oauth2.0 登录界面 B. 广告主用已绑定当前应用的帐号对应的 QQ 登录 C. 登录成功并确认授权后广点通向开发者的应用程序返回一个授权码 (Authorization Code) D. 应用程序调用接口用授权码 (Authorization Code) 获得 access_token, 同时获得一个用于刷新 access_token 的 refresh_token E. 在 access_token 过期后, 使用 refresh_token 获得新的 access_token( 可选 ) 详细描述如下 : 步骤 1: 引导广告主完成 Oauth2.0 认证后并获得 authorization_code 调用 OAuth2.0 登录界面的 URL 形如 : <CLIENT_ID>&redirect_uri= 其中 : client_id 为开发者创建的应用唯一标识 id; redirect_url 为回调地址, 由开发者自行提供和定义, 用于跳转并接收回调信息 state 为开发者自定义参数, 可用于验证请求有效性或者传递其他自定义信息, 回调的时候会原样带回

9 当引导广告主在上述登录界面完成登录身份验证后, 系统会自动跳转到刚才定义的回调地址中, 但不会带上 authorization_code( 有效期 5 分钟 ) 和 state 两个参数与此同时, 回调地址会收到一次包含了 authorization_code( 有效期 5 分钟 ) 和 state 两个参数的请求, 需要此回调地址记录对应参数形如 : 开发者的应用程序在收到上述返回后, 应当在 authorization_code 有效期内, 利用 authorization_code 获得 access_token ( 见下一步 ), 并对广告主给出相应的提示和跳转指引等步骤 2: 使用 authorization_code 获得 access_token 和 refresh_token 用 authorization_code 获得 access_token 和 refresh_token 的接口地址为接口输入参数如下表所示 : 名称类型描述限制 client_id integer 应用 id, 开发者创建应用后获得, 旧名称 appid 已不可用是否必填 client_secret string 应用 secret, 应用被审核通过后获得, 旧名称 app_key 已不可用 grant_type string 请求的类型, 可选值 :authorization_code( 授权码方式获取 token) refresh_token( 刷新 token) authorization_code string OAuth 认证 code, 当 grant_type='authorization_code' 时必填应用 secret 小于 256 个英文字符 no

10 名称类型描述限制是否必填 redirect_uri string 应用回调地址, 当 grant_type='authorization_code',redirect_uri 为必填参数, 仅支持 http 和 https, 不支持指定端口号, 且主域名必须与创建应用时登记的回调域名一致 refresh_token string 应用 refresh token, 当 grant_type='refresh_token' 时必填字段最小长度 1 字节, 最大长度 1024 字节 no no 请求示例 : curl -k " CLIENT_SECRET>&authorization_code= <AUTHORIZATION_CODE>&grant_type=authorization_code" 返回示例 : { } "code": 0, "message": "", "data": { "access_token": "228bd56b7ee f766b40d e", "refresh_token": "854e744a1f4c6fc20f498e366b9aabd2c4b971fd", "access_token_expires_in": 86400, "refresh_token_expires_in": 获得 access_token 后, 开发者可用此调用接口对相关的广告主帐号进行操作其中 access_token 和 refresh_token 均设置了有效期 : access_token 默认有效期为 24 小时 refresh_token 默认有效期为 30 天建议广告主增加在 access_token 失效前及时刷新 access_token 的逻辑

11 注 : 使用 refresh_token 获得新的 access_token( 可选 ) 在 refresh_token 有效期内, 广告主可以用 refresh_token 通过 auth/access_token 接口获得新的 access_token 和 refresh_token, 示意如下 : curl -k " CLIENT_SECRET>&refresh_token=<REFRESH_TOKEN>&grant_type=refresh_token" 如何更新 refresh_token: 1. 如果 refresh_token 失效, 开发者需要重新通过 OAuth 2.0 授权获得新的 access_token 和 refresh_token 2. 由于 refresh_token 会过期, 所以需要开发者与广告主每隔 30 天进行一次 OAuth 2.0 鉴权认证 3. 关于不会过期的 refresh_token, 请参考永久 refresh_token 配额和频次控制系统对每个 APP 的接口调用有配额 ( 单个接口每天可以调用的总次数 ) 限制和频次 ( 单个接口每分钟调用的次数 ) 限制默认情况下, 每个 APP 每个接口每天接口调用的配额和频次限制如下 : 每个读接口限次 / 天,2000 次 / 分钟每个写接口限次 / 天,1000 次 / 分钟如果出现配额或者频次控制不满足开发者上报 H5 转化数据的需求, 可以通过以下途径申请提高配额开发者腾讯社交广告运营接口人 2.3 上报网页转化行为数据在传入转化行为数据之前, 请确保开发者已经 : 完成了文档 2.3 中需要上报效果广告主账户的绑定获取了可用的在有效期内的 token 转化数据类型要上报转化行为, 首先需要填写相应的转化类型 (ActionType) 对应参数为 action_type 如下表所示 ( 目前只开放下单行为 ):

转化行为下单 ActionType(action_type) COMPLETE_ORDER 2.3.

12 转化行为下单 ActionType(action_type) COMPLETE_ORDER 转化数据类型示例此处以下单为例数据上报参数说明名称类型描述限制 account_id integer 广告主 ID 必须是已经和开发者完成鉴权的广告主 ID user_action_set_id integer 原 pixel id, 现更名为 user_action_set_id, 旧参数名依然兼容后续用于标识数据归属权 user_action_set_id 获取方式是否必填 url string 转化行为发生页面的 URL

13 名称类型描述限制 action_time integer 行为发生时, 客户端的时间点广点通使用的是 GMT+8 的时间, 容错范围是前后 10 秒,UNIX 时间, 单位为秒, 如果不填将使用服务端时间填写 action_type enum 预定义的行为类型, 目前只支持 COMPLETE_ORDER( 表单提交 ) 是否必填 click_id string 落地页 URL 中的 click_id, 对于广点通流量为 URL 中的 qz_gdt, 对于微信流量为 URL 中的 gdt_vid 目前仅支持 click_id value integer 转化行为价值 ( 例如金额 ) 100 表示 1 元 nonce integer nonce 是一个长度小于 32 的随机字符串, 并要保证唯一性 timestamp integer timestamp 是精确到秒的时间戳, 广点通使用的是 GMT+8 的时间, 容错范围是前后 10 秒, 在上报前建议开发者更新服务器时间 no 转化数据上报请求示例需要统计下单的转化行为, 开发者只需要在下单转化行为发生时, 上报 action_type= COMPLETE_ORDER, 且附上由落地页获取的 click_id,nonce 是一个长度小于 32 的随机字符串, 并要保证唯一性请求示例如下 : curl -k " amp=<timestamp>&nonce=<nonce>" \ -d '{ "account_id": "<ACCOUNT_ID>" "actions": [ { "user_action_set_id": "<USER_ACTION_SET_ID>", "url": "<URL>", "action_time": , "action_type": "COMPLETE_ORDER", "trace": { "click_id": "<CLICK_ID>" },

14 }' ] } "value": 返回值正确的返回值为 : {"code":0,"message":"success"} 代表上报成功关于错误的返回码详见 MarketingAPI 返回码附录特别说明不同类型账户请求授权结果 : 1. 如果请求授权的是代理商帐号, 代理商用开户 QQ 登录并同意授权, 完成 OAuth 2.0 后应用获得 access_token, 该应用会获得当前代理商所有子客户的推广帐号的操作权限 2. 如果请求授权的是直客帐号, 客户用开户 QQ 登录并同意授权, 完成 OAuth 2.0 后应用获得 access_token, 该用户会获得当前客户推广帐号的操作权限 3. 如果请求授权的是代理商子客户, 用子客户的自理管理员 QQ( 由代理商分配 ) 登录并同意授权, 完成 OAuth 2.0 后应用获得 access_token, 该应用会获得当前子客户推广帐号的操作权限特别说明永久 Token 1. 永久 Token 只能用于上报数据, 如果有投放广告查看报表数据等需求, 需要单独新建开发者 APP 2. 开发者如果需要申请永久 Token 用于上报数据, 需要联系广点通运营, 并提供上报数据使用的开发者 APP 信息, 后续此 APP 只能使用 MarketingAPI 的上报数据功能 3. 目前永久 Token 已上线, 现已开放申请

优斗士微分销产品使用指南

优斗士微分销产品使用指南优斗士云店操作手册优斗士 ( 中国 ). 市场部 www.udows.com 咨询热线 :400-877-7882 移动让商业更简单 www.udows.com 1 目录第 1 章优斗士云店产品使用手册... 7 1.1 什么是优斗士云店系统?... 7 1.2 企业为什么要使用优斗士云