OMID chapter navigation
AdSession & session construction
APIThe 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
AdSession is the main object of the session client: creation, start / finish, impression and creative-loaded declarations, error reporting, event registration and element bounds updates. The objects needed to construct it — Context / Partner / VerificationScriptResource / OmidVersion — are listed alongside, with the corresponding iOS / Android names. UniversalAdId and VastProperties are referenced by a Context constructor parameter and by AdEvents.loaded(); the JS source exports both (packageExport onto OmidSessionClient) but the official JSDoc site publishes no page for either, so this chapter shows them only as parameter types rather than in their own tables.
- Client
- Session client
- Platform
- JavaScript
- Library version
- 1.6.10
- Public members
- 12
API surface
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)
|
| 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.
|
| 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
|
| 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.
|
| 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.
|
| 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.
|
| 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. |
Members the official source marks as friend scoped (not to be exported beyond obfuscation) are filtered out of this table; the public path for impression and creative load is AdEvents.
Session construction
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.
|
| 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.
|
| setSlotElement | setSlotElement(slotElement) | void | Specifies the ad creative HTML element within the WebView.
|
| setVideoElement | setVideoElement(videoElement) | void | Specifies the video element within the WebView.
|
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.
|
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.
|
| 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) |
OmidVersionjs · 1
Represents the Version of OMID Session Client.
| Name | Signature | Returns | Official description |
|---|---|---|---|
| OmidVersion | new OmidVersion(semanticVersion, apiLevel) | void | (no official description provided)
|
Cross-platform naming
| Concept | JavaScript | iOS | Android |
|---|---|---|---|
| ad-session | AdSession | OMIDAdSession | AdSession |
| ad-session-configuration | — | OMIDAdSessionConfiguration | AdSessionConfiguration |
| ad-session-context | — | OMIDAdSessionContext | AdSessionContext |
| context | Context | — | — |
| omid-version | OmidVersion | — | — |
| partner | Partner | OMIDPartner | Partner |
| 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).
- 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.
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.
Common failure modes
- universal-ad-id
Published 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-properties
VastProperties 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.