媒体渠道的“广告投放转化”数据回传API，对接需求怎么写？

本文将以某款金融产品对接快手广告平台为例，介绍广告主商业产品经理的入门级需求策划任务——对接广告平台的标准接口，把转化数据准确上报。

一款有强变现能力的产品（比如金融、游戏、电商），免不了在各种媒体渠道投放广告（比如快手、头条、抖音）。而从用户点击广告到下载、注册、登录、付费等一系列关键行为转化的数据统计，一方面关系到广告结费，另一方面也可以分析广告投放效果、及时调整策略缩减成本提升转化率。

但是，媒体方只有用户点击广告的数据，投放广告的广告主也只有自身产品相关的转化数据，要做到整体漏斗的统计分析，就需要整合双方数据，许多广告平台应运而生（比如凤巢、广点通、多彩互动）。广告主商业产品经理的入门级需求策划任务，就是要对接广告平台的标准接口，把转化数据准确上报。

需要注意的是，媒体方和广告主不会共用一套账户体系，如何把一个用户在两端产生的数据匹配到一起就大有文章：

1. 首先，手机号是最为准确的匹配字段，如果媒体方和广告主的账号绑定的是同一个手机号，就可以认定这是同一个用户，数据可统一归集。
2. 然而，不是所有的媒体渠道都需要用户注册登录，一些游客也会点击广告带来转化。这时，安卓的IMEI设备号、苹果的IDFA设备号就有了用武之地，即时你没有注册账号，但你手机的设备号总不会变，如果媒体方和广告主采集的行为数据对应的设备号是一致的，那也可匹配上两端的数据。
3. 可是这样也不能100%解决问题，有些用户并不会授权给客户端获取它的设备号，那就压根拿不到他的IMEI和IDFA。不过，我们还有手机的MAC网卡地址、Android下的AndroidID、IP地址等可以用来匹配用户身份的字段。总体来说，IMEI和IDFA的采集率最高，其它匹配方式可作为备选或补充。（其实，IMEI和IDFA之外的字段媒体方也不一定会采集、广告平台接口也不一定会提供）

（以某款金融产品对接快手广告平台为例）

一、业务概述

1.1 背景

****、***在快手信息流投放缺少转化数据统计分析，转化量及成本有优化空间。

如下表所示，从历史数据来看对接转化数据回传API，收益明显。

另外，需求实施的前置条件是达标的设备号获取率，经调研已满足要求：

1. 快手的IMEI和IDFA获取率95%左右；
2. APP客户端优化于5月7日上线：V*.*.*版本（****）的IMEI获取率为91.53%，V*.*.*版本（***）的IMEI获取率为91.21%，达到预期要求；
3. ****和***的IDFA抓取率在98%以上。

1.2 目标

如下表所示，通过本次对接转化数据回传API，实现****、***在快手信息流投放的量级增长、成本降低。

1.3 业务主流程示意图

1. 快手用户点击快手客户端展示的广告。
2. 快手客户端请求广告平台中设置的监测链接（广告主自行开发或者托管第三方监测平台），通过宏替换的方式把点击数据详细信息实时同步给广告主或者第三方监测平台（具体见接口一）。
3. 广告主或者第三方监测平台接收到快手接口一上报的点击请求后，记录请求参数中的用户信息（例如用户的IDFA-MD5、IMEI-MD5等）和callback信息，后续从产生相关转化的用户中，匹配出由快手推广渠道带来的用户及其转化数据。
4. 广告主或者第三方监测平台将匹配出的转化数据，通过请求相应的callback通知快手效果统计服务器（具体见接口二）。
5. 快手效果统计服务器将接收到的转化信息和广告点击数据匹配，在投放平台报表中披露出对应广告计划-广告组-广告创意的转化数据。

1.4 名词解释

1.4.1 广告主

本次对接快手API，****、***两款产品流程、需求一致，统称为在快手媒体渠道投放信息流广告的“广告主”。

1.4.2 新增注册

用户手机号本次注册是首次注册，对于同一个手机号****和***是独立分开的，即同一个手机号可以在****和***各新增注册一次。

1.4.3 广告点击

当快手用户点击广告可互动区域时，触发点击事件，该事件被认为是一次有效的广告点击。进入指定落地页后点击内部相关链接等行为，不算作点击。

1.4.4 转化数

快手后台报表中展现的转化数据，时间上以快手服务器收到回调请求的时间为准，量级上以客户实际上报请求数为准。

二、API对接流程

2.1 流程图

作为广告主，****、***对接快手API的流程分为记录点击用户的设备号相关信息、新增注册用户判断、获取注册用户的设备号相关信息、设备号匹配、发送注册用户的设备号相关信息5个环节。

需要注意的是，记录点击用户的设备号相关信息对其它4个环节来说是异步的、前置的。

2.2 流程说明

2.2.1 记录点击用户的设备号相关信息

1. 快手客户端请求点击监测URL（广告主预先在快手广告平台设置），把用户点击数据详细信息实时通过接口一同步给广告主服务端；

2. 广告主服务端接收到快手接口一上报的点击请求后，记录请求参数中的用户信息，其中包括用户的IDFA-MD5或IMEI-MD5、用户点击广告的AID、CID、DID和DNAME、用户点击广告的时间TS和callback信息；（参数说明如下表）

需要额外说明的是，用户每一次点击行为都会上报，都需要完整记录参数信息；

3. 点击监测URL的iOS格式

点击监测URL的Android格式

其中：

• www.example.com是广告主接收点击上报数据的地址，需服务端给出
• channel=kuaishou是广告主自定义用来区分渠道的参数信息，快手上报时原样返回，不做任何修改
• channel/aid/cid/did/dname/ts/idfaMD5/imeiMD5/callback这几个参数名称仅作为参考，最终使用的参数名称可由服务端自行设定
• __CALLBACK__为必填参数，快手客户端在上报的时候会替换成http形式的地址（已编码一次），广告主在接收到上报数据后，需要保存该地址，当用户在应用内完成注册时，请求该地址来上报转化数据（需要拼接相应参数）。

4. 响应要求：响应方式为JSON数据格式，HTTP标准状态码，响应内容不做要求。

2.2.2 新增注册用户判断

1. 用户首次登录APP，广告主服务端判断用户是否为新增注册的用户，若用户不是新增注册则流程结束；
2. 若用户本次是新增注册，则广告主服务端获取该用户安装来源的注册渠道号，若获取的注册渠道号不是快手渠道号（****、***的快手渠道号详见附件《快手&**渠道号》），则流程结束；
3. 若获取的注册渠道号是快手渠道号，则流程进入下一环节2.2.3.。

2.2.3 获取注册用户的设备号相关信息

经过广告主服务端判断，通过快手信息流渠道下载APP且为新增注册的用户通过筛选。

针对这一部分用户，获取他们的MD5加密后的设备ID、用户注册时间两个字段信息，若获取失败则流程结束，若获取成功则流程进入下一环节2.2.4。

其中：

• 安卓imei双卡手机可能有两个，取默认的一个
• iOS下的idfa计算MD5，规则为32位十六进制数字+4位连接符“-”的原文（比如：32ED3EE5-9968-4F25-A015-DE3CFF569568），再计算MD5，再转大写
• 用户注册时间需为13位毫秒级时间戳

2.2.4 设备号匹配

将获取到的注册用户MD5加密设备号与2.2.1.记录的点击用户的MD5加密设备号进行匹配，具体匹配规则为：注册用户的MD5加密设备号存在于点击用户的MD5加密设备号名单中，且最近一次的点击行为发生在注册前7天之内（天数可配置）视为匹配成功，否则为不成功。

若匹配不成功则流程结束，若匹配成功则进入下一环节2.2.5。

2.2.5 发送注册用户的设备号相关信息

1. 发送地址：广告主通过接口一接收的注册前7天内最近一次点击行为的__CALLBACK__替换后的http地址（需要拼接相应参数）；

2. 需要拼接的参数：

• event_type，事件类型，参数值回传2，含义是转化事件为注册
• event_time，事件时间，13位毫秒级时间戳（若请求中携带event_type参数，则必须同时携带event_time参数，否则报错）
• callback，接口一接收的__CALLBACK__替换后的http地址中的callback参数（参考下方示例中标红处）

3. 回调的请求URL（接口一中__CALLBACK__的对应值，链接地址Decode后再拼接相关参数）点击查看示例（“callback=”后字段的字符每次都会不同）

4. 响应内容：回调后response里的result=1代表回调请求上报成功。

2.3 时序说明

三、其他说明

3.1 异常处理

若接口二响应异常，广告主最多上报3次同一条应用内转化数据；如果发送仍失败，则放弃本次发送，并记录异常日志。

3.2 异常报警

广告主上报应用内转化数据到快手广告平台，采用即时策略，如果连续3次同一条应用内转化数据发送失败，就短信或邮件报警提醒到相应人员，每天最多发送一次报警，具体发送名单如下：

姓名***，手机号**********，邮箱**********

3.3 数据需求

需要记录注册转化用户设备号相关信息的发送、响应数据，具体需求字段如下：

Ø channel：渠道

Ø aid：广告组id
Ø cid：广告创意ID

Ø did：广告计划Id

Ø dname：广告计划名称

Ø dt：广告点击事件发生的UTC时间戳

Ø idfaMD5：iOS下的idfa计算MD5

Ø imeiMD5：对15位数字的IMEI进行MD5

Ø event_type：转化事件类型

Ø event_time：转化事件时间

Ø sendNumber：第几次发送（1~3）

Ø sendTime：发送时间

Ø returnCode：返回码

Ø returnTime：返回时间

3.4 信息资料

3.4.1 快手广告平台转化数据API文档v1.4
3.4.2 快手&**渠道号 

本文素材来自互联网