ORTB
…
OMID 分册导航

VerificationClient

接口

本页清单由 scripts/gen-omid-spec.mjs 自 IAB Tech Lab 官方源生成，描述为官方英文原文；采集基线见页尾。 规范收录数据保留英文原文；已提供的中文译文为初稿（draft），打开中英对照可查看原文。

本页目录

定位与职责

验证客户端供测量厂商的验证脚本（verification script）使用：registerSessionObserver 订阅会话事件、addEventListener 订阅指定事件类型、sendUrl 与 injectJavaScriptResource 在受限环境中发起网络请求与注入脚本、setTimeout / setInterval 提供受控定时器，以及 1.6.0 引入的 attest（设备认证）。

所属客户端
验证客户端
端
JavaScript
库版本
1.6.10
公开成员
14

接口面

VerificationClientjs · 14

供验证脚本（verification script）与 OM SDK 服务交互。ENAllows verification scripts to interact with the OM SDK Service.译稿校对中

名称签名返回官方描述
VerificationClientnew VerificationClient(communication)void（官方未提供描述）
  • communication: Communication<?>This parameter is for OM SDK internal use only and should be omitted.
communicationcommunication—VerificationClient 用于与 VerificationService 通信的 Communication 对象。该属性便于测试；若未显式指定，则会构造并使用正确的 Communication。ENCommunication object that the VerificationClient will use to talk to the VerificationService. This parameter is useful for testing. If left unspecified, the correct Communication will be constructed and used.译稿校对中
addEventListeneraddEventListener(eventType, functionToExecute)void订阅广告生命周期事件与度量（metric）事件。事件处理器会以单个参数被调用，该参数含以下字段：'adSessionId'（string）、'timestamp'（number）、'type'（string）、'data'（object）。ENSubscribes to ad lifecycle and metric events. The event handler will be called with a single argument that has the following fields: 'adSessionId': string, 'timestamp': number, 'type': string, 'data': object译稿校对中
  • eventType: AdEventTypeThe event type to subscribe this listener to.
  • functionToExecute: EventCallbackAn event handler to be invoked when the given event type is triggered.
attestattest(requestPayload, callback)void请求调用设备证明（attestation）机制。验证脚本可用本方法调用该设备所支持的证明机制。ENRequests the attestation mechanism to be invoked. This can be used by the verification scripts to invoke the attestation mechanism supported by this device.译稿校对中
  • requestPayload: AttestRequestPayloadcontains attestation details like mechanism name, version and mechanism specific payload
  • callback: AttestCallbackcallback to be executed.
clearIntervalclearInterval(intervalId)void取消重复回调的后续执行。ENCancels further execution of a repeated callback.译稿校对中
  • intervalId: numberThe ID returned from setInterval of the callback to cancel.
clearTimeoutclearTimeout(timeoutId)void在超时回调执行前取消该超时。行为等价于 window.clearTimeout 这一 Web API 方法。ENCancels a timeout before its callback has been executed. Provides behavior equivalent to the window.clearTimeout web API method.译稿校对中
  • timeoutId: numberThe ID returned from setTimeout of the callback to cancel.
getEnvironmentgetEnvironment()Environment|null获取 OM 服务的环境类型——即注入了验证资源的那个 OM 服务，或存在于全局上下文（如 window）中的那个 OM 服务。注意该判断依据所使用的服务二进制文件：omsdk-v1.js（App）或 omweb-v1.js（Web）。该二进制文件通常与 OM SDK 实际运行的环境一致，但也可能存在反例，例如 Web 服务二进制文件运行在移动应用内的 webview 中。ENGets the environment type of the OM Service that either injected the verification resource or is present in the global context (e.g. window). Note that this check is based on which service binary is used: omsdk-v1.js (App) or omweb-v1.js (Web). The binary typically corresponds to the actual environment in which the OM SDK is run, but there may be counterexamples such as the Web service binary running in a webview inside a mobile app.译稿校对中
injectJavaScriptResourceinjectJavaScriptResource(url, successCallback, failureCallback)void将所提供的 JavaScript 资源注入到与验证提供方相同的执行环境中。对所有基于 DOM 的环境（包括 Android 原生广告会话），本方法会向 DOM 追加 script 元素；对原生广告会话，本方法会将该职责委托给 OM SDK 库，由该库负责下载 JavaScript 内容并将其注入执行环境。ENInjects the supplied JavaScript resource into the same execution environment as the verification provider. For all DOM based environments (incl. Android native ad sessions) this will append `script` elements to the DOM. For native ad sessions this will delegate responsibility to the OM SDK library which will be responsible for downloading and injecting the JavaScript content into the execution environment.译稿校对中
  • url: stringThe URL of the JavaScript resource to load into the environment.
  • successCallback: function()Optional callback to be executed if the HTTP request was successful. Does not indicate whether the script evaluation was successful.
  • failureCallback: function()Optional callback to be executed if the script failed to load.
injectionSource已废弃injectionSource()Environment|undefined已弃用（DEPRECATED）：改用 getEnvironment，它同时覆盖注入脚本与内联脚本。获取注入了该验证资源的 OM 服务的环境类型。ENDEPRECATED: use getEnvironment to cover both injected and inline scripts. Gets the environment type of the OM Service that injected the verification resource.译稿校对中
isSupportedisSupported()boolean检查 OMID 是否可用。ENChecks if OMID is available.译稿校对中
registerSessionObserverregisterSessionObserver(functionToExecute, vendorKey)void订阅所有会话事件（'sessionStart'、'sessionError'、'sessionFinish'）。本方法同时表明验证脚本已加载完毕并可接收事件，因此应在初始化时调用。事件处理器会以单个参数被调用，该参数含以下字段：'adSessionId'（string）、'timestamp'（number）、'type'（string）、'data'（object）。ENSubscribes to all session events ('sessionStart', 'sessionError', and 'sessionFinish'). This method also signals that the verification script has loaded and is ready to receive events, so it should be called upon initialization. The event handler will be called with a single argument that has the following fields: 'adSessionId': string, 'timestamp': number, 'type': string, 'data': object译稿校对中
  • functionToExecute: SessionObserverCallbackAn event handler which will be invoked on session events.
  • vendorKey: string
sendUrlsendUrl(url, successCallback, failureCallback)void请求目标 URL。可用于向远端服务器传输数据：将载荷（payload）作为查询参数嵌入 URL 后发起请求。ENRequests the target URL. This can be used to transmit data to a remote server by requesting a URL with the payload embeded into the URL as query arg(s).译稿校对中
  • url: stringThe URL to be requested.
  • successCallback: function()Optional callback to be executed if the request was successfully received (2xx response code).
  • failureCallback: function()Optional callback to be executed if the request was not successfully received (non-success response code or other error).
setIntervalsetInterval(functionToExecute, timeInMillis)number安排一个函数按指定间隔重复调用。行为等价于 window.setInterval 这一 Web API 方法。ENSchedules a function to be called repeatedly at a specified interval. Provides behavior equivalent to the window.setInterval web API method.译稿校对中
  • functionToExecute: function()The callback to execute repeatedly.
  • timeInMillis: numberThe number of milliseconds to wait between callback invocations.
setTimeoutsetTimeout(functionToExecute, timeInMillis)number安排一个函数在指定延迟之后被调用。行为等价于 window.setTimeout 这一 Web API 方法。ENSchedules a function to be called a function after the specified delay. Provides behavior equivalent to the window.setTimeout web API method.译稿校对中
  • functionToExecute: function()The callback to execute after the delay.
  • timeInMillis: numberThe number of milliseconds to wait before invoking the callback.
docs.iabtechlab.com/omsdk-1.6/js/VerificationClient.html ↗

表中已滤除官方源码标注为 friend scoped（不应导出到混淆之外）的成员；曝光与素材加载的公开路径见 AdEvents。

订阅模型

验证脚本有两种订阅方式，回调形态相同：处理函数只收到一个参数，字段为 adSessionId: string、timestamp: number、type: string、data: object。

  • registerSessionObserver(functionToExecute, vendorKey) 订阅全部会话事件（sessionStart、sessionError、sessionFinish）。该方法同时表示验证脚本已加载、可以开始接收事件，故官方要求在初始化时调用。
  • addEventListener(eventType, functionToExecute) 订阅广告生命周期与指标事件。官方对 registerSessionObserver 的描述只列出上述三个会话事件，故 AdEventType 中的 geometryChange、impression 与各媒体事件走 addEventListener 这条路径。
  • injectionSource() 已弃用：官方要求改用 getEnvironment()，因为后者同时覆盖被注入的脚本与内联脚本。

受限环境下的替代能力

验证脚本可能运行在跨域 iframe、不可见 WebView，或原生广告的无 DOM JavaScript 执行环境中，此时不能依赖全局对象上的常规能力。验证客户端为此提供等价替代：

  • sendUrl(url, successCallback, failureCallback)：请求目标 URL，可把载荷作为查询参数嵌入 URL 传往远端服务器。
  • injectJavaScriptResource(url, successCallback, failureCallback)：把 JS 资源注入到与验证方相同的执行环境。基于 DOM 的环境（含 Android 原生广告会话）通过向 DOM 追加 script 元素实现；原生广告会话则把下载与注入的责任委托给 OM SDK 库。
  • setTimeout / clearTimeout / setInterval / clearInterval：官方说明其行为与 window 上的同名 Web API 等价。
  • getEnvironment()：取注入该验证资源、或存在于全局上下文（如 window）中的 OM 服务的环境类型。官方注明判定依据是所用的服务二进制——omsdk-v1.js 对应 App、omweb-v1.js 对应 Web；该二进制通常对应实际运行环境，但存在反例，例如 Web 服务二进制运行在移动应用内的 webview 中。
  • isSupported()：检查 OMID 是否可用。
  • attest(attestPayload, callback)：请求调用本设备支持的认证机制，供验证脚本使用（OM SDK 1.6.0 起的设备认证）。

跨平台命名对照

概念JavaScriptiOSAndroid
script-injector—OMIDScriptInjectorScriptInjector
sdk-entry—OMIDSDKOmid
verification-clientVerificationClient——
  • script-injectoriOS OMIDScriptInjector / Android ScriptInjector：把验证脚本内容注入 HTML 创意；JS 侧由 OM SDK service 完成，无公开类。
  • sdk-entryiOS 为 OMIDSDK（+sharedInstance / -activate），Android 为 Omid（activate(Context) / isActive()）；JS 侧无对应类，服务脚本由 OM SDK service 自行装载。
  • verification-client仅 JS 公开：验证脚本（第三方测量）一律使用 JS 的 OmidVerificationClient，原生 SDK 不含验证客户端。

同一概念在三端的类名对照；空缺表示该端不提供对应类。JS 侧把会话配置折进 Context 与构造参数，iOS / Android 侧则拆为独立的配置与上下文类。

内容取自 IAB Tech Lab 官方源（OM SDK JS 仓库、三端官方 API 文档、OpenRTB 支持通告与 VAST 规范）；规范收录数据保留英文原文，站内撰写文案为中英双语。溯源见 data/omid-spec/PROVENANCE.json。