王尘宇

一、概述

为满足快手广告主对广告效果的监测需求，本文档介绍如何把从快手广告渠道分发的应用内转化数据，回传给快手广告管理平台，帮助广告主跟踪转化效果。该方案适用于Android和iOS。

二、定义

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

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

三、数据流程图

流程说明：

1、快手用户浏览或点击快手客户端展示的广告。

2、快手客户端请求广告平台中设置的监测链接（广告主自行开发或者托管第三方监测平台），通过宏替换的方式把广告数据详细信息实时同步给广告主或者第三方监测平台（具体见接口一）。

3、广告主或者第三方监测平台接收到快手接口一上报的广告请求后，记录请求参数中的用户信息（例如用户的IDFA-MD5、IMEI-MD5等）和callback信息，后续从产生相关转化的用户中，匹配出由快手推广渠道带来的用户及其转化数据。

4、广告主或者第三方监测平台将匹配出的转化数据，通过请求相应的callback通知快手效果统计服务器（具体见接口二）。

5、快手效果统计服务器将接收到的转化信息和广告投放数据匹配，在投放平台报表中披露出对应广告计划-广告组-广告创意的转化数据。

      快应用回传逻辑：

1、快手用户浏览或点击快手客户端展示的广告。

2、客户通过魔力建站嵌入快应用，吊起快应用在快应用，吊起快应用+callback。

3、广告主或者第三方监测平台接收到快手接口一上报的广告请求后，记录请求参数中的用户信息（例如用户的IDFA-MD5、IMEI-MD5等）和callback信息(将callback作为唯一匹配值)，后续从产生相关转化的用户中，匹配出由快手推广渠道带来的用户及其转化数据。

4、广告主或者第三方监测平台将匹配出的转化数据，通过请求相应的callback通知快手效果统计服务器（具体见接口二）。

5、快手效果统计服务器将接收到的转化信息和广告投放数据匹配，在投放平台报表中披露出对应广告计划-广告组-广告创意的转化数据。

四、接口详情

【接口一】

接口一可以帮助广告主接收快手服务器提供的广告投放数据，由广告主或者第三方监测平台开发，最终以监测链接的形式填写至广告投放后台。

1. 简介

请求方：快手App客户端

处理方：广告主提供的监测平台服务器

请求协议：HTTPS协议（仅支持HTTPS，不支持HTTP）

请求方式：GET

请求地址：广告主在快手广告平台设置的监测URL

2. 监测链接

监测链接URL中，使用 【__参数__】（如：imeiMD5=__IMEI2__，注意参数前后都为双下划线) 的形式来设置所需上报的数据，常用链接示例如下：

iOS格式样例（参数名自定义即可）：

Android格式样例（参数名自定义即可）：

由于目前不支持动态上报操作系统信息，建议iOS和Android各自使用一套独立监测链接。

其中：

1. www.example.com是广告主接收点击上报数据的地址，需要广告主自行修改替换；

2. xxx=XXXX是广告主自定义参数信息，可由广告主自行设定，快手在上报时，原样返回，不做任何修改；

3. idfaMD5/imeiMD5/callback这几个参数名称仅作为参考，最终使用的参数名称可由广告主自行设定；

4. __IDFA2__/__IMEI2__在上报的时候，会替换为相应的md5加密设备号，其他参数也可以获取，例如在链接地址中添加&mac2=__MAC2__，可以获取md5加密的mac信息，具体可支持的参数列表可查看下方参数说明；

5. __CALLBACK__为必填参数，快手客户端在上报的时候会替换成http形式的地址（已编码一次），广告主在接收到上报数据后，需要保存该地址，当用户在应用内完成相应转化事件时，请求该地址来上报转化数据（需要拼接相应参数，详见下方接口二）。

3. 参数值列表

以下为快手支持的参数值及对应说明。其中，无对应值或快手未获取到值的占位符，不做替换或替换为空字符串（非空格），注意：占位符前后都为双下划线。

4. 上报样例

iOS上报示例：

https://www.example.com?xxx=XXXX&idfaMD5=D4C00E03AC3BFAFE392A310E5D35807F&mac=&callback=http%3a%2f%2fad.partner.gifshow.com%2ftrack%2factivate%3fcallback%3dDHAJASALKFyk1uCKBYCyXp-iIDS-uHDd_a5SJ9Dbwkqv46dahahd87TW7hhkJkd

Android上报示例：

https://www.example.com?xxx=XXXX&imeiMD5=ec40a3448a16fe01f23ea60efdcb5c77&androidid=__ANDROIDID2__&callback=http%3a%2f%2fad.partner.gifshow.com%2ftrack%2factivate%3fcallback%3dDUKFQQ3NGFyk1uCKBYCyXp-ApCU-r7FG_a3TeY40C4wxmWqv46Pmr1q0wfwU3IPB

5. 响应方式

JSON数据格式

6. 响应内容

HTTP标准状态码，响应内容不做要求

7. 注意事项

1、占位符必须全大写，且不能使用不在上述列表中的占位符（如：__GEO__等），后台会做拼写校验；

2、监测链接中参数的命名不需要和上述样例完全一致，但是含义及用途需要完全符合上述定义；

3、监测链接长度不得超过500字节；

4、监测链接不能是下载链接。

【接口二】

接口二用于广告主将应用内转化数据上报给快手广告服务器，快手会将收到的转化数据与广告计划-广告组-广告创意关联，跟踪每个广告创意的转化效果。

1. 简介

请求方：广告主提供的监测平台服务器

处理方：快手广告服务器

请求协议：HTTP HTTPS

请求方式：GET

请求地址：监测方通过接口一接收的__CALLBACK__替换后的http地址（需要拼接相应参数）

参数:

callback，接口一接收的__CALLBACK__替换后的http地址中的callback参数（参考下方示例中标红处）。

event_type，事件类型，转化事件和参数值的对应关系见下表，建议对接前与快手运营同学沟通确认。

event_time，事件时间，13位毫秒级时间戳。若请求中携带event_type参数，则必须同时携带event_time参数。

purchase_amount，金额。当event_type为{3,12,13,14,15}，必须同时回传消费金额参数purchase_amount，单位元，可保留两位小数。

user_tags_age，用户年龄，可选参数，整数，仅限保险行业使用。

user_tags_insurance，社保情况，可选参数，整数，仅限保险行业使用，取值：0-无社保、1-ext_pred_ltv社保、2-其他。

weighted_purchase_amount，加权付费金额，可选参数，双精度浮点型，仅限保险行业使用。

action_reason，行为原因，可选参数，整数，当event_type为{120,121}时强烈建议回传，枚举值见下方表格。

key_action_category：关键行为类型，可选参数，整数，当 event_type=143 时强烈建议回传，枚举值见下方表格。

key_action_threshold：关键行为定义对应的次数/数量/等级/金额等信息，可选参数，数字，当 event_type=143 时强烈建议回传，枚举值见下方表格

ext_pred_pay_ratio：预估LTV，可选参数，double。

ext_pred_ltv：预估LTV，可选参数，double。

pay_level：付费等级，可选参数，具体:S/M/L,event_type=151可回传

novel_chapter_num：小说章节，可选参数，1-1000。event_type=150可回传

2. 回调请求

回调的请求URL（接口一中__CALLBACK__的对应值，UrlDecode后再拼接相关参数）示例如下：

1）激活

http://ad.partner.gifshow.com/track/activate?event_type=1&event_time=1536045380000&callback=DHAJASALKFyk1uCKBYCyXp-iIDS-uHDd_a5SJ9Dbwkqv46dahahd87TW7hhkJkd  （标红区域字段的字符，仅作为样例，不可用于联调）。

2）注册

http://ad.partner.gifshow.com/track/activate?event_type=2&event_time=1536045380000&callback=DHAJASALKFyk1uCKBYCyXp-iIDS-uHDd_a5SJ9Dbwkqv46dahahd87TW7hhkJkd  （标红区域字段的字符，仅作为样例，不可用于联调）。

3）付费

http://ad.partner.gifshow.com/track/activate?event_type=3&event_time=1536045380000&purchase_amount=10.88&callback=DHAJASALKFyk1uCKBYCyXp-iIDS-uHDd_a5SJ9Dbwkqv46dahahd87TW7hhkJkd  （标红区域字段的字符，仅作为样例，不可用于联调）。

3. 响应内容

回调后response为JSON格式，result=1代表回调请求上报成功，其他参数及参数值无需关注。

4. 多触点归因数据回传

为提升投放效果，快手希望广告主可以将归因至其它渠道的转化数据也回传至快手，帮助优化深度转化模型训练，上报此类转化数据时，需要增加参数“&is_direct_match=false”，表示“该用户看过快手广告，但转化归因到了其它平台”，此类数据不会计入投放报表展现。上报样例：

五、联调

广告主可在投放后台“工具-转化追踪-追踪应用”中，新建转化目标，填写相关内容后，按页面说明进行联调。

联调不计入报表，只有体验广告才计入报表。

六、Q&A

强烈建议广告主通过监测链接收集并记录账户/计划/组/创意这四个层级的ID，这样可以清楚的知道转化callback最终上报后，会披露在哪个账户/计划/组/创意下面；我们的广告id已经超过int32位了，请客户按照int64来存储，已经出现有客户因广告id过长导致存储失败，而无法归因的情况。

对接中如果遇到问题，广告主通常可关注以下几点来进行问题排查：1. 是否正确收到监测请求上报，2. 转化归因匹配是否正常，3. 是否成功回调转化callback。

若遇到其他问题，可查看Q&A文档。文档中包含了对接期间注意事项、常见问题的排查方向、以及产生数据差异时，双方的协作流程。

---