一、 API 方案介绍....................................................................................................................3
1、使用须知 ..................................................................................................................................3
2、使用背景 ..................................................................................................................................4
3、原理介绍 ..................................................................................................................................4
二、 对接步骤 ............................................................................................................................5
1、准备阶段 ..................................................................................................................................5
2、正式对接 ..................................................................................................................................5
3、例行化.......................................................................................................................................5
4、验证 ...........................................................................................................................................5
三、 准备阶段 ............................................................................................................................6
1、注册成为开发者 ......................................................................................................................6
2、创建数据源 ..............................................................................................................................9
四、 正式对接 ......................................................................................................................... 11
1、获取用户 CLICK_ID ................................................................................................................ 11
2、确定行为类型 ....................................................................................................................... 11
3、回传数据 ............................................................................................................................... 12
五、 例行化 ............................................................................................................................. 16
六、 验证 ................................................................................................................................. 17
1、自行验证 ............................................................................................................................... 17
2、上线验证 ............................................................................................................................... 17
一、 API 方案介绍
在微信广告(https://mp.weixin.qq.com/,以下简称 MP 投放端)推广 H5 或小程序页面时,用户进入 H5 或小程序中会产生对应的转化行为(如下单、资料收集等),为了 量化广告转化效果,以及积累转化数据以使用智能优化(oCPM/oCPA)能力,需要回 传用户的转化行为。本 API 解决的是 H5 页面或小程序转化行为回传的问题。
1、使用须知 对接流程简介:
-
1) 在MP投放端(https://mp.weixin.qq.com/)的『开发』—『基本配置』中注册
成为开发者;
-
2) 创建转化数据对应的数据源;
-
3) 获取用户click_id,根据转化行为、推广目标,选择对应的行为类型回传数据,构
造请求回传数据至对应的行为源,需要确保回传成功;
-
4) 例行化:确保线上实际投放时,用户发生转化后,会自动实时运行步骤2,调用API
回传数据,并回传成功;
-
5) 验证:判断步骤3是否正常运行;
注:对于二次接入本 API 的广告主账号,可以跳过 1、2 步骤; 建议对接人员:建议后台开发同学对接本 API;
2、使用背景
目前支持的行为类型以及对应的智能投放优化目标、数据指标如下:
行为名称 | ActionType | 推广目标 | 数据指标 | 说明 |
下单 | COMPLETE_ORDER | 推广我的商品 | 下单量 | 如电商商品 被下单 |
预约 | RESERVATION | 收集销售线索 | 销售线索量 | 如提交联系 信息,预约看 车 |
目前支持的广告流量包括:
1)公众号底部和文中:品牌活动推广、电商推广、销售线索收集广告的 H5 和小程序落地页;
2)朋友圈信息流:品牌活动推广、本地推广、电商推广、销售线索收集广告的 H5和小程序落地页;
3、原理介绍
l 对于落地页为 H5 或小程序的广告而言,在微信广告平台推广时,每次点击都会生 成一个 click_id,在跳转到落地页时,会将 click_id 作为参数传入对应的 URL 中。
回传转化数据时,需要回传 click_id 与转化行为,广告平台会通过 click_id 关联到 该次转化对应的广告,从而得到点击与转化的关联。
关联后计算的广告效果会呈现在 MP 投放端报表中(mp.weixin.qq.com),并会成 为智能优化的数据基础。
二、 对接步骤概览
1、准备阶段
1) 注册成为开发者;
2) 创建数据源,获取存储数据的数据源 ID;
2、正式对接
1)获取用户 click_id;
2)确定行为类型;
3)获取创建时存储的数据源 ID 4)构造请求回传数据,需要确保回传成功;
3、例行化
确保线上实际投放时,用户发生转化后,会自动实时运行
4、验证
调用 API 回传数据,并回传成功;
三、 准备阶段
1、注册成为开发者
目标:获取开发者 ID、密码和 access_token
步骤:
1) 进入注册页面(mp.weixin.qq.com),点击左边栏,『开发』下『基本配置』。同意
《微信公众平台开发者服务协议》后,点击『成为开发者』;
2) 获取开发者密码。点击“重置”按钮:
3) 弹窗提示,点击“确定重置”按钮:
4) 点击“开始”按钮:
5) 选择验证方式进行验证:
6) 验证完成之后扫码绑定微信号,绑定成功后重置开发者密码。然后微信上点击确认,
进行第二步密码验证:
-
密码验证后,即可查看开发者密码。由于开发者密码不会直接显示在 MP 后台, 因此需要开发者保存。开发者密码为重要账号凭据,建议不要外传。
-
获取 access_token。在开发——基本配置中点击“获取 access_token”,用之前 注册的开发者 id 和生成的开发者密码调用接口获取 access_token。
2、创建数据源
目标:创建数据源,生成数据源 ID(user_action_set_id) 步骤:
1)构造请求,创建数据源;保存数据源 ID,用于后续回传数据; 请求地址:
user_action_sets/add
请求方法:
POST
请求参数:
名称 | 类型 | 描述 |
Type | enum | 用户行为源类型,WEB |
Name | string | 用户行为源名称,必填 |
名称 | 类型 | 描述 |
description | string | 用户行为源描述,字段长度最小 1 字节,长度最大 128 字 节 |
请求示例:
curl -i "https://api.weixin.qq.com/marketing/user_action_sets/add?version=v1.0&access_token=<ACCE SS_TOKEN>"
-H "Content-Type: application/json" -d '{
"type": "WEB", "name": "wxadtest", "description": "test"
}'
应答字段:
名称 | 类型 | 描述 |
user_action_set_id | integer | |
用户行为源 id,通过 [user_action_sets 接口] 创建用户 行为源时分配的唯一 id | ||
应答示例:
{
}
"errcode":0, " "errmsg":"" "data": {
"user_action_set_id": "<USER_ACTION_SET_ID>" }
四、 正式对接
1、获取用户 click_id
目标:获取访问 H5 或小程序的用户 click_id,作为回传数据的用户标识;
步骤:
1)获取 click_id
落地页为 H5:用户点击广告进入落地页后,广告平台会在 URL 增加 click_id。即,URL 中的 gdt_vid;
注:
1、落地页为小程序时获取方法参考数据监控指引;
2、click_id 格式:18 位或 16 位长度字符串;
2)传递 click_id
如果存在二跳页面,建议页面增加逻辑向下传递 click_id。即,访问下一页面时,网页 参数中增加 click_id 信息;
3)记录 click_id
用户发生转化时,记录发生转化的 click_id;
2、确定行为类型
目标:请与业务人员沟通确认,根据推广目标和 oCPM 优化目标,确认需要回传的行 为类型;
步骤:
根据以下建议,确认后续 API 回传时需要填写的 Action_Type:
行为名称 | ActionType | 推广目标 | 数据指标 | 说明 |
下单 | COMPLETE_ORDER | 推广我的商品 | 下单量 | 如电商商品 被下单 |
预约 | RESERVATION | 收集销售线索 | 销售线索量 | 如提交联系 信息,预约看 车,金融业务 注册申请等 |
3、回传数据
目标:根据 click_id、Action_Type、创建时保存的数据源 ID,调用 API 进行回传,获 取成功应答;
步骤:
1)前提
在传入转化行为数据之前,请确保开发者已经:
注册成为开发者,并获取了可用的在有效期内的 token
已创建数据源,并保留 user_action_set_id,查询已有的 user_action_set_id
2)确认上报数据字段
参数说明如下:
名称 | 类型 | 必填 | 限制 | 说明 |
user_action_set_id | integer | yes | 用于标识数据归属权。 |
名称 | 类型 | 必填 | 限制 | 说明 |
url | string | yes | 转化行为发生页面的 URL | |
action_time | integer | yes | 行为发生时,客户端的时间点。 广告平台使用的是 GMT+8 的 时间,容错范围是前后 10 秒, UNIX 时间,单位为秒,如果不 填将使用服务端时间填写 | |
action_type | enum | yes | 预定义的行为类型,目前只支 持 COMPLETE_ORDER(下 单)及 RESERVATION(表单 预约) | |
click_id | string | yes | 目前仅支持 click_id | 落地页 URL 中的 click_id,对 于微信流量为 URL 中的 gdt_vid,获取方法参考数据监 控指引 |
action_param | string | no | 行为所带的参数,转化行为价 值(例如金额),详见附录, 字段长度最小 1 字节,长度最 大 204800 字节 |
名称 | 类型 | 必填 | 限制 | 说明 |
value | Int | no | 代表订单金额,单位为分,需 要填写到 param 中获取,例如 商品单价 40 元,需赋值为 4000 |
3)调用 API
回传数据 示例:需要统计“下单”的转化行为,开发者只需要在下单转化行为发生时,上报 action_type=“COMPLETE_ORDER”,且附上由落地页获取的 click_id。 请求示例:
curl -k "https://api.weixin.qq.com/marketing/user_actions/add?version=v1.0&access_token=<ACCESS_ TOKEN>"
-d '{
"actions":[ {
} ]
}'
-H "Content-Type:application/json"
"user_action_set_id":"<USER_ACTION_SET_ID>", "url":"<URL>",
"action_time":1513077790, "action_type":"COMPLETE_ORDER",
"trace":{ "click_id":"<CLICK_ID>"
}, "action_param":{
"value": 40 }
应答示例:
正确的返回值为:
{"errcode":0," errmsg":""} 返回错误返回码时,详见『附录-问题排查流程』。
五、 例行化
1)确保广告实际投放中,用户发生转化后,步骤四能够正常运行,自动获取用户的click_id,并通过 API 回传到广告系统中。
2)增加 API 数据回传日志,记录每次调用 API 回传的内容以及 API 应答信息,方便后 续排查问题。
六、 验证
1、自行验证
1)根据后续投放归因场景,创建测试广告;
2)根据线上数据,获取用户链接中的 click_id;
3)手动调用 API,填入 click_id,模拟手动回传一次转化数据;
4)获得应答信息:{"errcode":0," errmsg":""},则验证成功;
注:
验证成功,代表 API 回传通路正常,如果线上应答不成功,需要重点排查获取click_id,填写各种信息,自动回传的逻辑是否正常;
验证失败,请参考 章节一:问题咨询流程
2、上线验证
1)创建广告;
2)正常投放;
3)确认 API 数据回传日志,有数据回传且应答信息正确; 无日志可以根据『附录-数据源报表查询』,根据 raw_action_count 是否有值,判断是 否成功传入了行为数据;
4)访问 MP 投放端报表,数据指标是否有相应的数值显示;
ActionType = COMPLETE_ORDER 对应数据指标:下单量;
ActionType = RESERVATION 对应数据指标:销售线索量;