快手短視頻廣告管理平臺：應用下載類廣告轉化數據API接口文檔

一、概述

為滿足快手廣告主對廣告效果的監測需求，本文檔介紹如何把從快手廣告渠道分發的應用內轉化數據，回傳給快手廣告管理平臺，幫助廣告主跟蹤轉化效果。該方案適用于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格式樣例（參數名自定義即可）：

https://www.example.com?xxx=XXXX&idfaMD5=__IDFA2__&callback=__CALLBACK__&campaignid=__DID__

Android格式樣例（參數名自定義即可）：

https://www.example.com?xxx=XXXX&imeiMD5=__IMEI2__&callback=__CALLBACK__&campaignid=__DID__

由于目前不支持動態上報操作系統信息，建議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可回傳