ORTB
…
OMID 分册导航

开放测量：OMID 与 OM SDK

IAB Tech Lab · OMID 1.6
本页目录

为什么需要统一的测量接口

第三方测量要成立，测量方必须能取得与广告展示同期发生的客观数据：广告视图的几何位置、遮挡情况、播放进度与曝光时点。这些数据只能由渲染方（广告 SDK、播放器或发布方应用）观察到，测量方无法自行采集，只能依赖渲染方提供。

在开放测量接口定义（Open Measurement Interface Definition，OMID）之前，视频广告的这类能力由视频播放器-广告接口定义（Video Player-Ad Interface Definition，VPAID）承担：测量代码与交互逻辑都运行在广告可执行文件内，播放器与广告互相依赖。VPAID 已被官方标注弃用并正在淘汰，验证职责由 OMID 接替、交互职责由安全交互媒体接口定义（Secure Interactive Media Interface Definition，SIMID）接替；VAST 4 的模型据此把媒体与可执行文件分离。

OMID 的做法是定义一套接口：渲染方创建广告会话并派发事件，OM 服务（OM Service）计算几何与遮挡并把事件转发给验证脚本（verification script），测量方据此独立判定并上报。接口本身不规定测量方法学，也不规定上报格式与目的地——各方测得的口径差异因此可以被解释，而不是被隐藏。

这套接口对从业者的意义集中在三点：

  • 口径可比会话显式声明创意类型（CreativeType）与曝光判定口径（ImpressionType），不同测量方对同一次展示的差异有共同参照。
  • 测量独立验证脚本由测量厂商提供并自行上报，渲染方只负责派发事件，不产出测量结论。
  • 跨端一致同一套会话与事件模型覆盖 JavaScript、iOS、Android 三条实现线，联网电视（Connected TV，CTV）在 JS 实现内扩展。

三方角色与会话内数据流

  • 集成方

    广告 SDK / 发布方应用

    会话客户端（session client）：omid-session-client-v1.js、OM SDK iOS、OM SDK Android

    • 创建广告会话，声明创意类型（CreativeType）与曝光判定口径（ImpressionType）
    • 注册本次会话应接收事件的验证脚本资源（VerificationScriptResource）
    • 传递创意元素或元素边界，供 OM 服务计算几何与遮挡
    • 派发曝光、素材加载与媒体播放事件
    • 结束会话；异常时先上报错误类型与描述

  • OM 服务

    OMID JS Service / 原生 SDK 服务层

    Web 场景以 iframe 承载，其他 iframe 通过名为 omid_v1_present 的 iframe 探测其可用性

    • 接收集成方消息并维护会话状态（是否运行、是否已注册广告/媒体事件、创意是否已加载）
    • 注入验证脚本资源并承载其与客户端之间的通信（同文档、跨域 iframe、不可见 WebView 或无 DOM 环境）
    • 计算广告视图几何、遮挡与不可度量成因
    • 向验证脚本派发会话事件（sessionStart / geometryChange / impression / sessionError / sessionFinish）与媒体事件

  • 验证脚本

    测量厂商

    验证客户端（verification client）：omid-verification-client-v1.js，由厂商在构建期并入自己的脚本

    • 以 registerSessionObserver 订阅会话事件，以 addEventListener 订阅指定事件类型
    • 在受限环境中改用 sendUrl 发起网络请求、injectJavaScriptResource 注入脚本、受控定时器代替原生定时器
    • 自行判定并上报测量结果；OMID 不定义上报格式与目的地
    • 会话结束时按 sessionFinish 做清理与结题上报

一次会话的消息顺序

下表为一次广告会话从创建到结束的消息顺序。步骤只表示先后关系，不代表各端的调用约束完全相同；完整时序约束见「会话生命周期与所有权」分册。

  1. 1集成方OM 服务创建会话上下文：会话方标识、验证脚本资源、创意元素、内容 URL代表调用new AdSession(context) · AdSession.createAdSession(configuration, context)
  2. 2OM 服务验证脚本注入验证脚本资源并建立通信代表调用VerificationClient.registerSessionObserver(callback, vendorKey)
  3. 3集成方OM 服务声明创意类型与曝光判定口径代表调用setCreativeType(creativeType) · setImpressionType(impressionType)
  4. 4集成方OM 服务注册事件所有权：本次会话由谁派发广告事件与媒体事件代表调用registerAdEvents() · registerMediaEvents()
  5. 5集成方OM 服务启动会话（移动应用环境中由原生 SDK 拥有，JS 侧调用无效果）代表调用start()
  6. 6OM 服务验证脚本派发 sessionStart：携带 context 与 verificationParameters，是会话的首个事件代表调用SessionEvent(type: 'sessionStart', data)
  7. 7OM 服务验证脚本持续派发 geometryChange：广告视图几何、遮挡与不可度量成因码代表调用AdEvent(type: 'geometryChange', data)
  8. 8集成方OM 服务声明素材加载完成与曝光发生代表调用AdEvents.loaded(vastProperties) · AdEvents.impressionOccurred()
  9. 9集成方OM 服务派发媒体播放事件：start 与三个四分位、complete、暂停恢复、缓冲、跳过、音量、播放器状态、用户交互代表调用MediaEvents.start(duration, mediaPlayerVolume) … complete()
  10. 10OM 服务验证脚本转发 impression 与媒体事件给已订阅该事件类型的验证脚本代表调用VerificationClient.addEventListener(eventType, callback)
  11. 11集成方OM 服务结束会话；不可恢复错误先上报，sessionError 不替代 sessionFinish代表调用error(errorType, message) → finish()
  12. 12OM 服务验证脚本派发 sessionFinish：会话的最后一个事件，验证脚本据此清理并做结题上报代表调用SessionEvent(type: 'sessionFinish')

广告格式承载点

  • 请求侧OpenRTB / AdCOM

    请求侧声明能力与会话方标识：广告位是否支持 OMID、创意是否要求 OMID、由哪个集成方驱动会话。

    • imp.{banner,video,audio,native}.api 取值 7（AdCOM APIFrameworks 的 OMID-1）：广告位支持 OMID
    • bid.apis（OpenRTB 2.x 为 bid.api）取值 7：创意要求 OMID
    • source.ext.omidpn / source.ext.omidpv：OMID Partner 对象的 name 与 versionString
    • Native 广告以 event 取值 555 的自定义事件追踪器承载验证脚本，配合 ext.vendorKey 与 ext.verification_parameters
    进入分册

  • 响应侧VAST 4.x

    响应侧下发验证脚本资源本身：资源地址、厂商标识与厂商参数。VPAID 弃用后，其验证职责由 OMID 承接。

    • AdVerifications / Verification 元素（官方 4.0 XSD 已在 InLine 与 Wrapper 双侧声明），Verification@vendor 给出厂商标识（如 company.com-omid）
    • JavaScriptResource@apiFramework="omid" 标识 OMID 资源；@browserOptional 自 4.1 起入库（官方 4.0 XSD 未声明）
    • VerificationParameters 自 4.1 起入库，承载厂商自定义参数
    • 宏 [VERIFICATIONVENDORS] 填充验证厂商列表、[OMIDPARTNER] 填充 Partner 标识（格式 name/versionString）
    进入分册

版本演进

OM SDK 的库版本按端各自发布。下表记录 OM SDK JS 的发布节点，取自官方仓库 CHANGELOG.md。

记录范围

  1. JS 客户端公开发布（2018）

    OM SDK JS 以 1.1.0 为首个正式可用版本发布，随后客户端代码公开到 GitHub 仓库；1.2.0 起浏览器集成成为支持场景。

    • OM SDK JS 1.1.0 发布，官方 CHANGELOG 记为首个正式可用（General Availability）版本。
    • OM SDK JS 客户端代码公开到 GitHub 仓库（1.1.3），并附带构建文件、README 与 CHANGELOG。
    • OM SDK JS 1.2.0：验证脚本处于友好 iframe（friendly iframe）时改用直接通信而非 postMessage；移除「曝光事件必须先于其他事件发送」的限制。

  2. 会话分类与事件命名统一（1.3，2019）

    1.3 是一次重大更新：媒体类型改由创意类型表达、事件类型 video 改名 media、会话类型增加 javascript 取值。OMID 1.2 的脚本仍可运行，但集成方需要改代码。

    • OM SDK 1.3.0（重大更新）：属性 mediaType 由 creativeType 取代、事件类型 video 由 media 取代、adSessionType 增加 javascript 取值、loaded 事件适用于展示广告会话、错误事件可有 media 类型；sessionStart 增加 supportsLoadedEvent 与 contentUrl，loaded 增加 creativeType / mediaType / impressionType，impression 增加 creativeType / impressionType，geometryChange 增加 pixels / friendlyObstructions / declaredFriendlyObstructions。官方说明 1.2 脚本仍可运行，集成方需改代码，迁移指南随 Android 与 iOS 发布包提供。

  3. CTV 支持（1.4–1.5，2022–2024）

    1.4 引入联网电视（Connected TV，CTV）所需的事件与上下文字段，1.5 落到具体电视平台（Samsung Tizen、LG webOS）并给出 CTV 参考应用。

    • OM SDK 1.4.0（重大更新）：增加联网电视（Connected TV，CTV）支持——Context 定义增加 DeviceCategory、增加 CTV 的最后活动时间信号（lastActivityTime 进入验证事件 schema 与 event-typedefs）、遮挡成因增加 noOutputDevice 并纳入可见性计算；移除未使用的 adId 字段。
    • OM SDK 1.5.0（重大更新）：OM Web SDK 增加 LG webOS 与 Samsung Tizen 支持，提供 Web CTV 参考应用，为两平台增加 appId 与 deviceInfo 及设备音量检测；由 JS 管理的会话不再标记为评估中（under evaluation）。

  4. 访问模式收敛与设备认证（2025 起）

    domain 访问模式被移除、访问模式收敛为 full 与 limited 两种；1.6.0 起增加设备认证，用于应对 CTV 与移动端的设备信息伪造。

    • OM SDK JS 1.5.4：移除 domain 访问模式。此后选择 DOMAIN 会回落为 LIMITED，constants.js 中该取值保留并标注 @deprecated。
    • OM SDK JS 1.5.5：增加 UniversalAdId 支持；验证厂商清单增加 HUMAN；移除 Moat 的 URL 正则，以防该域名被他人接管后冒名。
    • OM SDK 1.6.0（重大更新）：增加 Fire TV 与 Apple 设备的设备认证（device attestation）支持，含面向 Fire TV 的 Privacy Pass Attestation 改造；提供现代版本的会话客户端与验证客户端。验证客户端侧新增 attest 方法。
    • OM SDK JS 1.6.6：向 OmidSessionClient 导出 VideoPlayerState、InteractionType、CreativeType、ErrorType 与 ImpressionType 五个枚举；改进合规与验证事件数据的精度处理。
    • OM SDK JS 1.6.10 发布，为本站 OMID 模块的采集基线（commit b6f12bd）。· last-verified 2026-09-22
  • 上游差异IAB Tech Lab 标准页列出的 OMID 规范版本为 1.0 / 1.2 / 1.3 / 1.4 / 1.5 / 1.6，无 1.1；但 OM SDK JS 的 CHANGELOG.md 含 1.1.0（2018-03-29，首个正式可用版本）至 1.1.4 共五个库版本。二者是规范版本与库版本两套序列，本站按各自出处分别收录，不合并、不推断对应关系。https://iabtechlab.com/standards/open-measurement-sdk/ · vendor/iab-omid-js/CHANGELOG.md
  • 上游差异官方 CHANGELOG.md 的 1.3.0 条目原文含两处拼写瑕疵：「signficant update」与「Atribute adSessionType」。本站按原文收录，不改写上游文本。vendor/iab-omid-js/CHANGELOG.md:342-363（commit b6f12bd）

平台现行状态一览

OMID 的规范本体平台中立，实现分三条线。表中库版本与公开类数取自各端官方文档与本站采集的官方源码。

端实现库版本规范版本公开类官方文档
JavaScriptOM SDK JSOmidSessionClient · OmidVerificationClient1.6.10OMID 1.68docs.iabtechlab.com/omsdk-1.6/js/index.html ↗
iOSOM SDK iOSOMID—OMID 1.612docs.iabtechlab.com/omsdk-1.6/ios/index.html ↗
AndroidOM SDK Androidcom.iab.omid.library · com.iab.omid.library.adsession · com.iab.omid.library.adsession.media—OMID 1.610docs.iabtechlab.com/omsdk-1.6/android/index.html ↗

核心术语

本域高频术语。英文全称在首现处展开；字段级条目（kind = field）以等宽字体标注。

  • OMIDOpen Measurement Interface Definition

    开放测量接口定义：由 OM SDK 或等效服务向验证代码开放的 API。在 VAST 4 的「媒体与可执行文件分离」模型中，OMID 接替 VPAID 承担验证职责（交互职责由 SIMID 承担）。

  • OM SDKOpen Measurement SDK

    互动广告局技术实验室（IAB Tech Lab）主导的项目，产出一套在广告展示时收集并开放创意测量数据的公共库，供验证使用。OMID 是它对外开放的接口定义，OM SDK 是它的实现（分 JavaScript、iOS、Android 三条线）。

  • OM Service

    会话客户端与验证脚本之间的中介：接收集成方派发的会话与媒体事件，向验证脚本转发事件并计算几何数据。Web 场景以 iframe 承载，其他 iframe 通过名为 omid_v1_present（应用内为 omid_v1_present_app、Web 为 omid_v1_present_web）的 iframe 探测 OMID 是否可用。官方自 1.5.6 起建议不要对该 iframe 使用 display:none。

  • Ad Session

    广告会话：OMID 的度量单位。一次会话由集成方创建，声明创意类型与曝光判定口径，注册需要接收事件的验证脚本，经 start 开始、finish 结束；会话期内 OM 服务向验证脚本派发 sessionStart / geometryChange / impression / 媒体事件。

  • Integration Partner

    集成方：广告 SDK 与发布方应用，负责创建并驱动广告会话。会话客户端（session client）即由集成方在构建期并入广告 HTML 或原生应用。

  • Verification Script

    验证脚本：测量厂商提供的可执行代码，经广告格式的验证资源元素下发，在会话期内订阅事件并自行上报测量结果。脚本在构建期并入验证客户端（verification client）源码；运行位置可能是创意所在的同一文档、跨域 iframe、不可见 WebView，或原生广告的无 DOM JavaScript 执行环境。

  • Verification Vendor

    验证厂商：提供验证脚本的测量方。OM SDK JS 内置一份已知厂商 ID 清单（VerificationVendorId：OTHER 1、MOAT 2、DOUBLEVERIFY 3、INTEGRAL_AD_SCIENCE 4、PIXELATE 5、NIELSEN 6、COMSCORE 7、MEETRICS 8、GOOGLE 9、HUMAN 10、MOBIAN 11），按脚本 URL 正则匹配识别；MOAT 已被刻意从 URL 匹配表中移除，官方注释说明其不再运营，且不希望该命名空间被收购旧域名的第三方冒用。

  • Session Client

    会话客户端：集成方使用的 OMID 客户端，产物为 omid-session-client-v1.js（UMD），在 Web 顶层与跨域 iframe 中均可工作。导出 AdSession、AdEvents、MediaEvents、Context、Partner、VerificationScriptResource、UniversalAdId、VastProperties、OmidVersion 等对象。

  • Verification Client

    验证客户端：测量厂商的验证脚本使用的 OMID 客户端，产物为 omid-verification-client-v1.js（UMD）。提供 registerSessionObserver、addEventListener、sendUrl、injectJavaScriptResource、受控定时器与 attest（1.6.0 起）。

  • Access Mode

    访问模式：决定验证脚本能否取得创意元素引用。full 表示验证代码可访问创意元素，且 OM SDK 会在 context 中给出 video / slotElement 引用；limited 只给几何数据。domain 模式已于 1.5.4 移除，选择后回落为 limited。

  • Impression Type

    曝光判定口径：声明本次会话以何种条件记为 OMID 曝光，取值 definedByJavaScript / unspecified / loaded / beginToRender / onePixel / viewable / audible / other。声明口径的目的是让不同测量方之间的曝光差异可被解释；未声明时默认为 unspecified（OMID 1.2 的默认值）。

  • Creative Type

    创意类型：本次会话所测量创意的类型，取值 definedByJavaScript / htmlDisplay / nativeDisplay / video / audio。它同时约束验证脚本的形态——htmlDisplay 下验证脚本可包裹创意或作为资源下发，其余取值下只能作为资源下发；audio 不提供任何可见性数据。1.3 起取代原 mediaType 属性。

  • Geometry Change

    几何变更事件（geometryChange）：广告容器状态变化到使 viewport 或 adView 任一字段与上次上报不同时触发，携带已注册广告视图的完整几何数据（含遮挡与检测到的成因码）。事件数据中的尺寸与位置单位为独立像素（independent pixels），坐标相对屏幕坐标系。

  • Obstruction

    遮挡：覆盖在广告视图之上、影响可见性计算的其他视图或元素。geometryChange 事件按遮挡给出 obstructionClass 与 obstructionPurpose，并以 Reason 枚举解释不可度量的成因（notFound / hidden / backgrounded / pictureInPicture / deviceLocked / viewport / obstructed / clipped / unmeasurable / noWindowFocus / noOutputDevice）。

  • Friendly Obstruction

    友好遮挡：由集成方声明为「属于广告体验一部分、不应算作遮挡」的视图（如自有的播放控件）。1.3 起 geometryChange 事件增加 friendlyObstructions 与 declaredFriendlyObstructions 两个属性；注册 API 仅原生端提供（iOS 为 OMIDAdSession 的 removeAllFriendlyObstructions 等方法与 OMIDFriendlyObstructionType 枚举）。

  • Partner

    会话方标识对象：以 name 与 versionString 声明是哪个集成方（广告 SDK）在驱动本次会话。同一对值在 OpenRTB 侧以 source.ext.omidpn 与 source.ext.omidpv 传递，在 VAST 侧以宏 [OMIDPARTNER]（格式为 name/versionString）填充。

  • Device Attestation

    设备认证：由设备制造商出具隐私保护的认证凭据，使买方能独立核验所购联网电视（Connected TV，CTV）与移动端库存的真实性，用于应对设备信息伪造（device spoofing）。OM SDK 1.6.0 起支持 Fire TV 与 Apple 设备，验证客户端侧以 attest 方法接入。官方实现指南自述为 In Progress。

  • CTVConnected TV

    联网电视：OMID 自 1.4 起支持的场景，在 JS 实现内扩展。1.4 增加 DeviceCategory 与最后活动时间信号，1.5 落到 Samsung Tizen 与 LG webOS 并给出 CTV 参考应用，1.6 增加 Fire TV 与 Apple 设备的设备认证。

  • VPAIDVideo Player-Ad Interface Definition

    视频播放器-广告接口定义：规定广告与媒体播放器之间协议的旧标准，用于实现广告交互与高级视频功能。官方已标注弃用并正在淘汰，验证职责由 OMID 接替、交互职责由 SIMID 接替。

  • libraryVersion

    库版本：各端 OM SDK 实现自己的版本号（如 OM SDK JS 1.6.10）。与规范版本（OMID 1.0 / 1.2 / 1.3 / 1.4 / 1.5 / 1.6）是两套序列——三端各自发布库版本，JS 库的修订号多于规范版本，同号不保证同日。IAB Tech Lab 的合规认证按平台分别记录 libraryVersion 与 partnerVersion。

推荐阅读路径

按「先模型、再 API、再承载」的顺序，六步读完本域主干。

  1. 1会话模型：三方角色、会话生命周期与所有权划分
  2. 2AdSession 与会话构造：集成方侧的调用面
  3. 3AdEvents 与 MediaEvents：事件集与 VAST 追踪事件的对应关系
  4. 4VerificationClient：测量厂商侧的调用面
  5. 5OpenRTB / AdCOM 承载：请求侧如何声明 OMID 能力与会话方标识
  6. 6VAST 承载：响应侧如何下发验证脚本资源

数据源与基线

OM SDK JS 1.6.10（commit b6f12bd，2026-09-22 采集）· 三端公开 API 取自 docs.iabtechlab.com/omsdk-1.6 · 许可 Apache 2.0

IAB Tech Lab OM SDK 标准页 ↗

25 chapters · scripts/gen-omid-spec.mjs

规范收录数据（接口方法、枚举取值、发布记录）取自 IAB Tech Lab 官方源并保留英文原文；站内撰写文案为中英双语。溯源见 data/omid-spec/PROVENANCE.json。