简介OpenRTB 2.5 中文翻译文档是一份计算广告领域的协议学习资料面向 DSP、SSP、Ad Exchange 开发者和程序化广告从业人员帮助读者突破英文文档障碍系统掌握实时竞价中请求、响应、竞价、定向与定价等核心环节。文档对 Bid Request、Bid Response、Impression、User、Device、Site/App、Ext、Bidder Seat、Price Floors 等对象逐一说明并结合 Bid Request 中如何携带用户、设备与广告位信息DSP 如何组织 Bid Response 返回出价和创意以及 Price Floors 对库存价值的保护作用展开梳理同时介绍了 GDPR 隐私处理、视频/音频/富媒体广告支持、地理位置精确定位以及基于 JSON 的数据交换方式便于对照实际业务快速定位字段含义。资源共 1 个 PDF 文件压缩包仅 1.36MB适合在电脑或移动设备上随时查阅。目前已有 709 人学习尤其适合正在搭建竞价流程知识体系的技术人员也可作为团队内部协议培训的补充材料。1. 为什么 OpenRTB 2.5 中文翻译文档值得你放在手边做程序化广告对接最磨人的往往不是写代码而是查字段。竞价请求里几十个对象、上百个字段英文原版规范每个词都认识连起来却拿不准这个字段到底要不要上送、填错了会怎样。我第一次对接某交易平台时因为没有吃透imp下的geo和user下的geo到底谁优先线上流量有一半被判成地址不匹配预算花了大半才发现问题。OpenRTB 2.5 的中文翻译文档本质上不是一份翻译件而是一份能让中文团队一起评审、一起排错的工作底稿。它不解决算法问题但能解决字段理解偏差和跨角色沟通成本。适合三类人DSP/SSP 的后端开发广告交易平台的协议维护者还有做流量质量与反作弊的数据工程师。接下来我把翻译文档的边界、查询方法、代码对照和实务陷阱一次讲清楚。2. OpenRTB 2.5 在翻译什么对象模型、版本差异与文档边界OpenRTB 2.5 规范的核心是一张“请求—响应”的数据契约。翻译文档的价值不在逐字翻译而在于把这条契约里的对象、字段、枚举和示例理顺让团队在联调时说的不是“那个字段”而是imp.bidfloor。2.1 从 2.3 / 2.4 到 2.5中文翻译文档里最容易被带偏的三个变化如果团队之前用的是 2.3 或 2.4 的中文资料直接切到 2.5 时最容易在同名不同义的地方翻车。第一个变化是“广告位多格式”的正式化。2.5 里同一个imp可以同时携带banner、video甚至native子对象。老版本里一个imp往往只放一种展示类型翻译文档如果还按老思路解释新手会把多格式请求拆成多个imp分别上送结果竞价率明显下降。我一般会在文档里专门加一句注释同一个 impression 下多个展示类型对象可以并存交易平台会依据点位与设备能力做筛选。第二个变化是source对象。2.5 把请求链路上的供应方信息例如fd、ext正式纳入对象模型。很多早期中文资料只讲site/app对source一笔带过。实际排查拿不到完整链路时缺的恰恰是它。比如流量经过多级中间层source.ext里可能带有每一级来源标识翻译文档若没有解释反作弊同学很容易把它当成噪音字段丢掉。第三个变化是枚举值与协议细节调整。api、protocol、creative_attribute、devicetype这些字段的取值范围在 2.5 里有新增和废弃。直接沿用旧版中文文档里的枚举表格会很危险因为联调时传输的是数字枚举丢了数字等于没有翻译。判断一份中文翻译文档是否值得采用先看它有没有标注“对应 2.5 版本”和“枚举值变更说明”而不是看它翻译得是否通顺。2.2 BidRequest / BidResponse 的层级结构先建坐标再读字段协议对象看起来扁平实际是嵌套结构。BidRequest 最上层是id、imp数组、site/app、device、user、at、tmax。imp下面挂banner/video/native、pmp、bidfloor。device下面挂geo、ext。user下面挂geo、data、ext。如果不把层级画出来查geo就会出现两条路径device.geo是设备所在地user.geo是用户注册地或常驻地的近似位置。先画一张对象层级缩略图后面读什么字段都不会迷路BidRequest ├─ id ├─ imp[] │ ├─ id │ ├─ banner{} │ ├─ video{} │ ├─ native{} │ ├─ pmp{ deals[] } │ ├─ bidfloor │ └─ bidfloorcur ├─ site{} / app{} ├─ device{ geo{}, ext{} } ├─ user{ geo{}, data{} } └─ regs{ coppa, ext }这个缩略图不是标准图但它非常管用。中文翻译文档如果能带一张类似的层级图字段归属就不会混。BidResponse 结构相对简单id、seatbid[]、bidid、cur。seatbid里是seat和bid[]bid里最常引起争议的是nurl与adm。adm是直接返回的创意代码或物料地址nurl是通知地址要求买家在此地址发起创意请求。中文文档里如果不区分就会有人把nurl当物料地址直接拉取结果创意一直出不来。注意geo类字段都包含lat/lon和type。type不同经纬度的来源与精度也不同翻译注释里必须写明否则数据校验会按错误标准拦截。2.3 翻译文档与英文规范的关系版本、勘误和扩展字段的边界翻译文档永远以英文规范为母本但它不是英文规范的中文镜像。规范是静态的翻译文档是动态的要记录团队踩坑后的结论。第一记录版本号和日期。规范组织会发修订版翻译文档若不标版本三个月后没人知道它对应哪个版本。第二记录术语表的来源。规定哪些词保留英文原词哪些词在项目里有约定俗成的译法。第三对未翻译或难以翻译的字段保留英文原词。我接手过一个项目有人把intevention这类字段硬译成“介入”结果评审时没人明白改回英文反而一目了然。另一个边界是ext字段。2.5 规范里大量ext是开放的规范只给示例不给完整约束。如果中文翻译文档没有明确标注“这是交易平台自定义字段不是标准字段”联调就会变成黑匣子对方说参考 OpenRTB 2.5实际上走的是imp.ext私有对象。我习惯把ext单独列一节并区分“规范示例”与“需向交易平台确认”两类。翻译文档的作用不是替代英文规范而是给英文规范做批注。批注里记录的是团队翻车后的结论例如“这个字段在视频场景不填会直接返回 4 开头错误码”。这样的文档才真正值得信任。3. 按对象查还是按场景查把翻译文档变成排查工具拿到一份翻译文档不要从头读到尾。正确用法是把它当排查工具像用字典一样去查。3.1 两种阅读顺序按对象逐字段读还是按问题反查新人容易从头读到尾但工程场景永远是“有一个现象要定位到字段”。所以我建议二八开两成时间按对象通读八成时间按问题反查。按对象通读是从object到字段建立全局观。按问题反查是从现象出发。举个例子iOS 设备上视频广告一直没有填充。按问题反查的顺序是先看请求里device.os是否等于 iOS再看video.protocols是否被对方支持继续看imp.bidfloor是否高于平台心理价最后看bcat是否误把自己创意分类过滤掉。这个路径在翻译文档里应该能一步到位。真正好用的翻译文档不是把所有字段整齐排列而是给高频字段加“常见问题”备注。我见过一份团队自建文档在regs.coppa字段后面写“coppa1 表示儿童流量非儿童应用千万不要填否则流量会被直接过滤。”这个备注比翻译本身值钱得多。3.2 自建“字段索引表”一份可检索的 Excel 或 Markdown把文档里的字段抽成索引表是投入最少、收益最高的事。结构可以直接照下面的表头做字段路径对象类型必须性取值范围/枚举中文说明关联场景字段路径写完整路径例如device.geo.country、imp.bidfloorcur。必须性用 R/R/O 标注Required / Recommended / Optional。取值范围写枚举数字和对应的英文、中文。关联场景写“PMP 私有交易”“视频请求”“儿童流量”。这份索引表放在 Excel 或 Markdown 都行关键是能全文检索。我一般会把它拆成两个工作表请求字段表和响应字段表。因为响应字段的排查频率极高尤其是nurl、adm、price。字段多的时候不要按字母排序要按对象分组排序。这样从问题反查字段时可以顺着对象一路找下去。提示字段索引表不要只抄规范要抄项目里实际用过的值。比如badv和bcat规范只给语义项目里要记录广告分类代码在哪里查、谁维护。3.3 字段四步走中文名、定义、取值、示例被问到任何一个字段时用四步走回答第一步中文名。第二步定义。第三步取值类型与单位。第四步一段最小 JSON 示例。这个习惯能避免“字面翻译陷阱”。举个例子banner.wmax字面是“最大宽度”。但实际语义是“横幅广告允许的最大宽度”且当w/h与wmax/hmax同时存在时平台有优先级差异。再比如topframe有人直接翻译成“顶部框架”真实含义是“广告是否在顶层窗口展示”。按字面理解前端参数就会传错。遇到翻译确实拗口的地方保留英文再补充注释。中文文档不需要把每个英文词都翻译真正重要的是团队建立共识。硬译只会制造新的黑话反而不如直接用nurl、adm这样的原词。4. 用中文翻译文档反推代码JSON 的逐行注解与字段校验翻译文档最终要落到代码里才能兑现价值。我习惯的做法是先看中文翻译搞懂字段语义再动手写 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是请求唯一标识交易平台会拿它和响应id对应。imp是广告位数组这里只请求一个 320x50 的横幅。bidfloor是底价bidfloorcur是底价货币必须成对出现否则某些平台按默认美元处理。pmp表示私有交易deals数组里放的是与指定买家约定的交易 IDprivate_auction1表示只有列表内的买家可以参与。参数说明at是竞价方式2 表示密封竞价1 表示价格无下限。tmax是最大处理时间单位毫秒。bcat是广告主类别黑名单IAB-25是某内容分类。badv是广告主域名黑名单这里阻塞了 example.com。devicetype4对应手机设备查翻译文档枚举表会发现 4 是 Phone不要和 1移动/平板混淆。4.2 BidResponse 解析must-have 字段与空值处理对应上述请求的响应如下{ 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 }逻辑说明响应顶层id必须与请求id一致否则交易平台无法关联。seatbid里每个bid的impid必须对应请求里的imp.id。price是竞价价格单位是cur这里为 CNY。adm是创意代码直接返回物料 HTML。nurl如果存在则是通知地址交易平台会在竞价成功通知后请求该地址。参数说明adomain用于广告主域名白名单校验若请求里有badv交易平台会把这里的内容做比对。crid是创意 ID一般与adid配合做频控与反作弊。w/h必须与请求的 banner 尺寸一致如果不一致交易平台可能直接丢弃这条出价。注意响应里seatbid[].bid[]可以为空数组表示不竞价但顶层id不能为空。解析器要把“空竞价”和“协议错误”区分开否则监控会误报。4.3 常见做法把 JSON Schema 和 protobuf 定义挂在翻译文档旁边如果只是人工看 JSON翻译文档已经够用。但工程上要减少遗漏最好把机器校验规则也放到翻译文档旁边。我一般会为字段索引表里的 Required 字段生成一份简化 JSON Schema用工具做上线前校验。常见做法是写一个最小脚本读取请求样本逐字段对拍翻译文档里的必填项jq .imp[] | .id as $imp_id | .banner, .video, .native | select(has(id)|not) bid_request_sample.json这条命令会检查每个imp对象下是否缺少必填 ID。jq的过滤逻辑并不复杂关键在于把翻译文档里的字段必须性持续固化成这种机器检查规则而不是依赖人工 review。逻辑说明select(has(id)|not)会输出所有没有id的展示对象。字段索引表里一旦有imp.id为 Required就应该在 CI 里跑类似规则。这样翻译文档就不只是给人看的也成了机器契约的一部分。5. 翻译文档使用避坑5 个实务陷阱与排查记录再好的翻译文档用错了地方也会翻车。以下 5 条都是实际发生过的问题按“现象 → 原因 → 解决”的方式记录可以直接对照自查。5.1 “Recommended”当“Required”用上线后收到一大片超时现象某广告位接入新流量源后竞价请求大量超时交易平台返回 5 开头错误码。原因团队按中文翻译文档把所有 Recommended 字段都加上必填校验导致部分字段缺失就拒绝发请求。但规范里 Recommended 只是“推荐”不是“必须”。比如imp.banner.h在部分视频插屏场景可以不填由平台端自适应。过严的校验把本应发出去的流量拒之门外。解决把字段索引表统一改成三档Required / Recommended / Optional并让平台侧接口配置与翻译文档保持一致。Recommended 字段做警告不做硬校验。5.2 枚举值漏翻设备类型表译错一位数据直接进错模型现象某模型按设备类型切分效果上线后发现 Android 流量占比异常低。原因翻译文档里的devicetype枚举只翻译了名称没保留数字编号。实现时按字母顺序重新映射把 Phone 和 Tablet 的编号写反数据全部分错。解决在字段索引表里强制保留“数字编号 英文名称 中文翻译”三列。任何枚举字段都不允许只写中文杜绝二次理解。5.3 设备标识相关字段语义不明GAID/OAID 映射写反现象归因数据对不上激活和点击不是同一条设备记录。原因在 OpenRTB 2.5 里设备标识一般出现在device.ext或user.ext各家交易平台字段名不一致。翻译文档把它统一成“设备 ID”没说明谁是 Android 的 GAID、谁是国产安卓的 OAID、谁是 iOS 的 IDFA。后端点位配置时映射错位数据自然对不上。解决翻译文档单独出一张“设备标识映射表”列出常见交易平台字段名与对应系统。做不到统一时宁可保留原字段英文名也不要含糊翻译成“设备 ID”。5.4 拿旧版中文文档对接新版流量multiformat 支持缺失现象安卓端部分开屏流量无法竞价日志显示请求被对方解析失败。原因流量方升级到了 2.5 风格的多格式请求一个imp同时放了banner和video。但对接方看的是基于 2.3 的中文译稿解析逻辑只读取banner遇到多格式请求直接丢出异常。解决升级翻译文档到 2.5并在代码里兼容imp下多个展示对象并存。解析时不要用else if要用多个独立判断。5.5 把示例 JSON 当完整协议漏掉必填的 bidfloor 与扩展字段现象测试环境一切正常线上填充率骤降。原因测试请求复制自文档示例示例里没有bidfloor。翻译文档没解释这是示例最小值实现时完全照搬流量变成了无底价竞价而部分平台对无底价请求不响应。解决在翻译文档每个示例旁边标注“最小示例实际请求需要按业务补全字段”。同时把bidfloor、badv、bcat等项目级字段做成初始化模板不允许从零手写。6. 让翻译文档真正生效三栏术语表与每周对照评审一份翻译文档如果只停留在“有人翻译过”的状态很快就会失效。要让它在团队里持续生效以下三个动作最有效。6.1 三栏术语表英文原文、中文译文、备注不要只做“英文-中文”两栏。加一栏备注专门记录边界条件和项目习惯。例如英文原文中文译文备注bidfloor出价底价单位跟随 bidfloorcur不填可能被部分平台按 0 处理nurl通知地址竞胜后由交易平台请求不是创意物料地址imp广告位请求可同时包含 banner/video/native不要拆成多个 imppmp私有交易private_auction1 时仅 deal 列表内买家可参与这个表是团队的共同语言新同学接入时先读它能少踩一半坑。6.2 每周 Code Review 时对照规范原文过一遍变更协议不是天天变但业务代码天天改。我习惯每周找个半小时把最近改过的请求构造代码和翻译文档对一遍。重点看字段必须性、货币单位、设备类型枚举。这样做不是走形式是防止某个同学按自己的理解新造了一个字段。6.3 一个具体技巧用“上线前验收清单”验证翻译文档可用性把翻译文档的要点固化成一张清单每次接新交易平台前逐项打勾。包含请求 ID 是否在日志中可追踪、广告位 ID 是否映射一致、底价字段是否有单位、响应解析是否处理空竞价、设备标识是否区分系统、枚举值是否有数字编号、扩展字段是否单独评审。我现在接任何新流量源第一件事不是看代码而是先找对方要协议版本号再打开翻译文档对一遍枚举和必须性。这个习惯帮我少发了无数次“为什么填充率是 0”的排查消息。希望帮到你。本文还有配套的精品资源点击获取