簡介OpenRTB 2.5 中文翻譯文檔是一份計算廣告領(lǐng)域的協(xié)議學(xué)習(xí)資料面向 DSP、SSP、Ad Exchange 開發(fā)者和程序化廣告從業(yè)人員幫助讀者突破英文文檔障礙系統(tǒng)掌握實時競價中請求、響應(yīng)、競價、定向與定價等核心環(huán)節(jié)。文檔對 Bid Request、Bid Response、Impression、User、Device、Site/App、Ext、Bidder Seat、Price Floors 等對象逐一說明并結(jié)合 Bid Request 中如何攜帶用戶、設(shè)備與廣告位信息DSP 如何組織 Bid Response 返回出價和創(chuàng)意以及 Price Floors 對庫存價值的保護(hù)作用展開梳理同時介紹了 GDPR 隱私處理、視頻/音頻/富媒體廣告支持、地理位置精確定位以及基于 JSON 的數(shù)據(jù)交換方式便于對照實際業(yè)務(wù)快速定位字段含義。資源共 1 個 PDF 文件壓縮包僅 1.36MB適合在電腦或移動設(shè)備上隨時查閱。目前已有 709 人學(xué)習(xí)尤其適合正在搭建競價流程知識體系的技術(shù)人員也可作為團(tuán)隊內(nèi)部協(xié)議培訓(xùn)的補充材料。1. 為什么 OpenRTB 2.5 中文翻譯文檔值得你放在手邊做程序化廣告對接最磨人的往往不是寫代碼而是查字段。競價請求里幾十個對象、上百個字段英文原版規(guī)范每個詞都認(rèn)識連起來卻拿不準(zhǔn)這個字段到底要不要上送、填錯了會怎樣。我第一次對接某交易平臺時因為沒有吃透imp下的geo和user下的geo到底誰優(yōu)先線上流量有一半被判成地址不匹配預(yù)算花了大半才發(fā)現(xiàn)問題。OpenRTB 2.5 的中文翻譯文檔本質(zhì)上不是一份翻譯件而是一份能讓中文團(tuán)隊一起評審、一起排錯的工作底稿。它不解決算法問題但能解決字段理解偏差和跨角色溝通成本。適合三類人DSP/SSP 的后端開發(fā)廣告交易平臺的協(xié)議維護(hù)者還有做流量質(zhì)量與反作弊的數(shù)據(jù)工程師。接下來我把翻譯文檔的邊界、查詢方法、代碼對照和實務(wù)陷阱一次講清楚。2. OpenRTB 2.5 在翻譯什么對象模型、版本差異與文檔邊界OpenRTB 2.5 規(guī)范的核心是一張“請求—響應(yīng)”的數(shù)據(jù)契約。翻譯文檔的價值不在逐字翻譯而在于把這條契約里的對象、字段、枚舉和示例理順讓團(tuán)隊在聯(lián)調(diào)時說的不是“那個字段”而是imp.bidfloor。2.1 從 2.3 / 2.4 到 2.5中文翻譯文檔里最容易被帶偏的三個變化如果團(tuán)隊之前用的是 2.3 或 2.4 的中文資料直接切到 2.5 時最容易在同名不同義的地方翻車。第一個變化是“廣告位多格式”的正式化。2.5 里同一個imp可以同時攜帶banner、video甚至native子對象。老版本里一個imp往往只放一種展示類型翻譯文檔如果還按老思路解釋新手會把多格式請求拆成多個imp分別上送結(jié)果競價率明顯下降。我一般會在文檔里專門加一句注釋同一個 impression 下多個展示類型對象可以并存交易平臺會依據(jù)點位與設(shè)備能力做篩選。第二個變化是source對象。2.5 把請求鏈路上的供應(yīng)方信息例如fd、ext正式納入對象模型。很多早期中文資料只講site/app對source一筆帶過。實際排查拿不到完整鏈路時缺的恰恰是它。比如流量經(jīng)過多級中間層source.ext里可能帶有每一級來源標(biāo)識翻譯文檔若沒有解釋反作弊同學(xué)很容易把它當(dāng)成噪音字段丟掉。第三個變化是枚舉值與協(xié)議細(xì)節(jié)調(diào)整。api、protocol、creative_attribute、devicetype這些字段的取值范圍在 2.5 里有新增和廢棄。直接沿用舊版中文文檔里的枚舉表格會很危險因為聯(lián)調(diào)時傳輸?shù)氖菙?shù)字枚舉丟了數(shù)字等于沒有翻譯。判斷一份中文翻譯文檔是否值得采用先看它有沒有標(biāo)注“對應(yīng) 2.5 版本”和“枚舉值變更說明”而不是看它翻譯得是否通順。2.2 BidRequest / BidResponse 的層級結(jié)構(gòu)先建坐標(biāo)再讀字段協(xié)議對象看起來扁平實際是嵌套結(jié)構(gòu)。BidRequest 最上層是id、imp數(shù)組、site/app、device、user、at、tmax。imp下面掛banner/video/native、pmp、bidfloor。device下面掛geo、ext。user下面掛geo、data、ext。如果不把層級畫出來查geo就會出現(xiàn)兩條路徑device.geo是設(shè)備所在地user.geo是用戶注冊地或常駐地的近似位置。先畫一張對象層級縮略圖后面讀什么字段都不會迷路BidRequest ├─ id ├─ imp[] │ ├─ id │ ├─ banner{} │ ├─ video{} │ ├─ native{} │ ├─ pmp{ deals[] } │ ├─ bidfloor │ └─ bidfloorcur ├─ site{} / app{} ├─ device{ geo{}, ext{} } ├─ user{ geo{}, data{} } └─ regs{ coppa, ext }這個縮略圖不是標(biāo)準(zhǔn)圖但它非常管用。中文翻譯文檔如果能帶一張類似的層級圖字段歸屬就不會混。BidResponse 結(jié)構(gòu)相對簡單id、seatbid[]、bidid、cur。seatbid里是seat和bid[]bid里最常引起爭議的是nurl與adm。adm是直接返回的創(chuàng)意代碼或物料地址nurl是通知地址要求買家在此地址發(fā)起創(chuàng)意請求。中文文檔里如果不區(qū)分就會有人把nurl當(dāng)物料地址直接拉取結(jié)果創(chuàng)意一直出不來。注意geo類字段都包含lat/lon和type。type不同經(jīng)緯度的來源與精度也不同翻譯注釋里必須寫明否則數(shù)據(jù)校驗會按錯誤標(biāo)準(zhǔn)攔截。2.3 翻譯文檔與英文規(guī)范的關(guān)系版本、勘誤和擴(kuò)展字段的邊界翻譯文檔永遠(yuǎn)以英文規(guī)范為母本但它不是英文規(guī)范的中文鏡像。規(guī)范是靜態(tài)的翻譯文檔是動態(tài)的要記錄團(tuán)隊踩坑后的結(jié)論。第一記錄版本號和日期。規(guī)范組織會發(fā)修訂版翻譯文檔若不標(biāo)版本三個月后沒人知道它對應(yīng)哪個版本。第二記錄術(shù)語表的來源。規(guī)定哪些詞保留英文原詞哪些詞在項目里有約定俗成的譯法。第三對未翻譯或難以翻譯的字段保留英文原詞。我接手過一個項目有人把intevention這類字段硬譯成“介入”結(jié)果評審時沒人明白改回英文反而一目了然。另一個邊界是ext字段。2.5 規(guī)范里大量ext是開放的規(guī)范只給示例不給完整約束。如果中文翻譯文檔沒有明確標(biāo)注“這是交易平臺自定義字段不是標(biāo)準(zhǔn)字段”聯(lián)調(diào)就會變成黑匣子對方說參考 OpenRTB 2.5實際上走的是imp.ext私有對象。我習(xí)慣把ext單獨列一節(jié)并區(qū)分“規(guī)范示例”與“需向交易平臺確認(rèn)”兩類。翻譯文檔的作用不是替代英文規(guī)范而是給英文規(guī)范做批注。批注里記錄的是團(tuán)隊翻車后的結(jié)論例如“這個字段在視頻場景不填會直接返回 4 開頭錯誤碼”。這樣的文檔才真正值得信任。3. 按對象查還是按場景查把翻譯文檔變成排查工具拿到一份翻譯文檔不要從頭讀到尾。正確用法是把它當(dāng)排查工具像用字典一樣去查。3.1 兩種閱讀順序按對象逐字段讀還是按問題反查新人容易從頭讀到尾但工程場景永遠(yuǎn)是“有一個現(xiàn)象要定位到字段”。所以我建議二八開兩成時間按對象通讀八成時間按問題反查。按對象通讀是從object到字段建立全局觀。按問題反查是從現(xiàn)象出發(fā)。舉個例子iOS 設(shè)備上視頻廣告一直沒有填充。按問題反查的順序是先看請求里device.os是否等于 iOS再看video.protocols是否被對方支持繼續(xù)看imp.bidfloor是否高于平臺心理價最后看bcat是否誤把自己創(chuàng)意分類過濾掉。這個路徑在翻譯文檔里應(yīng)該能一步到位。真正好用的翻譯文檔不是把所有字段整齊排列而是給高頻字段加“常見問題”備注。我見過一份團(tuán)隊自建文檔在regs.coppa字段后面寫“coppa1 表示兒童流量非兒童應(yīng)用千萬不要填否則流量會被直接過濾。”這個備注比翻譯本身值錢得多。3.2 自建“字段索引表”一份可檢索的 Excel 或 Markdown把文檔里的字段抽成索引表是投入最少、收益最高的事。結(jié)構(gòu)可以直接照下面的表頭做字段路徑對象類型必須性取值范圍/枚舉中文說明關(guān)聯(lián)場景字段路徑寫完整路徑例如device.geo.country、imp.bidfloorcur。必須性用 R/R/O 標(biāo)注Required / Recommended / Optional。取值范圍寫枚舉數(shù)字和對應(yīng)的英文、中文。關(guān)聯(lián)場景寫“PMP 私有交易”“視頻請求”“兒童流量”。這份索引表放在 Excel 或 Markdown 都行關(guān)鍵是能全文檢索。我一般會把它拆成兩個工作表請求字段表和響應(yīng)字段表。因為響應(yīng)字段的排查頻率極高尤其是nurl、adm、price。字段多的時候不要按字母排序要按對象分組排序。這樣從問題反查字段時可以順著對象一路找下去。提示字段索引表不要只抄規(guī)范要抄項目里實際用過的值。比如badv和bcat規(guī)范只給語義項目里要記錄廣告分類代碼在哪里查、誰維護(hù)。3.3 字段四步走中文名、定義、取值、示例被問到任何一個字段時用四步走回答第一步中文名。第二步定義。第三步取值類型與單位。第四步一段最小 JSON 示例。這個習(xí)慣能避免“字面翻譯陷阱”。舉個例子banner.wmax字面是“最大寬度”。但實際語義是“橫幅廣告允許的最大寬度”且當(dāng)w/h與wmax/hmax同時存在時平臺有優(yōu)先級差異。再比如topframe有人直接翻譯成“頂部框架”真實含義是“廣告是否在頂層窗口展示”。按字面理解前端參數(shù)就會傳錯。遇到翻譯確實拗口的地方保留英文再補充注釋。中文文檔不需要把每個英文詞都翻譯真正重要的是團(tuán)隊建立共識。硬譯只會制造新的黑話反而不如直接用nurl、adm這樣的原詞。4. 用中文翻譯文檔反推代碼JSON 的逐行注解與字段校驗翻譯文檔最終要落到代碼里才能兌現(xiàn)價值。我習(xí)慣的做法是先看中文翻譯搞懂字段語義再動手寫 JSON 或 Schema 校驗。4.1 一個最小 BidRequest 示例逐行注解以下是最小可用的 BidRequest 示例只保留核心字段{ id: 0a1b2c3d, imp: [ { id: 1, banner: { w: 320, h: 50 }, bidfloor: 0.5, bidfloorcur: CNY, pmp: { private_auction: 1, deals: [ { id: deal-001, bidfloor: 1.2, bidfloorcur: CNY, at: 2 } ] } } ], device: { ua: Mozilla/5.0 (Linux; Android 12; Pixel 6), ip: 203.0.113.42, os: Android, osv: 12, devicetype: 4 }, user: { id: u-abc-123 }, at: 2, tmax: 120, bcat: [IAB-25], badv: [example.com] }邏輯說明id是請求唯一標(biāo)識交易平臺會拿它和響應(yīng)id對應(yīng)。imp是廣告位數(shù)組這里只請求一個 320x50 的橫幅。bidfloor是底價bidfloorcur是底價貨幣必須成對出現(xiàn)否則某些平臺按默認(rèn)美元處理。pmp表示私有交易deals數(shù)組里放的是與指定買家約定的交易 IDprivate_auction1表示只有列表內(nèi)的買家可以參與。參數(shù)說明at是競價方式2 表示密封競價1 表示價格無下限。tmax是最大處理時間單位毫秒。bcat是廣告主類別黑名單IAB-25是某內(nèi)容分類。badv是廣告主域名黑名單這里阻塞了 example.com。devicetype4對應(yīng)手機設(shè)備查翻譯文檔枚舉表會發(fā)現(xiàn) 4 是 Phone不要和 1移動/平板混淆。4.2 BidResponse 解析must-have 字段與空值處理對應(yīng)上述請求的響應(yīng)如下{ id: 0a1b2c3d, seatbid: [ { seat: dsp-001, bid: [ { id: a1, impid: 1, price: 1.8, adid: ad-10086, adomain: [advertiser.example.com], crid: creative-001, w: 320, h: 50, adm: html.../html } ] } ], cur: CNY }邏輯說明響應(yīng)頂層id必須與請求id一致否則交易平臺無法關(guān)聯(lián)。seatbid里每個bid的impid必須對應(yīng)請求里的imp.id。price是競價價格單位是cur這里為 CNY。adm是創(chuàng)意代碼直接返回物料 HTML。nurl如果存在則是通知地址交易平臺會在競價成功通知后請求該地址。參數(shù)說明adomain用于廣告主域名白名單校驗若請求里有badv交易平臺會把這里的內(nèi)容做比對。crid是創(chuàng)意 ID一般與adid配合做頻控與反作弊。w/h必須與請求的 banner 尺寸一致如果不一致交易平臺可能直接丟棄這條出價。注意響應(yīng)里seatbid[].bid[]可以為空數(shù)組表示不競價但頂層id不能為空。解析器要把“空競價”和“協(xié)議錯誤”區(qū)分開否則監(jiān)控會誤報。4.3 常見做法把 JSON Schema 和 protobuf 定義掛在翻譯文檔旁邊如果只是人工看 JSON翻譯文檔已經(jīng)夠用。但工程上要減少遺漏最好把機器校驗規(guī)則也放到翻譯文檔旁邊。我一般會為字段索引表里的 Required 字段生成一份簡化 JSON Schema用工具做上線前校驗。常見做法是寫一個最小腳本讀取請求樣本逐字段對拍翻譯文檔里的必填項jq .imp[] | .id as $imp_id | .banner, .video, .native | select(has(id)|not) bid_request_sample.json這條命令會檢查每個imp對象下是否缺少必填 ID。jq的過濾邏輯并不復(fù)雜關(guān)鍵在于把翻譯文檔里的字段必須性持續(xù)固化成這種機器檢查規(guī)則而不是依賴人工 review。邏輯說明select(has(id)|not)會輸出所有沒有id的展示對象。字段索引表里一旦有imp.id為 Required就應(yīng)該在 CI 里跑類似規(guī)則。這樣翻譯文檔就不只是給人看的也成了機器契約的一部分。5. 翻譯文檔使用避坑5 個實務(wù)陷阱與排查記錄再好的翻譯文檔用錯了地方也會翻車。以下 5 條都是實際發(fā)生過的問題按“現(xiàn)象 → 原因 → 解決”的方式記錄可以直接對照自查。5.1 “Recommended”當(dāng)“Required”用上線后收到一大片超時現(xiàn)象某廣告位接入新流量源后競價請求大量超時交易平臺返回 5 開頭錯誤碼。原因團(tuán)隊按中文翻譯文檔把所有 Recommended 字段都加上必填校驗導(dǎo)致部分字段缺失就拒絕發(fā)請求。但規(guī)范里 Recommended 只是“推薦”不是“必須”。比如imp.banner.h在部分視頻插屏場景可以不填由平臺端自適應(yīng)。過嚴(yán)的校驗把本應(yīng)發(fā)出去的流量拒之門外。解決把字段索引表統(tǒng)一改成三檔Required / Recommended / Optional并讓平臺側(cè)接口配置與翻譯文檔保持一致。Recommended 字段做警告不做硬校驗。5.2 枚舉值漏翻設(shè)備類型表譯錯一位數(shù)據(jù)直接進(jìn)錯模型現(xiàn)象某模型按設(shè)備類型切分效果上線后發(fā)現(xiàn) Android 流量占比異常低。原因翻譯文檔里的devicetype枚舉只翻譯了名稱沒保留數(shù)字編號。實現(xiàn)時按字母順序重新映射把 Phone 和 Tablet 的編號寫反數(shù)據(jù)全部分錯。解決在字段索引表里強制保留“數(shù)字編號 英文名稱 中文翻譯”三列。任何枚舉字段都不允許只寫中文杜絕二次理解。5.3 設(shè)備標(biāo)識相關(guān)字段語義不明GAID/OAID 映射寫反現(xiàn)象歸因數(shù)據(jù)對不上激活和點擊不是同一條設(shè)備記錄。原因在 OpenRTB 2.5 里設(shè)備標(biāo)識一般出現(xiàn)在device.ext或user.ext各家交易平臺字段名不一致。翻譯文檔把它統(tǒng)一成“設(shè)備 ID”沒說明誰是 Android 的 GAID、誰是國產(chǎn)安卓的 OAID、誰是 iOS 的 IDFA。后端點位配置時映射錯位數(shù)據(jù)自然對不上。解決翻譯文檔單獨出一張“設(shè)備標(biāo)識映射表”列出常見交易平臺字段名與對應(yīng)系統(tǒng)。做不到統(tǒng)一時寧可保留原字段英文名也不要含糊翻譯成“設(shè)備 ID”。5.4 拿舊版中文文檔對接新版流量multiformat 支持缺失現(xiàn)象安卓端部分開屏流量無法競價日志顯示請求被對方解析失敗。原因流量方升級到了 2.5 風(fēng)格的多格式請求一個imp同時放了banner和video。但對接方看的是基于 2.3 的中文譯稿解析邏輯只讀取banner遇到多格式請求直接丟出異常。解決升級翻譯文檔到 2.5并在代碼里兼容imp下多個展示對象并存。解析時不要用else if要用多個獨立判斷。5.5 把示例 JSON 當(dāng)完整協(xié)議漏掉必填的 bidfloor 與擴(kuò)展字段現(xiàn)象測試環(huán)境一切正常線上填充率驟降。原因測試請求復(fù)制自文檔示例示例里沒有bidfloor。翻譯文檔沒解釋這是示例最小值實現(xiàn)時完全照搬流量變成了無底價競價而部分平臺對無底價請求不響應(yīng)。解決在翻譯文檔每個示例旁邊標(biāo)注“最小示例實際請求需要按業(yè)務(wù)補全字段”。同時把bidfloor、badv、bcat等項目級字段做成初始化模板不允許從零手寫。6. 讓翻譯文檔真正生效三欄術(shù)語表與每周對照評審一份翻譯文檔如果只停留在“有人翻譯過”的狀態(tài)很快就會失效。要讓它在團(tuán)隊里持續(xù)生效以下三個動作最有效。6.1 三欄術(shù)語表英文原文、中文譯文、備注不要只做“英文-中文”兩欄。加一欄備注專門記錄邊界條件和項目習(xí)慣。例如英文原文中文譯文備注bidfloor出價底價單位跟隨 bidfloorcur不填可能被部分平臺按 0 處理nurl通知地址競勝后由交易平臺請求不是創(chuàng)意物料地址imp廣告位請求可同時包含 banner/video/native不要拆成多個 imppmp私有交易private_auction1 時僅 deal 列表內(nèi)買家可參與這個表是團(tuán)隊的共同語言新同學(xué)接入時先讀它能少踩一半坑。6.2 每周 Code Review 時對照規(guī)范原文過一遍變更協(xié)議不是天天變但業(yè)務(wù)代碼天天改。我習(xí)慣每周找個半小時把最近改過的請求構(gòu)造代碼和翻譯文檔對一遍。重點看字段必須性、貨幣單位、設(shè)備類型枚舉。這樣做不是走形式是防止某個同學(xué)按自己的理解新造了一個字段。6.3 一個具體技巧用“上線前驗收清單”驗證翻譯文檔可用性把翻譯文檔的要點固化成一張清單每次接新交易平臺前逐項打勾。包含請求 ID 是否在日志中可追蹤、廣告位 ID 是否映射一致、底價字段是否有單位、響應(yīng)解析是否處理空競價、設(shè)備標(biāo)識是否區(qū)分系統(tǒng)、枚舉值是否有數(shù)字編號、擴(kuò)展字段是否單獨評審。我現(xiàn)在接任何新流量源第一件事不是看代碼而是先找對方要協(xié)議版本號再打開翻譯文檔對一遍枚舉和必須性。這個習(xí)慣幫我少發(fā)了無數(shù)次“為什么填充率是 0”的排查消息。希望幫到你。本文還有配套的精品資源點擊獲取