對接文檔 · 藍蛙SSP媒體服務平臺對接文檔

[TOC] ## **更新日志** | 版本 | 更新時間 | 修訂內容 | | --- | --- | --- | | 1.2.0 | 2021-01-20 | 1、添加deeplink點擊上報事件 2、跑OPPO需要相對坐標和絕對坐標，跑vivo只需要相對坐標 | | 1.2.1 | 2021-03-26 | 1、刪除參數 img_type 2、添加參數 caid | | 1.3.0 | 2021-04-09 | 1、新增廣點通廣告 | | 1.3.1 | 2021-06-03 | 1、新增參數support_universal、os_update_time、os_startup_time、phone_name、phone_name、sys_memory、sys_disksize、hardware_machine、country、language、timezone、hms_ver、hwag_ver| | 1.3.2 | 2021-09-02 | 1、新增參數 boot_mark、update_mark | | 1.3.3 | 2021-09-03 | 1、添加返回字段is_gdt, 修改廣點通預算輸出方式 | | 1.3.4 | 2021-09-09 | 1、新增參數 ali_aaid, iOS跑阿里預算必填| | 1.3.5 | 2021-10-08 | 1、刪除宏\_\_DOWN_TIME__、\_\_UP_TIME__、\_\_SHOW_TIME__、\_\_CLICK_TIME__ 2、新增宏請求廣告位寬高\_\_REQ\_WIDTH\_\_、\_\_REQ\_HEIGHT\_\_； 廣告展示區域坐標：\_\_DISPLAY\_LUX\_\_、\_\_DISPLAY\_LUY\_\_、\_\_DISPLAY\_RDX\_\_、\_\_DISPLAY\_RDY\_\_； 廣告按鈕區域坐標：\_\_BUTTON\_LUX\_\_、\_\_BUTTON\_LUY\_\_、\_\_BUTTON\_RDX\_\_、\_\_BUTTON\_RDY\_\_； 設備參數信息：\_\_MAC\_M\_\_、\_\_MAC\_MS\_\_、\_\_IMEI\_M\_\_、\_\_ANDROIDID\_\_、\_\_ANDROIDID\_M\_\_； 視頻時間：\_\_VIDEO\_TIME\_\_、\_\_BEGIN\_TIME\_\_、\_\_END\_TIME\_\_| | 1.3.6 | 2021-11-25 | 1、添加fallback\_type返回字段 | | 1.3.7 | 2022-01-04 | 1、新增參數 installed | | 1.3.8 | 2022-06-15 | 1、添加廣點通喚醒廣告處理方式 | | 1.4.0 | 2022-11-25 | 1、新增參數api_version、count,新增響應字段Ad.id 2、響應字段data由對象改為數組對象(為了兼容，參數帶api_version時生效) | | 1.4.1 | 2022-12-12 | 1、新增小程序響應字段applet_id、applet_path、applet_appid，interaction_type=3| | 1.4.2 | 2023-1-13 | 1、新增邏輯像素宏| | 1.4.3 | 2023-4-23 | 1、新增響應字段ua| | 1.4.4 | 2023-4-25 | 1、新增響應字段clk_time、over_time 2、新增參數bidfloor、響應字段price、價格宏__LW_BID_PRICE__| | 1.4.5 | 2023-5-18 | 1、新增廣告交互方式宏_\_SLD__| | 1.4.6 | 2024-5-24 | 1、新增響應字段應用商店直投地址: market_url | | 1.4.7 | 2024-11-19 | 1、修改請求字段 platform 2、增加下載六要素字段: app_version、 privacy_url 、 perm_url 、 perm_content、developer、feature_url、 size| | 1.4.8 | 2024-12-06 | 1、增加請求字段 caids 2、刪除請求字段: caid | | 1.4.9 | 2025-01-07 | 1、新增響應曝光失敗字段 lurls | ## **接入說明** 本文檔定義了廣告平臺接入協議，便于媒體實現快速接入。接入方務必詳細閱讀對接流程及連接方式，避免對接過程中出現問題。 > 正式對接時，媒體方需要向 BlueMobi 運營人員申請聯調地址和代碼位ID； ## **開發原則** 1. POST 方式，參數值以 UTF-8 編碼，請使用 json/application作為 Content-Type， **請使用長連接請求**。 2. 通過 API 請求到的廣告內容，請及時展現給終端用戶，不要緩存，不要同一廣告展現多次，這樣廣告服務會將該點擊判為作弊，反而使得開發者收入降低。 3. 開發者在廣告請求時應盡可能多填寫參數，這樣廣告服務可以配到更相關、用戶更喜歡的廣告，能夠提升用戶點擊率，從而提高開發者收入。但是如果開發者本身獲取不到可選參數，請開發者不要隨便填寫可選字段，這樣反而可能造成配到不相關廣告，降低點擊率，影響開發者收入。總之，對于可選字段，開發者應該盡最大可能填寫準確可信的值。 4. 請求廣告時，若從服務器發起，必須使用 ip 參數傳入用戶原始 IP 地址。 5. 展示上報和點擊上報必須從客戶端發起，禁止通過第三方服務器發起，以免被判定為作弊。 6. 請求和上報 HTTP 請求中的 User-Agent 請設置成客戶端瀏覽器默認 User-Agent 值，不允許自定義 User-Agent, 以免被判定為作弊。請求到的廣告如果超過半小時，展示就不用上報了 7. **請求和上報的ua, ip要保持一致，宏替換盡量替換，以免過濾** 8. **所有廣告進入落地頁或者進行上報時，請求頭如果在x-request-with、ua、cookie等中攜帶包名，需要去掉。示例: {"x-requested-with":"com.baidu.video"}** ## **請求參數** | 字段 | 類型| 是否必填 | 備注 | | --- | --- | --- | --- | | api_version | String | 是| API版本，當前版本號1.4.0| | app_name | String | 是| 應用名稱| | app_version | String | 是| 應用版本,來源于 manifest 的 versionName ，而不是versionCode如3.5.6| | app_version_code | Int | 是| 應用版本號,來源于 manifest 的 versionCode。如 119| | pkg_name | String | 是| 應用包名| | platform | Int | 是| 平臺： 0 - 未知 1 - 安卓 2 - IOS 3 - iPad 9 - 其他| | make | String | 是| 設備制造商，例如 OPPO| | model | String | 是| 設備硬件型號，例如 PGCM10| | brand | String | 是| 手機品牌,例如 OPPO| | hwv | String | 推薦| 硬件型號版本，例如 iPhone 中的 7S，默認值："unkown"| | os | String | 是| 操作系統，Android 或 iOS 字符串，注意大小寫| | os_version | String | 是| 系統版本，示例：7.0| | osapilevel | Int | 是|安卓系統版本系統級別，示例：24。 av >= 29時，視為安卓系統為 Android Q 及以上| | android_id | String | 是| Android ID| | auidmd5 | String | 是| Android ID的MD5值| | auidsha1 | String | 是| Android ID的sha1值| | imei | String | 是| Android 系統必填，Android手機設備的imei| | imeimd5 | String | 是| Android 系統必填，Android手機設備的imei的MD5值| | imeisha1 | String | 是| Android 系統必填，Android手機設備的imei的sha1值| | meid | String | 否| 手機設備的meid號| | imsi | String | 否| 國際移動用戶識別碼| | oaid | String | 是 | 廣告標識符，安卓10以上必填| | idfa | String | 是| IOS系統必填，原生大寫| | idfamd5 | String | 否| idfa md5| | idfv | String | 是| IOS系統必填| | idfvmd5 | String | 否| idfv md5| | openudid | String | 是| IOS系統必填,設備識別碼 | caids | Object Array| 否 | **中國廣告協會推出的廣告標識符，有版本號概念，在后端算法升級時，會獲得兩個 caid，分別為升級前和升級后的 id，****數據為json****，期望進行****jsonToStr(caid)****，實際內容** **格式樣例：** [{"id": "eeac4a69edbbe8fd373e62d838f8752d","version": "20220111"},{"id": "daad7cca70fe29d9e8c2a94a02eea04b","version": "20230330"}] | | ip | String | 是| IP地址| | ipv6 | String | 否| IPv6地址| | ua | String | 是| 客戶端 user-agent| | mac | String | 是| 客戶端mac地址，保留原始值| | macmd5 | String | 是| 32位小寫md5加密mac| | density | String | 是| 屏幕密度，比例值（dpi/160） eg: 1.5 | | ppi | Int | 是| 像素密度，表示每英寸的像素數。eg:401 | | dpi | Int | 是| 像素點密度，表示每英寸的點數。eg:240 | | screen_width | Int | 是| 屏幕的寬度| | screen_height | Int | 是| 屏幕的高度| | screen_orient | Int | 是| 屏幕的方向： 1 - 豎屏 2 - 橫屏| | app_store_version | String | 否 | 樣例:oppo:5500,vivo:10700 手機自帶的應用商店的版本（OV廣告不能為空）,包括華為ag版本號等 | | rom_version | String | 否 | 手機的ROM版本號（OV廣告不能為空） | | net_type | Int | 是| 客戶端網絡類型: 0.unkown 1.wifi 2.2G 3.3G 4.4G 5.5G| | carrier | Int | 是| 運營商類型： 0. 未知運營商 1.中國移動 2.中國聯通 3.中國電信 4.其他運營商| | bssid | String | 推薦|無線網 ssid 名稱| | wifi_mac | String | 推薦|wifi 路由的 mac 地址| | iccid | String | 否| Sim卡的序號| | mnc | String | 否| 基站MNC| | mcc | String | 否| 基站MCC| | serialno | String | 是 | 系統設備序列號（獲取不到需要報備）| | ali_aaid| String | 否 | 阿里巴巴匿名設備標識，需集成阿里SDK 獲取，阿里預算必填，具體查看附件。 | | boot_mark | String | 是 | 系統啟動標識，原值傳輸，取值參見附件文檔，示例 iOS:：1623815045.970028，Android：ec7f4f33-411a-47bc-8067-744a4e7e0723 | | update_mark | String | 是 | 系統更新標識，原值傳輸，取值參見附件文檔，示例 iOS：1581141691.570419583， Android：1004697.709999999 | | os_birth_time | String | 是 | iOS必傳，系統初始化時間 | | os_compiling_time | String | 是 | iOS必傳，系統編譯時間 | | os_update_time | String | 是 | iOS必傳，系統最近一次更新時間，單位：秒（保留6位小數）示例："1595214620.383940" | | os_startup_time | String | 是 | iOS必傳，系統最近一次啟動時間, 秒級時間戳,（保留整數）示例："1600607108" | | phone_name | String | 是 | 設備名稱 例如：張三的 iPhone | | phone_name_md5 | String | 是 | 設備名稱md5值 | | sys_memory | String | 是 | 系統內存，單位字節 | | sys_disksize | String | 是 | 硬盤容量，單位字節 例如：63900340224 | | cpu_num | String | 是 | 設備的 cpu 核心數量 | | hardware_machine | String | 是 |設備machine值，示例:"iPhone10.3" | | hardware_model | String | 是 | 設備model值示例:“D22AP",僅限iOS設備 | | country | String | 否 | 國家編碼（ISO-3166-1/alpha-2）例如：CN | | language | String | 否 | 設備語言（ISO-639-1/alpha-2）例如：zh | | timezone | String | 否 | 系統所在時區例如：Asia/Shanghai | | hms_ver| String | 條件必填 | 華為安卓設備的 HMS Core的版本號，保留原始值。華為手機必填 | | hwag_ver| String | 條件必填 | 華為安卓設備的 AG（應用市場）的版本號，保留原始值。華為手機必填 | | sys_ui_ver| String | 條件必填 | 系統UI版本，保留原始值。如小米設備的 MIUI的版本號，華為、OV、魅族等設備版本號 | | gps_type | Int | 是| 坐標類型。 0：未知； 1= WGS84(全球衛星定位系統坐標系)； 2= GCJ02（國家測繪局坐標系）； 3= BD09（百度坐標系）；| | longitude | Double | 是| 經度，默認值： 0| | latitude | Double | 是| 緯度，默認值：0| | gps_ts | Int | 是| 獲取 gps 位置時的時間戳,單位：秒| | ad_width | Int | 是| 廣告位寬度，單位為像素| | ad_height | Int | 是| 廣告位高度，單位為像素| | support_deeplink | Int | 是| 是否支持deeplink: 0.不支持 1.支持| | support_universal | Int | 是| 是否支持universal link: 0.不支持 1.支持| | installed | []String | 否 | 從應用列表中篩選已安裝的應用包名進行上傳，如 ["com.sina.news","com.kuaishou.nebula"] | | count | Int | 否 | 廣告數量，默認1，預留字段，部分預算有效| | bidfloor| Int | 否 | 底價，單位分，部分預算有效| > 參數請盡量獲取，實在無法獲取的可暫時填寫模擬默認值（0 or ""等）模擬測試，有問題再與技術協調 ## **廣告響應** ### 響應參數 | 字段 | 類型 | 是否必填 | 備注 | | --- | --- | --- | --- | | code | Int | 是 | 響應狀態碼，0=正常, 1=無填充，其他請看msg提示 | | msg | String | 是 | 響應提示消息| | data | []Ad **Object** | 否 | 廣告信息 | | unique| String | 是 | 請求唯一標識符 | ### Ad | 字段 | 類型 | 是否必填 | 備注 | | --- | --- | --- | --- | | id | String | 否 | 曝光id，每個廣告唯一 | | title | String | 否 | 主標題 | | desc | String | 否 | 描述 | | price| Int | 否 | 投放出價，單位分，部分預算有效| | ad_width | Int | 否 | 廣告寬度| | ad_height | Int | 否 | 廣告高度 | | ad_logo | String | 否 | 廣告圖標 | | imgs | []String | 否 | 圖片地址數組 | | fallback_type | Int | 否 | deeplink 退化類型，應用未安裝時如何處理，默認0 0 - 瀏覽器打開 1 - 下載應用 | | interaction_type | Int | 是 | 廣告操作行為： 0 - 落地頁 1 - 下載 2 - 喚醒 3 - 小程序廣告 | | ad_type | Int | 否 | 廣告類型： 1 - Banner 2 - 開屏 3 - 插屏 4 - 信息流 5 - 激勵視頻 | | is_gdt | Int | 否 | 是否廣點通: 0 - 不是 1 - 是 | | replace | Int | 是 | 是否需要宏替換: 0 - 不需要 1 - 需要 | | deeplink | String | 否 | Deeplink地址 | | market_url| String | 否 | 應用商店直投schema地址,用于直接打開應用商店詳情頁 | | clk | String | 是 | 落地頁/點擊行為地址，優先級: deeplink > market_url > clk | | clk_time | Int| 否 | 點擊事件觸發的時間，單位：秒，距離曝光的時間。不傳或0默認正常處理后續廣告行為 | | over_time | Int| 否 | 超時時間，單位秒，當因滅屏導致程序中斷時間超過該設置時間時，后續廣告行為不處理。不傳或0默認不處理超時，正常處理后續廣告行為 | | **applet_id** | String | 否 | ?程序原始ID，格式:gh\_xxxxxxx | | **applet_path** | String | 否 | ?程序??的可帶參路徑，schema | | **applet_appid** | String | 否 | ?程序id，格式:wxexxxxxxx | | ua| String | 否 | 后續上報事件、訪問素材以及落地頁URL需要使用的UA，沒有時默認傳客戶端ua | | event | Event **Object** | 是 | 事件行為,使用GET請求上報 | | video | Video **Object**| 否 | 激勵視頻信息 | | video_event| VideoEvent **Object** | 否 | 激勵視頻事件行為,使用GET請求上報 | | appinfo| App **Object** | 是 | App信息 | ### Event | 字段 | 類型 | 是否必填 | 備注 | | --- | --- | --- | --- | | wurls | []String | 否 | 競勝上報數組| | lurls | []String | 否 | 競敗/曝光失敗上報數組，替換宏\_\_ACTION_LOSS\_\_ : 曝光失敗原因(0:價格過低 1:不通過審核 2:頻率攔截 3:其他)| | show | []String | 是 | 展示跟蹤鏈接數組，對接廣告位客戶端需要獲取show里的所有鏈接進行逐條上報。上報時,http header頭中需要增加User-Agent屬性，下同！ | | click | []String | 是 | 點擊跟蹤鏈接數組，對接廣告位客戶端需要獲取click 里的所有鏈接進行逐條上報。 | | start_down| []String | 否 | 開始下載上報數組| | down_done| []String | 否 | 下載完成上報數組 | | start_install| []String | 否 | 開始安裝上報數組 | | install_done| []String | 否 | 安裝完成上報數組 | | open_app_success | []String | 否 | deeplink 打開成功后上報數組 | | open_app_false | []String | 否 | deeplink 打開失敗后上報數組 | | open_app_click | []String | 否 | deeplink被點擊(嘗試喚起)，如果為空，無需上報 | | active_app | []String | 否 | 安裝后激活打開App后上報數組 | ### Video | 字段 | 類型 | 是否必填 | 備注 | | --- | --- | --- | --- | | url | String | 是 | 視頻地址 | | cover| String | 否 | 視頻素材封面地址 | | desc | String | 否 | 廣告文本描述，如點擊下載查看詳情等 | | width | Int| 否 | 視頻寬度，像素 | | height | Int| 否 | 視頻高度，像素 | | duration| Float | 否 | 視頻時長（秒） | | end_show_type | Int | 否 | 視頻播放結束顯示尾幀類型: 空/0：沒有 ; 1：圖片url; 2：html頁面?; 3：html url | | end_show_value | String | 否 | 視頻播放結束顯示尾幀值，存放videoEndShowType對應類型的數據 | | html_show_tracking | []String | 否 | 跳轉類廣告落地頁展示上報鏈接 | | html_click_tracking | []String | 否 | 跳轉類廣告落地頁點擊上報鏈接 | | html_close_tracking | []String | 否 |跳轉類廣告落地頁關閉后進行的上報鏈接 | ### VideoEvent | 字段 | 類型 | 是否必填 | 備注 | | --- | --- | --- | --- | | start_tracks| []String | 否 | 視頻開始播放追蹤 url 數組 | | click_tracks| []String | 否 | 視頻播放過程中點擊追蹤 url 數組 | | complete_tracks| []String | 否 | 視頻播放完成追蹤 url 數組 | | skip_tracks| []String | 否 | 視頻跳過播放追蹤 url 數組 | | stop_tracks| []String | 否 | 視頻暫停播放追蹤 url 數組 | | unstop_tracks| []String | 否 | 視頻解除暫停播放追蹤 url 數組 | | mute_tracks| []String | 否 | 視頻靜音追蹤 url 數組 | | unmute_tracks| []String | 否 | 視頻取消靜音追蹤 url 數組 | | play_first_quartile_tracks| []String | 否 | 視頻播放 1/4 追蹤 url 數組 | | play_midpoint_tracks| []String | 否 | 視頻播放 1/2 追蹤 url 數組 | | play_third_quartile_tracks| []String | 否 | 視頻播放 3/4 追蹤 url 數組 | | close_tracks| []String | 否 | 視頻關閉追蹤 url 數組 | ### App | 字段 | 類型 | 是否必填 | 備注 | | --- | --- | --- | --- | | app_name| String | 否 | App名稱 | | package_name| String | 否 | 包名 | | app_version| String | 否 | 應用版本 | | privacy_url | String | 否 | 應用隱私鏈接 | | perm_url | String | 否 | 應用權限鏈接 | | perm_content | String | 否 | 應用權限內容 | | developer| String | 否 | 應用開發者 | | feature_url| String | 否 | 應用功能介紹鏈接 | | size| Int| 否 | 應用大小 | ## Interaction_type 值說明 | 數值 | 說明 | | --- | --- | | 0 | 落地頁是頁面，直接調用瀏覽器打開clk，展示上報 show，點擊上報 click | | 1 | 點擊后落地頁clk是應用下載地址(若deeplink有值，先使用原生方法處理deeplink并單獨觸發clk點擊檢測)，走 event 對象的下載流程，依次展示上報 show，點擊上報 click，開始下載上報 start_down，下載完成上報 down_done ，開始安裝上報 start_instal，安裝完成上報 install_done，激活上報 active_app | | 2 | 喚醒處理，走喚醒流程，展示上報 show，點擊上報 click，喚醒成功 open_app_success，喚醒失敗 open_app_false | 1. 先根據圖片和廣告標題之類的拼揍出一個廣告頁面，頁面出來之后逐條上報 show里的URL 2. 當用戶點擊后逐條上報 click 的 url，點擊后先判斷deeplink如果有值則訪問 deeplink(如果 deeplink 有宏需要替換也得處理),拉起應用，此時上報 open_app_success 里的所有 url。如果失敗，則上報 open_app_false 里的所有 url，并且根據fallback_type值判斷clk鏈接交互方式，默認以webview瀏覽器打開clk ### 點擊廣告流程部分廣告僅部分上報流程，為空則不上報，請注意判別，結合上下文進行合理操作。 ### **優先級: deeplink > market_url > clk** ![](https://img.kancloud.cn/1c/37/1c37a76690a43e90ebdd7b82d125bed2_984x300.png) ## 宏替換 >推薦**左右兩條下劃線，中間一條下劃線** 使用$$、%%等特殊符號會存在兼容問題！！！從而影響上報統計，望知悉！！！ <table> <tr> <th>宏</th> <th colspan="2">說明</th> </tr> <tr> <td>__REQ_WIDTH__</td> <td rowspan="6">廣告位寬高</td> <td>請求時廣告位寬度</td> </tr> <tr> <td>__REQ_HEIGHT__</td> <td>請求時廣告位高度</td> </tr> <tr style="color:red;"> <td>__WIDTH__</td> <td>實際廣告位寬度，單位為物理像素</td> </tr> <tr style="color:red;"> <td>__HEIGHT__</td> <td>實際廣告位高度，單位為物理像素</td> </tr> <tr style="color:red;"> <td>__DP_WIDTH__</td> <td>實際廣告位寬度，單位為邏輯像素</td> </tr> <tr style="color:red;"> <td>__DP_HEIGHT__</td> <td>實際廣告位高度，單位為邏輯像素</td> </tr> <tr> <td>__DISPLAY_LUX__</td> <td rowspan="4">廣告展示區域坐標（坐標定義：以屏幕左上角坐標為原點）</td> <td>左上角橫坐標</td> </tr> <tr> <td>__DISPLAY_LUY__</td> <td>左上角縱坐標</td> </tr> <tr> <td>__DISPLAY_RDX__</td> <td>右下角橫坐標</td> </tr> <tr> <td>__DISPLAY_RDY__</td> <td>右下角縱坐標</td> </tr> <tr style="color:red;"> <td>__DOWN_X__</td> <td rowspan="4">點擊相關 1（絕對坐標定義：以屏幕左上角坐標為原點，單位物理像素）</td> <td>點擊時橫坐標</td> </tr> <tr style="color:red;"> <td>__DOWN_Y__</td> <td>點擊時縱坐標</td> </tr> <tr style="color:red;"> <td>__UP_X__</td> <td>彈起時橫坐標</td> </tr> <tr style="color:red;"> <td>__UP_Y__</td> <td>彈起時縱坐標</td> </tr> <tr style="color:red;"> <td>__DOWN_OFFSET_X__</td> <td rowspan="4">點擊相關 2（相對坐標定義：以廣告位左上角為原點，單位物理像素）</td> <td>點擊時橫坐標</td> </tr> <tr style="color:red;"> <td>__DOWN_OFFSET_Y__</td> <td>點擊時縱坐標</td> </tr> <tr style="color:red;"> <td>__OFFSET_X__</td> <td>彈起時橫坐標</td> </tr> <tr style="color:red;"> <td>__OFFSET_Y__</td> <td>彈起時縱坐標</td> </tr> <tr style="color:red;"> <td>__DP_DOWN_X__</td> <td rowspan="4">點擊相關 3（相對坐標定義：以廣告位左上角為原點，單位邏輯像素）</td> <td>點擊時橫坐標</td> </tr> <tr style="color:red;"> <td>__DP_DOWN_Y__</td> <td>點擊時縱坐標</td> </tr> <tr style="color:red;"> <td>__DP_UP_X__</td> <td>彈起時橫坐標</td> </tr> <tr style="color:red;"> <td>__DP_UP_Y__</td> <td>彈起時縱坐標</td> </tr> <tr> <td>__BUTTON_LUX__</td> <td rowspan="4">廣告按鈕區域坐標（坐標定義：以屏幕左上角坐標為原點）</td> <td>左上角橫坐標</td> </tr> <tr> <td>__BUTTON_LUY__</td> <td>左上角縱坐標</td> </tr> <tr> <td>__BUTTON_RDX__</td> <td>右下角橫坐標</td> </tr> <tr> <td>__BUTTON_RDY__</td> <td>右下角縱坐標</td> </tr> <tr> <td>__READY_TIME__</td> <td colspan="2">所有?告素材下載完成時的當前時間戳，精確到毫秒(13 位)</td> </tr> <tr style="color:red;"> <td>__TS__</td> <td colspan="2">執行時間戳秒級</td> </tr> <tr style="color:red;"> <td>__MTS__</td> <td colspan="2">執行時間戳毫秒級替換 13位</td> </tr> <tr> <td>__EVENT_TIME_START__</td> <td colspan="2">事件開始時 13位時間戳，單位毫秒</td> </tr> <tr> <td>__EVENT_TIME_END__</td> <td colspan="2">事件結束時 13位時間戳，單位毫秒</td> </tr> <tr> <td>__LONGITUDE__</td> <td colspan="2">經度，沒有則替換為 0</td> </tr> <tr> <td>__LATITUDE__</td> <td colspan="2">緯度，沒有則替換為 0</td> </tr> <tr> <td>__UA__</td> <td colspan="2">UserAgent,客戶端 UA,需要 URLEncode</td> </tr> <tr> <td>__IP__</td> <td colspan="2">客戶端IP地址</td> </tr> <tr> <td>__MAC__</td> <td colspan="2">設備 mac 地址</td> </tr> <tr> <td>__MAC_M__</td> <td colspan="2">設備的 mac 地址，字符串，保留分隔符“:”，轉大寫，然后 MD5 加密</td> </tr> <tr> <td>__MAC_MS__</td> <td colspan="2">設備的 mac 地址，字符串，去除分隔符“:”，轉大寫，然后 MD5 加密</td> </tr> <tr> <td>__IMEI__</td> <td colspan="2">IMEI，Android 設備的 IMEI 號</td> </tr> <tr> <td>__IMEI_M__</td> <td colspan="2">Android 設備的 IMEI 號,MD5 加密</td> </tr> <tr> <td>__ANDROIDID__</td> <td colspan="2">Android ID</td> </tr> <tr> <td>__ANDROIDID_M__</td> <td colspan="2">Android ID,MD5 加密</td> </tr> <tr> <td>__OAID__</td> <td colspan="2">Android 廣告標識符</td> </tr> <tr> <td>__IDFA__</td> <td colspan="2">idfa，iOS 設備的 IDFA</td> </tr> <tr> <td>__CLICKAREA__</td> <td colspan="2">點擊區域：1-廣告素材；2-按鈕</td> </tr> <tr> <td>__CLICK_ID__</td> <td colspan="2">點擊唯一ID</td> </tr> <tr> <td>__DP_REASON__</td> <td colspan="2">調起失敗原因，調起失敗時必填：1-被攔截，2-應用未安裝，3-調起異常</td> </tr> <tr> <td>__DP_RESULT__</td> <td colspan="2">deeplink 調起結果：0-成功，1-失敗</td> </tr> <tr> <td>__VIDEO_TIME__</td> <td colspan="2">視頻總時長(s)</td> </tr> <tr> <td>__BEGIN_TIME__</td> <td colspan="2">視頻播放開始時間(s)</td> </tr> <tr> <td>__END_TIME__</td> <td colspan="2">視頻播放結束時間(s)</td> </tr> <tr> <td>__PROGRESS__</td> <td colspan="2">視頻?告播放的進度，單位秒</td> </tr> <tr> <td>__PROGRESS_MS__</td> <td colspan="2">視頻?告播放的進度，單位毫秒</td> </tr> <tr> <td>__RATE__</td> <td colspan="2">視頻?告播放的進度，百分比</td> </tr> <tr> <td>__LW_BID_PRICE__</td> <td colspan="2">曝光價格原值，取整，單位分，競價必須！</td> </tr> <tr> <td>__SLD__</td> <td colspan="2">廣告交互方式: 0 - 常規觸屏點擊 1 - 滑動點擊 2 - 搖一搖 3 - 自定義手勢 5 - 扭一扭 6 - 擦除</td> </tr> <tr> <td>__TARGET_APP_INSTALL__</td> <td colspan="2">目標app是否安裝, 喚醒類廣告觸發點擊上報時進行替換，用于判定目標app是否安裝； * 枚舉值：0/1；0代表未安裝，1代表安裝 * 判斷依據： * 喚醒時判斷目標app是否安裝； * 點擊后宿主app是否被置于后臺；</td> </tr> </table> > 所有上報鏈接里都可能含有上面宏，都需要替換坐標，特別注意，落地頁 clk 也可能含有坐標宏需要替換比如 click 里的一條 url 包含“\_\_DOWN_X_\_ ”這個字符，那你就得用你按下時的坐標比如210，去替換這個值 ## 廣點通廣告處理僅針對于**喚醒類**預算(即 deeplink有值時)，且**is_gdt** 值為 1 時，執行正常喚醒操作；當喚起目標app失敗時，則使用點擊響應data JSON對象的**dstlink**進行跳轉；僅針對于**下載類**預算(即 Interaction\_type=1)，且**is_gdt** 值為 1 時：需要 http get 二次請求 clk，以便獲取到最終的下載地址以及后續下載、安裝監測需要用clickid 替換里面的\_\_CLICK_ID__ 的字段。二次請求的響應格式如下： ``` { "ret":0, "data":{ "dstlink":"http://xxx/xxx.apk", "clickid":"xxxxxxxxxxx" } } ``` 廣點通坐標替換處理點： 1、廣告位相對坐標 \_\_DOWN_OFFSET_X\__ 、\_\_DOWN_OFFSET_Y\__、 \_\_OFFSET_X\__、 \_\_OFFSET_Y\__ 、\_\_WIDTH__、\_\_HEIGHT__這些值必須替換 2、替換的坐標不能超出廣告點擊區域，例如（廣告位的實際寬高：600*300,那點擊的x和y一定在600和300里面） 3、宏替換在**clk**中有，點擊上報鏈接**click**中也有，點擊上報鏈接中的宏也都要替換，替換的值和**clk**中的一樣。 | 字段 | 類型 | 描述 | | --- | --- | --- | | ret | Int | 0 表示返回值正常，當 ret 返回錯誤值時，不打開落地頁，不發送后續監測上報 | | dstlink | String | 真正的下載地址，客戶端解析 json 后直接請求該地址開始下載 app。 | | clickid | String | 點擊 ID。需緩存下來，用于后續點擊、下載事件上報（轉化上報）。替換上報中的宏變量\_\_CLICK_ID__| ## 請求示例 ``` { "api_version": "1.4.0", "app_name": "抖音短視頻", "pkg_name": "com.ss.android.ugc.aweme", "app_version": "5.6.0", "make": "Oppo", "brand": "Oppo", "model": "Oppor15", "hwv": "5s", "android_id": "83ae257b377746ec", "auidmd5": "523AB7C8EA18A674C4A085E354818AAB", "auidsha1": "bc4520537f6e32940c2e291b0a999bf079c17376", "imei": "867905025513807", "imeimd5": "B7B46DA7A31349518CD8E87857DDEC8A", "imeisha1": "69db2ef0feb8048321b8a14cd2888e42f7f9771d", "imsi": "7512a3c480f43980dc1c45738c078921", "ua": "Mozilla/5.0 (Linux; Android 8.1.0; M1816 Build/O11019; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/65.0.3325.109 Mobile Safari/537.36", "mac": "90:f0:52:40:c5:a1", "net_type": 1, "density": 1.5, "screen_width": 1080, "screen_height": 1920, "dpi": 326, "ppi": 441, "platform": 1, "os": "Android", "os_version": "10.1", "osapilevel": 8.0, "ip": "223.104.65.150", "screen_orient": 1, "serialno": "008d4305e9ab2653ce4ce86704f3cf3f", "carrier": 1, "latitude": 0, "longitude": 0, "iccid": "008d4305e9ab2653ce4ce86704f3cf3f", "bssid": "", "pkgs": "", "mnc": "", "mcc": "", "oaid": "846359299220", "ad_width": 350, "ad_height": 150, "support_deeplink": 1, "installed": [ "com.kuaishou.nebula", "com.sina.news", "com.smile.gifmaker", "com.ss.android.ugc.aweme.lite", "com.ss.android.ugc.aweme", "com.quark.browser", "com.wuba", "com.dragon.read", "com.baidu.searchbox", "com.anjuke.android.app", "com.eg.android.AlipayGphone", "com.UCMobile", "com.qqjh.easyclean", "cn.emagsoftware.gamehall", "com.tencent.qqlivekid", "com.tencent.qqlive", "com.tencent.map" ]} ``` ## 響應數據 ``` { "code": 0, "msg": "OK", "unique": "30f3cdb46c61f4", "data": [{ "title": "開屏測試廣告", "desc": "", "ad_width": 720, "ad_height": 1280, "clk": "http://download.alicdn.com/wireless/taobao4android/latest/702757.apk", "deeplink": "", "replace": 0, "interaction_type": 1, "imgs": [ "http://cdn.cloudmob.xyz/img/pg_20200416105713.jpg" ], "event": { "show": [ "http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=show" ], "click": [ "http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=click" ], "start_down": [ "http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=start_down" ], "down_done": [ "http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=down_done" ], "start_install": [ "http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=start_install" ], "install_done": [ "http://ssp2.com/media/ads_report?&action=install_done" ], "open_app_success": [ "http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=open_app_success" ], "open_app_false": [ "http://ssp2.com/media/ads_report?action=open_app_false" ], "active_app": [ "http://ssp2.com/media/ads_report?e=3Z97ZrBsMcXZrhy8dbUgu9Xz_MuQiaQzM8nbp06_f6xW0GhqvNw9BeDnpnAvxHbdBeZSLR9fDtDnF7g7MFCysau6HxcsS4o8NnPCry8vgj4&action=active_app" ] }, "appinfo": { "app_name": "", "package_name": "" } }] } ``` ## 激勵視頻響應示例 ``` { "code": 0, "msg": "OK", "unique": "AUdisTexOhjpjDgr1611041011", "data": [{ "title": "", "desc": "這是什么神仙游戲，掛機就能領紅包，提現秒到賬！", "ad_width": 0, "ad_height": 0, "clk": "http://down-ddz.734399.com/download/shandianapi/shandian3-awddz-release0529.apk", "ad_type": 5, "interaction_type": 1, "replace": 1, "deeplink": "", "imgs": [ ], "event": { "show": [ "http://ssp.com/media/ads_report?" ], "click": [ "http://ssp.com/media/ads_report?" ], "start_down": [ "http://ssp.com/media/ads_report?" ], "down_done": [ "http://ssp.com/media/ads_report?" ], "start_install": [ "http://ssp.com/media/ads_report?" ], "open_app_success": [] }, "video": { "url": "http://static.wannuosili.com/material/1610957675.685468_46_tmpb8huo0kk.webm", "width": 720, "height": 1280, "size": 0, "duration": 34 }, "video_event": { "start_tracks": [ "https://adx.test.com/ssp/report?t=v" ], "click_tracks": [ "https://adx.test.com/ssp/report?t=v" ], "complete_tracks": [ "https://adx.test.com/ssp/report?t=v" ], "skip_tracks": [ "https://adx.test.com/ssp/report?t=v" ], "mute_tracks": [ "https://adx.test.com/ssp/report?t=v" ], "unmute_tracks": [ "https://adx.test.com/ssp/report?t=v" ], "play_first_quartile_tracks": [ "https://adx.test.com/ssp/report?t=v" ], "play_midpoint_tracks": [ "https://adx.test.com/ssp/report?t=v" ], "play_third_quartile_tracks": [ "https://adx.test.com/ssp/report?t=v" ] }, "appinfo": { "app_name": "", "package_name": "com.awpanda.pandaddz" } }] } ``` ## 返回狀態碼 | 狀態碼 | 說明 | | --- | --- | | 0 | 廣告請求成功，有廣告填充 | | 1 | 無廣告填充！ | | 其他 | 其他錯誤 | ## 附件 ### 1.參數boot\_mark和update\_mark **boot\_mark iOS參考代碼** ![](https://img.kancloud.cn/d7/d7/d7d7ddda4db27457bd75ce0e8ccf6546_1160x648.png) **boot\_mark Android參考代碼** ![](https://img.kancloud.cn/68/68/686800c8efdb2f22f3ab03733b1d8882_1152x776.png) **update\_mark iOS參考代碼** ![](https://img.kancloud.cn/31/75/317557301a04fe521b6d803c99803a31_1160x720.png) **update\_mark Android參考代碼** ![](https://img.kancloud.cn/83/7d/837dd7a5e0c73505305b039e6e628c0d_1160x560.png) ### 2.阿里aaid參數集成 [查看ali_aaid集成方式](http://ssp.ibluefrog.com/doc/Ali_AAID_API%E6%8E%A5%E5%85%A5%E6%96%87%E6%A1%A3_v0310.pdf)