微信朋友圈关于H5/小程序广告转化行为数据接入说明文档

一、 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. 1)  在MP投放端(https://mp.weixin.qq.com/)的『开发』—『基本配置』中注册

   成为开发者;

2. 2)  创建转化数据对应的数据源;

3. 3)  获取用户click_id，根据转化行为、推广目标，选择对应的行为类型回传数据，构

   造请求回传数据至对应的行为源，需要确保回传成功;

4. 4)  例行化:确保线上实际投放时，用户发生转化后，会自动实时运行步骤2，调用API

   回传数据，并回传成功;

5. 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) 验证完成之后扫码绑定微信号，绑定成功后重置开发者密码。然后微信上点击确认，

进行第二步密码验证:

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

2. 获取 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 对应数据指标:销售线索量;