OMID chapter navigation

JavaScript (web / webview / CTV)

platform

The listings on this page are generated by scripts/gen-omid-spec.mjs from official IAB Tech Lab sources, with descriptions in the original English; see the page footer for the collection baseline.

On this page

Role & scope
Platform notes
Public class listing
Cross-platform naming
Related chapters

Role & scope

OM SDK JS is the implementation shared by web, in-app WebView and Connected TV (CTV) scenarios, and it produces two UMD binaries: omid-session-client-v1.js, which ad SDKs bundle into the ad HTML at build time, and omid-verification-client-v1.js, which measurement vendors bundle into their verification scripts at build time. Current library version 1.6.10.

Platform: JavaScript
Implementation: OM SDK JS
Library version: 1.6.10
Spec version: OMID 1.6
Public classes: 8
Public members: 62

Platform notes

The build produces three UMD binaries: omid-session-client-v1.js (bundled into the ad HTML by the integration at build time), omid-verification-client-v1.js (bundled into the verification script by the measurement vendor at build time), and omid-compliance-verification-client-v1.js (the compliance verification script).
Three consumption patterns: CommonJS (require, then take OmidVerificationClient), Google Closure (goog.require('omid.verificationClient.VerificationClient'), needing Closure compiler 20200112.0.0 or later), and globals (load and run omid-verification-client-v1.js first so it exports the global, then read it from the verification script).
On the web the OM Service is hosted in an iframe; other iframes detect OMID availability through an iframe named omid_v1_present, whose name varies by service environment — omid_v1_present_web (web) and omid_v1_present_app (in-app). Since 1.5.6 the official guidance is not to use display:none on that iframe, and the web reference app stopped using an iframe in the same release.
The session client works both at the top level of a webview and in a cross-domain iframe. The official class description of AdSession states it enables the integration partner to contribute to an existing native ad session and handles scenarios with limited access to the OM SDK JS service (i.e. cross-domain iframes); consequently start() and finish() have no effect in a mobile app environment.
CTV is extended inside the same JS implementation: 1.4 introduced DeviceCategory and a last-activity signal (lastActivityTime), 1.5 added Samsung Tizen and LG webOS support (with appId, deviceInfo and device volume detection) plus a web CTV reference app, and 1.6 added device attestation for Fire TV.
UniversalAdId and VastProperties are exported onto OmidSessionClient via packageExport in the source (the former added in 1.5.5), but the official JSDoc site publishes no page for either; AdEvents.loaded(vastProperties) therefore references a type that is undocumented on the site.

Public class listing

AdEventsjs · 3

Ad event API enabling the JS component to signal to all verification providers when key events have occurred. The OM SDK JS service will allow only one ad events instance to be associated with the ad session and any attempt to create multiple instances will result in an error.

Name	Signature	Returns	Official description
AdEvents	new AdEvents(adSession)	void	(no official description provided) adSession: AdSessionThe ad session instance for sending events.
impressionOccurred	impressionOccurred()	void	Notifies all verification providers that an impression event should be recorded.
loaded	loaded(vastProperties)	void	Notifies all verification providers that a loaded event should be recorded. Video/audio creatives should supply non-null vastProperties. Display creatives should supply a null argument. vastProperties: VastPropertiescontaining static information about the video placement. This is non-null for video/audio creatives and null for display creatives.

docs.iabtechlab.com/omsdk-1.6/js/AdEvents.html ↗

AdSessionjs · 12

The JS ad session API enabling the integration partner to contribute to an existing native ad session. This is also responsible for communicating to the OM SDK JS service and will also handle scenarios with limited access to the OM SDK JS service - i.e. cross-domain iFrames. This API is commonly used in the following scenarios; - video ad session relying on the HTML5 video player for injecting verification script resources and/or publishing OMID video events. - display ad session relying on a separate JS component to handle the impression event.

Name	Signature	Returns	Official description
AdSession	new AdSession(context, communication, sessionInterface)	void	(no official description provided) context: Contextthat provides the required information for initialising the JS ad session. communication: Communication<?>This parameter is for OM SDK internal use only and should be omitted. sessionInterface: OmidJsSessionInterfaceThis parameter is for OM SDK internal use only and should be omitted.
error	error(errorType, message)	void	Notifies that an error has occurred on the ad session. All verification clients will be notified via the 'sessionError' session observer event. errorType: ErrorTypeHigh level error type. message: stringDescription of the session error.
finish	finish()	void	If there is a currently active ad session, this notifies all session observers that the ad session has finished with a SESSION_FINISH event. This ceases ad view tracking and message sending to verification scripts injected for the ad session. This method has no effect if called if there is no active ad session or in a mobile app environment.
getAdSessionId	getAdSessionId()	string	Get the ID of this ad session.
isSupported	isSupported()	boolean	Returns true if OMID is available, false otherwise.
registerAdEvents	registerAdEvents()	void	Registers the existence of an AdEvent instance.
registerMediaEvents	registerMediaEvents()	void	Registers the existence of an MediaEvents instance.
registerSessionObserver	registerSessionObserver(functionToExecute)	void	Subscribes to all session events ('sessionStart', 'sessionError', and 'sessionFinish'). The event handler will be called with a single argument that has the following fields: 'adSessionId': string, 'timestamp': number, 'type': string, 'data': object functionToExecute: function(Event)An event handler which will be invoked on session events.
setCreativeType	setCreativeType(creativeType)	void	Specifies the type of creative to be rendered in this session. Requires that the native layer set the creative type to DEFINED_BY_JAVASCRIPT. creativeType: CreativeTypeThe type of creative.
setElementBounds	setElementBounds(elementBounds)	void	Set the DOM element's geometry relative to the geometry of either the slotElement or the cross domain iframe the creative's DOM element is in. elementBounds: Rectangle
setImpressionType	setImpressionType(impressionType)	void	Specifies the type of impression to be triggered in this session. Requires that the native layer set the impression type to DEFINED_BY_JAVASCRIPT. impressionType: ImpressionTypeThe type of impression.
start	start()	void	If there is no currently active ad session, this notifies all session observers that an ad session has started with a SESSION_START event. This starts ad view tracking and makes video and ad events available to send to verification scripts injected for this ad session. This method has no effect if called after the ad session has already started or in a mobile app environment.

docs.iabtechlab.com/omsdk-1.6/js/AdSession.html ↗

Contextjs · 11

Holds information provided into the ad session context by the JavaScript layer.

Name	Signature	Returns	Official description
Context	new Context(partner, verificationScriptResources, contentUrl, customReferenceData, universalAdId)	void	Create a new ad session context providing reference to partner and a list of script resources which should be managed by OM SDK service. partner: PartnerThe integration's partner ID and version. verificationScriptResources: Array<VerificationScriptResource>The verification resources to load. contentUrl: stringOn web, the URL of top-level web page. In apps, an optional content URL of the screen within the app that is showing the ad, such as an Android deep link or iOS universal link. Defaults to null. customReferenceData: stringArbitrary reference data the integrator can share with verification scripts. Has no effect in mobile app environment. Defaults to null. universalAdId: UniversalAdId- The UniversalId tag used for creative ID validation. Defaults to null.
contentUrl	contentUrl: string	string	(no official description provided)
customReferenceData	customReferenceData: string	string	(no official description provided)
serviceWindow	serviceWindow: Window	Window	If not null, the window to which service communication should be directed, overriding the default search algorithm.
slotElement	slotElement: HTMLElement	HTMLElement	(no official description provided)
underEvaluation	underEvaluation: boolean	boolean	Whether or not this ad session is under evaluation, as defined by "Evaluation Flag" in the Open Measurement License for Web Video, V 1.0. Ignored in app environments. Defaults to false.
universalAdId	universalAdId: UniversalAdId	UniversalAdId	(no official description provided)
videoElement	videoElement: HTMLVideoElement	HTMLVideoElement	(no official description provided)
setServiceWindow	setServiceWindow(serviceWindow)	void	By default, the OM SDK Session Client Library will assume the Service Script is present in the same frame the library is loaded in, or top. Call this method to override this default and point the library to the give window instead. serviceWindow: WindowThe window containing the OMID Service Script.
setSlotElement	setSlotElement(slotElement)	void	Specifies the ad creative HTML element within the WebView. slotElement: HTMLElementThe ad creative DOM element.
setVideoElement	setVideoElement(videoElement)	void	Specifies the video element within the WebView. videoElement: HTMLVideoElementThe video element.

docs.iabtechlab.com/omsdk-1.6/js/Context.html ↗

MediaEventsjs · 14

Provides a complete list of supported JS media events. Using this event API assumes the media player is fully responsible for communicating all media events at the appropriate times. Only one media events implementation can be associated with the ad session and any attempt to create multiple instances will result in an error. The same rules apply to both multiple JS media events and any attempt to register a JS media events instance when a native instance has already been registered via the native bridge.

Name	Signature	Returns	Official description
MediaEvents	new MediaEvents(adSession)	void	(no official description provided) adSession: AdSessionThe ad session instance for sending events.
adUserInteraction	adUserInteraction(interactionType)	void	Notifies all media listeners that the user has performed an ad interaction. interactionType: InteractionTypeThe latest user interaction.
bufferFinish	bufferFinish()	void	Notifies all media listeners that buffering has finished and media playback has resumed.
bufferStart	bufferStart()	void	Notifies all media listeners that media playback has stopped and started buffering.
complete	complete()	void	Notifies all media listeners that media playback is complete.
firstQuartile	firstQuartile()	void	Notifies all media listeners that media playback has reached the first quartile.
midpoint	midpoint()	void	Notifies all media listeners that media playback has reached the midpoint.
pause	pause()	void	Notifies all media listeners that media playback has paused after a user interaction.
playerStateChange	playerStateChange(playerState)	void	Notifies all media listeners that media player state has changed. playerState: VideoPlayerStateThe latest media player state.
resume	resume()	void	Notifies all media listeners that media playback has resumed (after being paused) after a user interaction.
skipped	skipped()	void	Notifies all media listeners that media playback has stopped as a user skip interaction. Once skipped media it should not be possible for the media to resume playing content.
start	start(duration, mediaPlayerVolume)	void	Notifies all media listeners that media content has started playing. duration: numberDuration of the selected media media (in seconds). mediaPlayerVolume: numberAudio volume of the media player with a range between 0 and 1.
thirdQuartile	thirdQuartile()	void	Notifies all media listeners that media playback has reached the third quartile.
volumeChange	volumeChange(mediaPlayerVolume)	void	Notifies all media listeners that the media player has changed the volume. mediaPlayerVolume: numberAudio volume of the media player with a range between 0 and 1.

docs.iabtechlab.com/omsdk-1.6/js/MediaEvents.html ↗

OmidVersionjs · 1

Represents the Version of OMID Session Client.

Name	Signature	Returns	Official description
OmidVersion	new OmidVersion(semanticVersion, apiLevel)	void	(no official description provided) semanticVersion: string apiLevel: string

docs.iabtechlab.com/omsdk-1.6/js/OmidVersion.html ↗

Partnerjs · 1

Holds information about the integration partner that is using the session client.

Name	Signature	Returns	Official description
Partner	new Partner(name, version)	void	Creates a new partner instance given a name and a version. name: stringThe partner ID of the integration. version: stringThe version of the integration's session script.

docs.iabtechlab.com/omsdk-1.6/js/Partner.html ↗

VerificationClientjs · 14

Allows verification scripts to interact with the OM SDK Service.

Name	Signature	Returns	Official description
VerificationClient	new VerificationClient(communication)	void	(no official description provided) communication: Communication<?>This parameter is for OM SDK internal use only and should be omitted.
communication	communication	—	Communication 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.
addEventListener	addEventListener(eventType, functionToExecute)	void	Subscribes 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.
attest	attest(requestPayload, callback)	void	Requests 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.
clearInterval	clearInterval(intervalId)	void	Cancels further execution of a repeated callback. intervalId: numberThe ID returned from setInterval of the callback to cancel.
clearTimeout	clearTimeout(timeoutId)	void	Cancels 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.
getEnvironment	getEnvironment()	Environment\|null	Gets 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.
injectJavaScriptResource	injectJavaScriptResource(url, successCallback, failureCallback)	void	Injects 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.
injectionSourcedeprecated	injectionSource()	Environment\|undefined	DEPRECATED: use getEnvironment to cover both injected and inline scripts. Gets the environment type of the OM Service that injected the verification resource.
isSupported	isSupported()	boolean	Checks if OMID is available.
registerSessionObserver	registerSessionObserver(functionToExecute, vendorKey)	void	Subscribes 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
sendUrl	sendUrl(url, successCallback, failureCallback)	void	Requests 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).
setInterval	setInterval(functionToExecute, timeInMillis)	number	Schedules 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.
setTimeout	setTimeout(functionToExecute, timeInMillis)	number	Schedules 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 ↗

VerificationScriptResourcejs · 6

Represents a verification script resource that comes in a VAST extension for VAST versions <= 3 or a verification node for VAST versions >= 4

Name	Signature	Returns	Official description
VerificationScriptResource	new VerificationScriptResource(resourceUrl, vendorKey, verificationParameters, accessMode)	void	Creates new verification script resource instance which requires vendor specific verification parameters. resourceUrl: string vendorKey: string verificationParameters: string accessMode: AccessModeThe level of access this verification script will have when executed.
accessMode	accessMode: AccessMode	AccessMode	(no official description provided)
resourceUrl	resourceUrl: string	string	(no official description provided)
vendorKey	vendorKey: string	(string\|undefined)	(no official description provided)
verificationParameters	verificationParameters: string	(string\|undefined)	(no official description provided)
toJSON	toJSON()	Object	(no official description provided)

docs.iabtechlab.com/omsdk-1.6/js/VerificationScriptResource.html ↗

Cross-platform naming

Concept	JavaScript	iOS	Android
ad-events	AdEvents	OMIDAdEvents	AdEvents
ad-session	AdSession	OMIDAdSession	AdSession
ad-session-configuration	—	OMIDAdSessionConfiguration	AdSessionConfiguration
ad-session-context	—	OMIDAdSessionContext	AdSessionContext
context	Context	—	—
js-session-service	—	OMIDJavaScriptSessionService	—
media-events	MediaEvents	OMIDMediaEvents	MediaEvents
omid-version	OmidVersion	—	—
partner	Partner	OMIDPartner	Partner
script-injector	—	OMIDScriptInjector	ScriptInjector
sdk-entry	—	OMIDSDK	Omid
universal-ad-id	—	OMIDUniversalAdID	—
vast-properties	—	OMIDVASTProperties	VastProperties
verification-client	VerificationClient	—	—
verification-script-resource	VerificationScriptResource	OMIDVerificationScriptResource	VerificationScriptResource

ad-session-configurationNo JS counterpart: creativeType/impressionType are set through AdSession.setCreativeType()/setImpressionType(), and the event-owner concept (impressionOwner/mediaEventsOwner) does not exist on the JS side.
ad-session-contextCorresponds to Context on JS: JS folds partner, verificationScriptResources, contentUrl, customReferenceData, universalAdId and the slot/video element into Context plus the AdSession constructor arguments, while the native side splits them into AdSessionContext (iOS additionally has AdSessionConfiguration).
contextNo class of this name on iOS/Android: the JS Context is split on the native side into AdSessionContext + AdSessionConfiguration (see the ad-session-context / ad-session-configuration entries).
js-session-servicePublished on iOS only: the JS session service built into OM SDK iOS. On Android this is handled by Omid/OmidJsBridge, with no corresponding class published on the javadoc site.
omid-versionPublished on JS only: the top of the source file omid-version.js carries TODO(OMSDK-715) noting that the class seems unused and should be removed in the next major version, yet the JSDoc site still publishes it.
script-injectorOMIDScriptInjector on iOS / ScriptInjector on Android: inject verification script content into an HTML creative. On the JS side the OM SDK service does this and publishes no class.
sdk-entryOMIDSDK on iOS (+sharedInstance / -activate) and Omid on Android (activate(Context) / isActive()); there is no JS counterpart class, as the service script is loaded by the OM SDK service itself.
universal-ad-idPublished on iOS only: the JS source has UniversalAdId (exported via packageExport onto OmidSessionClient.UniversalAdId, added in 1.5.5) but the official JSDoc site has no page for it; Android's createNativeAdSessionContext(...)/getUniversalAdId() reference the UniversalAdId type in their signatures, and the javadoc site has no such page either (verified 404).
vast-propertiesVastProperties on JS (src/common/vast-properties.js, marked @public and listed in jsdoc.json's include list) is not published on the official JSDoc site (VastProperties.html verified 404), so js is recorded as null; AdEvents.loaded(vastProperties) therefore references a type that is undocumented on the site.
verification-clientPublished on JS only: verification scripts (third-party measurement) always use the JS OmidVerificationClient; the native SDKs contain no verification client.

Class names for the same concept on each of the three platforms; a blank cell means that platform provides no corresponding class. On the JS side session configuration is folded into Context and the constructor arguments, while iOS / Android split it into separate configuration and context classes.