Secure Interactive Media Interface Definition (SIMID)

1. Version

2. Executive Summary

Secure Interactive Media Interface Definition (SIMID) is a standard for providing rich interactivity in the context of streaming audio and video ads. While the Video Ad Serving Template (VAST) standard addresses how publishers discover various metadata assets related to an ad campaign, SIMID addresses how the publisher’s video player should communicate and interface with a rich interactive layer and vice versa. As such, one can think of the SIMID creative as one of the assets listed in a VAST document.

A main tenet of SIMID is the separation of the interactive layer from the media asset. This clear separation allows publisher players to be in control of their streams and enables use cases such as server-side ad insertion (SSAI), as well as live streaming.

SIMID was built with strong security from the ground up, and is designed to be sandboxed from the media player, providing peace of mind to publishers when serving ads from third party services. SIMID aims to provide the tools and controls to allow creatives to offer rich augmented user experiences while degrading gracefully if certain features are not supported.

A diagram showing SIMID ads sandboxed from the publisher player environment

SIMID is part of a broader effort to replace the older VPAID standard (more details in this blog post by the IAB Tech Lab). While Open Measurement replaces the use case of verification and measurement, SIMID replaces the use case of interactive streaming media ads, the original intended purpose of the VPAID standard. SIMID provides a path for VPAID deprecation and allows the industry to move to more secure and transparent standards. SIMID aims to gain broad industry adoption by ensuring that the standard is focused on the primary use case of interactivity.

2.1. SIMID vs. VPAID Comparison

2.2. Intended Audience

The SIMID standard specification is geared toward the digital media advertising community. Anyone who works with products or services related to digital media advertising can benefit from reading the Introduction sections of this spec. The Messaging Protocol, API Reference, and later sections are predominantly targeted at software engineers developing products or services which leverage the technical capabilities provided by SIMID.

3. Introduction

Throughout this document, the SIMID interactive component is referred to as a “SIMID creative” or “creative”.

Compliance with SIMID requires support for all features and behaviors specificied in this document, unless a given feature or behavior is explicitly designated as optional. Standard RFC language will be used. See https://tools.ietf.org/html/rfc2119 for RFC 2119 for enforcement terminology used in this standard.

3.1. SIMID Interactive Creative Nature

A SIMID creative can be included in a VAST document by way of an <InteractiveCreativeFile> element. The text within this element must be a url which returns an HTML document. When loaded into an iframe by a media player, this HTML document will define the SIMID creative’s content, and will direct the web browser or host application to load any additional assets required by that creative (images, CSS, scripts, etc.).

The <InteractiveCreativeFile> element is defined as a child of the <MediaFiles> element in VAST 4.0. For more technical details, see the § 5 Referencing a SIMID creative from VAST section.

Example:

<MediaFiles>
<MediaFile …>https://example.com/mediafile.mp4</MediaFile>
<InteractiveCreativeFile type="text/html" apiFramework="SIMID" variableDuration="true">
   	<![CDATA[https://adserver.com/ads/creative.html]]>
</InteractiveCreativeFile>
</MediaFiles>

3.2. SIMID Ad Serving Flow

The SIMID ad experience is delivered by a web browser or application concurrently rendering an ad’s streaming audio or video file and its interactive creative file. The media player obtains urls for both files from a VAST document, loads the files, assembles them together into a single ad unit, and ensures a cohesive ad experience.

This diagram illustrates the SIMID creative loading and presentation process.

3.3. Player and Creative Communication

A media player and a SIMID creative communicate by sending serialized messages back and forth to each other.

Because a SIMID creative is an HTML document that is served from an advertiser’s web domain, and it is loaded by a media player into an iframe within a web page hosted on a different domain, loading the creative requires the creation of a cross-origin iframe (also known as an "unfriendly iframe"). Due to browser sandbox security restrictions, javascript communication across this type of iframe can only be achieved via the standard postMessage API.

SIMID API requirements govern message construction conventions as well as the message data structure. See sections § 8 Messaging Protocol, § 4 API Reference for more information.

3.4. Scope and Limitation

The use of HTML is only required for the SIMID creative, not the publisher property hosting that creative. As long as the publisher can load HTML and communicate with it over the standard postMessage API, it can support SIMID. In practice, this means that SIMID can be hosted in web page iframes, mobile app web views, and other platforms. In fact, SIMID can better support mobile use cases than VPAID because a native app or media player directly controls loading and playback of a SIMID ad unit’s media asset (whereas a VPAID ad unit offers no direct access or control of its internal media asset).

Note that certain devices, including TV sets and OTT boxes, limit loading of external assets, have limited HTML rendering capabilities or are unable to display html along with audio or video. These devices are unable to support SIMID. Devices that support HTML and Javascript can support SIMID - in both client side as well as server side ad insertion scenarios.

SIMID cannot be used to decide which media to show on the client pre-impression. This is because the media file must be present alongside the SIMID creative and delivered via the VAST MediaFile node.

SIMID should not be set up to measure viewability.

Any use of the SIMID spec to support something other than interactive or dynamic content within the ad unit is counter to the intentions of this spec.

4. API Reference

All SIMID messages are sent via the § 8 Messaging Protocol

4.1. Reference Table

4.2. Messages triggered by media element events

When the media element that renders ad media dispatches events, the player posts corresponding messages to the SIMID creative. Media element related messages include original media event type names. Message.type values are prepended with SIMID:Media namespace.

Example:

1. Media element dispatches event play.

2. Player sends message to SIMID creative with Message.type = SIMID:Media:play.

Video messages should be reported immediately after player receives related event.

Message.timestamp property value is set to the time media element dispatches event.

4.2.1. SIMID:Media:durationchange

parameters:

• duration(float): The number in seconds of the video duration. For server side ad insertion this must be calculated to be the total duration of the ad.

4.2.2. SIMID:Media:ended

4.2.3. SIMID:Media:error

parameters:

• error(DOMString): corresponds to videoElement.error.code.

• message(DOMString): corresponds to videoElement.error.message.

4.2.4. SIMID:Media:pause

4.2.5. SIMID:Media:play

4.2.6. SIMID:Media:playing

4.2.7. SIMID:Media:seeked

4.2.8. SIMID:Media:seeking

4.2.9. SIMID:Media:stalled

4.2.10. SIMID:Media:timeupdate

parameters:

• currentTime(number): corresponds to videoElement.currentTime attribute. For server side ad insertion this must be calculated to be the total time the video ad has played. For example: if the media element time is 500 seconds but the ad started playback 10 seconds ago (in DAI), currentTime should be set to 10 seconds.

4.2.11. SIMID:Media:volumechange

parameters:

• volume(number): corresponds to videoElement.volume attribute.

4.3. Messages from the player

For example:

{
 type: "SIMID:Player:adStopped",
 args: {
   code: 0
 }
}

4.3.1. SIMID:Player:adSkipped

4.3.1.1. resolve

4.3.2. SIMID:Player:adStopped

The player should wait for the resolve response before unloading the creative iframe. The player should implement a reasonable timeout to allow for creative to conclude ad end logic.

parameters:

• code(int): reason for ad stopping

The player should use the following table to determine which code to send.

• 0: Unspecified

• 1: User initiated close

• 2: Ad media playback complete

• 3: Player initiating close before media playback complete

• 4: Creative initiated close

In response to SIMID:Player:adStopped, creative finalizes the ad end logic and responds with resolve message.

4.3.2.1. resolve

4.3.3. SIMID:Player:appBackgrounding

4.3.3.1. resolve

4.3.4. SIMID:Player:appForegrounding

4.3.5. SIMID:Player:fatalError

• errorCode(int): reason for error. See § 8.4 Error Codes

• errorMessage(DOMString): Any additional information.

4.3.5.1. resolve

4.3.6. SIMID:Player:init

To assist in preloading assets the player must send the SIMID:Player:init message before SIMID:Player:startCreative. The player should send this message early enough before playback so that assets can be displayed as soon as the ad starts.

The ad, however, should not assume it is given any amount of time between the SIMID:Player:init message and the SIMID:Player:startCreative message. For example a preroll might send SIMID:Player:startCreative immediately after SIMID:Player:init.

With SIMID:Player:init, the player shall provide the following parameters:

dictionary InitParameters {
  required EnvironmentData environmentData;
  required CreativeData creativeData;
};

dictionary CreativeData {
  required DOMString adParameters;
  DOMString clickThruUrl;
};

dictionary EnvironmentData {
  required VideoDimensions videoDimensions;
  required CreativeDimensions creativeDimensions;
  required boolean fullScreen;
  required boolean fullscreenAllowed;
  required boolean variableDurationAllowed;
  required SkippableState skippableState;
  required DOMString version;
  DOMString siteUrl;
  DOMString appId;
  DOMString useragent;
  DOMString deviceId;
  boolean muted;
  float volume;
};

enum SkippableState {"playerHandles", "adHandles", "notSkippable"};

• CreativeData is used to pass information associated with the creative (sometimes taken from VAST). In a VAST context, the ad unit should pass the value for either the Linear or Nonlinear AdParameter element specified in the VAST document.

  • adParameters ad parameters from VAST, or an empty string if unknown.

  • clickThruUrl The click through url, provided from VAST. If there is no click through url, do not set this variable.

• EnvironmentData is used to pass information associated with the publisher playback environment. The object should have the following fields.

  • videoDimensions indicates the video display area, see § 4.3.8 SIMID:Player:resize

  • creativeDimensions indicates the creative display area, see § 4.3.8 SIMID:Player:resize

  • fullScreen True if fullscreen.

  • fullscreenAllowed: True if the creative may choose to display or not display a fullscreen option

  • variableDurationAllowed: If set to true the player must allow the SIMID creative to pause player-controlled video playback during the ad. If false it will not (live streaming is a use case). An example use case here is a clickthru overlay, where variableDuration (ad requirement) is false, but variableDurationAllowed (publisher capability) can be true or false. It should not be used in any case where disallowing the pause interferes with the ad KPIs (for example if it can interfere with completions, time spent in an interactive component, etc).

  • skippableState: indicates whether the ad may be skippable and which party controls the skippability, must be one of the SkippableState enum values.

    • playerHandles: The player will render a skip button and might skip the ad.

    • adHandles: The ad may or may not render a skip button.

    • notSkippable: The ad cannot be skipped and the SIMID creative should not render a skip button. This may be common in DAI for live streams.

  • version: The version of SIMID that this player uses.

  • siteUrl Indicating the website the ad will play on, for example if the site was www.xyz.com/videoId, this information would include at least www.xyz.com. The player may give more information. Desired for reporting and troubleshooting.

  • appId The id of the app if applicable

  • useragent Data about sdks and players

  • deviceId IDFA or AAID would be used primarily for 3rd party tracking of custom events

  • muted (boolean): True if the audio is muted.

  • volume (number): The volume, which should be between 0 and 1.0.

4.3.6.1. resolve

4.3.6.2. reject

• reason(DOMString): An optional string error message

• errorCode(int): The code for what went wrong in initialization. See § 8.4 Error Codes

4.3.7. SIMID:Player:log

Note: If the creative is doing something out of spec and the player will not exit with a fatal error, the player’s log message should start with "WARNING:". Creative developers should monitor for this message.

parameters:

• message(DOMString): Logging information from the player to the creative.

4.3.8. SIMID:Player:resize

parameters:

dictionary ResizeParameters {
  required VideoDimensions videoDimensions;
  required CreativeDimensions creativeDimensions;
  required boolean fullScreen;
};

dictionary VideoDimensions {
  required long x;
  required long y;
  required long width;
  required long height;
};

dictionary CreativeDimensions {
  required long x;
  required long y;
  required long width;
  required long height;
};

The VideoDimensions communicate to the creative the dimensions of the video element. The CreativeDimensions tell the creative where the iframe is located as well as its dimensions. If the iframe is not yet visible (like during initialization) these dimensions will be the expected dimensions when it does become visible.

• VideoDimensions

  • x The x offset of the video. It should initialize at 0. 0 is defined as the top left corner of the player.

  • y The y offset of the video. It should initialize at 0. 0 is defined as the top left corner of the player.

  • width The width in pixels of the video.

  • height The height in pixels of the video.

• CreativeDimensions

  • x The x offset of the creative. It should initialize at 0. 0 is defined as the top left corner of the player.

  • y The y offset of the creative. It should initialize at 0. 0 is defined as the top left corner of the player.

  • width The width in pixels of the creative.

  • height The height in pixels of the creative.

• ResizeParameters

  • fullScreen true if fullscreen.

4.3.9. SIMID:Player:startCreative

SIMID:Player:startCreative must be sent when the player is ready to make the iframe visible.

4.3.9.1. resolve

4.3.9.2. reject

• reason(DOMString): An optional string error message

• errorCode(int): The code for what went wrong in initialization. See § 8.4 Error Codes

4.4. Messages from the Creative to the Player

4.4.1. SIMID:Creative:clickThru

The creative must handle click-thru due to the nature of cross-origin iframes. This message must only be sent in response to a user-initiated click that is considered a click-thru by the creative.

The main purpose of this message is for the player to track click-thrus. Since not every navigation is a click-thru, it should not be used for adjusting media playback status (pause, mute). If the player wants to update media playback status as a result of navigation, it should detect it via some other environment-specific method (eg. Page Visibility API on web and in apps).

Parameters:

• x (int): the x coordinate of the click relative to the left of the creative.

• y (int): the y coordinate of the click relative to the top of the creative.

4.4.2. SIMID:Creative:fatalError

parameters:

• errorCode(int): reason for error. See § 8.4 Error Codes

• errorMessage(DOMString): Any optional additional information about the fatal error.

4.4.3. SIMID:Creative:getVideoState

4.4.3.1. resolve

• currentSrc(DOMString): The src of which ad has been chosen. This may need correction for server side ad insertion as it should indicate the video media selected and not the url to the media playing.

• currentTime(number): This should be the current time from the first frame of the video ad. In the case of DAI, this number needs to be corrected. For example: if the video element time is 500 seconds but the ad started playback 10 seconds ago (in DAI), this should be 10 seconds.

• duration(number): This should be the duration of the ad. Server side ad insertion may need correction.

• ended(boolean): corresponds exactly to video element ended attribute

• muted(boolean): corresponds exactly to video element muted attribute

• paused(boolean): corresponds exactly to video element paused attribute

• volume(number): corresponds exactly to video element volume attribute

• fullscreen(boolean): true if the video element is full screen, false otherwise

4.4.4. SIMID:Creative:log

Note: If the player is doing something out of spec and the creative will not exit with a fatal error, the creatives log message should start with "WARNING:". Player developers should monitor for this message.

parameters:

• message(DOMString): Logging information sent from the creative to the player.

4.4.5. SIMID:Creative:reportTracking

• trackingUrls(Array ): An array of tracking pixels that the publisher should fire.

The creative is not required to use SIMID:Creative:reportTracking. However, the player must implement SIMID:Creative:reportTracking.

All tracking urls sent through SIMID:Creative:reportTracking must have their macros replaced as though they were tracking pixels specified in VAST. Then they must be reported by the player as though they were tracking pixels.

4.4.5.1. resolve

4.4.5.2. reject

parameters:

• reason(DOMString): An optional string error message

• errorCode(int): The code for why the player did not attempt to send a tracking pixel. See § 8.4 Error Codes

4.4.6. SIMID:Creative:requestChangeAdDuration

paramaters:

• duration(int): The new duration of the creative. -2 indicates unknown ad duration.

4.4.6.1. resolve

4.4.6.2. reject

4.4.7. SIMID:Creative:requestChangeVolume

• volume(float): a number between 0 and 1 indicating what volume the creative wants.

• muted(boolean): True indicates the creative wants the volume muted.

4.4.7.1. resolve

4.4.7.2. reject

4.4.8. SIMID:Creative:requestFullScreen

4.4.8.1. resolve

4.4.8.2. reject

4.4.9. SIMID:Creative:requestExitFullScreen

4.4.9.1. resolve

4.4.9.2. reject

4.4.10. SIMID:Creative:requestPause

4.4.10.1. resolve

4.4.10.2. reject

4.4.11. SIMID:Creative:requestPlay

4.4.11.1. resolve

4.4.11.2. reject

4.4.12. SIMID:Creative:requestResize

Request resize should use the ResizeParameters which are explained in § 4.3.8 SIMID:Player:resize

4.4.12.1. resolve

4.4.12.2. reject

4.4.13. SIMID:Creative:requestSkip

If the player cannot stop video playback, the player must not unload the iframe in response to this request.

4.4.13.1. resolve

4.4.13.2. reject

4.4.14. SIMID:Creative:requestStop

If the player cannot stop video playback, the player still unloads the iframe. The creative may hide all elements in this case if it doesn’t wish to be seen.

4.4.14.1. resolve

4.4.14.2. reject

5. Referencing a SIMID creative from VAST

When a SIMID creative is referenced within a VAST document, the <InteractiveCreativeFile> element must include the following required attributes on the element: type="text/html" and apiFramework="SIMID".

The value of the apiFramework attribute identifies SIMID as the required API for the creative. Players that do not support the SIMID API may load an audio or video file included with the ad, but they will not load or play the SIMID creative.

Media players that do support the SIMID API should handle version negotiation between the creative and the media player via the § 6.1 How to Handle Ad Loading algorithm. The SIMID API version is not identified by any element or attribute in the VAST file.

A third, optional attribute which may be included on the InteractiveCreativeFile element is variableDuration="true". If present, this attribute indicates that the ad unit is only playable if the media player allows the creative to pause playback of the ad’s audio or video and extend the duration of the ad break (for example, with interactive content such as a game or survey). If the player does not support or allow this capability, then it must not render the current ad’s audio/video or SIMID creative. The player should error out the ad instead (and either resume its primary content or continue on to the next ad in the current ad pod).

6. Common Workflows

6.1. How to Handle Ad Loading

The player must follow this workflow for loading an ad.

1. The player must create an iframe element for the SIMID creative. The player iframe should start out hidden. The iframe should be capable of executing javascript and loading resources.

2. The player starts listening on the window that is the parent of the iframe for messages from the creative.

3. The player sets the src element of the iframe to the url provided by the creative’s VAST InteractiveCreativeFile element. The player should assume this will be a cross domain iframe.

4. The player waits until the creative inializes a session. § 8.2.1 Establishing a new session The player responds with a resolve message. The resolve message includes the correlator that must be present in all messages going forward.

5. The player then sends a § 4.3.6 SIMID:Player:init message with all relevant parameters. The player waits until the creative responds with resolve. If the creative responds with reject, the player should immediately unload the creative’s iframe.

6. Where possible the player should wait until both the creative has responded to the § 4.3.6 SIMID:Player:init and the video is ready to start playing. Ready to start playing means the first frame will show and playback will continue.

7. When the video is started the player sends a § 4.3.9 SIMID:Player:startCreative message. The player must overlay the creative iframe over the video element exactly. The player must make the creative visible. The creative should respond to this message immediately with § 4.3.9.1 resolve.

6.2. How to Handle Ad Playback

The video player is responsible for handling playback of the video as well as tracking video related events. The SIMID creative on the other hand handles playback of interactive content and internal tracking related to interactivity (custom events, creative impression if desired (recommended)).

6.2.1. Ad Pause

If the variableDurationAllowed flag is set to true then the player should enable video pause by the SIMID creative via the SIMID:Creative:requestPause message. The player must respond to SIMID:Creative:requestPause with the AdPaused event.

When the SIMID creative would like to resume video playback, it should send a SIMID:Creative:requestPlay message. The player must respond to SIMID:Creative:requestPlay message with resolve and play the video.

6.2.2. Ad Resizing and Fullscreen

The player may resize the ad slot. The player must send a § 4.3.8 SIMID:Player:resize message any time the ad slot size is changed.

If fullscreenAllowed is true, the SIMID creative may send a § 4.4.8 SIMID:Creative:requestFullScreen message. The player must resize only the ad slot to fullscreen (not the video). The SIMID creative then will resize the video as it sees fit. The player must send a § 4.3.8 SIMID:Player:resize message to the SIMID creative with fullScreen set to true and videoDimensions and creativeDimensions set to the full screen dimensions.

If player goes fullscreen on its own. Then the player must send a § 4.3.8 SIMID:Player:resize message to the SIMID creative with fullScreen set to true and videoDimensions and creativeDimensions set to the full screen dimensions.

6.3. How to Handle Ad End and Unload

Following are cases where ad can end:

1. Ad was skipped, either by player or creative (if the ad contains the skip button). See § 6.3.1 Ad Skips.

2. The creative has fired § 4.4.14 SIMID:Creative:requestStop message and the player has allowed the ad to stop.

3. The player has fired § 4.3.2 SIMID:Player:adStopped message and the creative resolved.

4. Ad errors out. See § 6.3.5 Ad Errors Out.

6.3.1. Ad Skips

Skip Ad Handled by Player

1. The player sends a § 4.3.1 SIMID:Player:adSkipped message to the ad.

2. The player hides the creative.

3. The creative may dispatch any tracking pixels via § 4.4.5 SIMID:Creative:reportTracking

4. The creative may wait for § 4.4.5.1 resolve from the reportTracking message.

5. The creative dispatches resolve on the adSkipped message § 4.3.1.1 resolve.

6. The player fires any skip tracking pixels.

7. The player unloads the ad.

Skip Ad Handled by Ad

1. The creative dispatches § 4.4.13 SIMID:Creative:requestSkip.

2. The player dispatches resolves the to the requestSkip message.

3. The player follows all the steps in Skip Ad Handled by Player.

6.3.2. Ad Ends Before Video Completion

This scenario applies when the ad chooses to signal the player to kill it, typically at the prompting of the viewer. A good example would be a survey that allows the viewer to skip immediately to content when completed.

1. The ad cleans up and dispatches § 4.4.14 SIMID:Creative:requestStop.

2. The player unloads the ad.

6.3.3. Ad Extends Beyond Video Completion

This scenario is only possible when the variableDurationAllowed flag is set to true. Video duration must only be extended in response to user interaction.

1. User interacts at any point during playback of the video, triggering extended ad portion.

2. The Creative dispatches § 4.4.6 SIMID:Creative:requestChangeAdDuration message with the new duration.

3. The ad enters its extended phase.

4. The creative dispatches § 4.4.14 SIMID:Creative:requestStop when extended phase is finished.

6.3.4. Ad Completes at Video Completion

When an ad finishes at the same time as its video.

1. The player sends a § 4.3.2 SIMID:Player:adStopped message to the ad.

2. The player hides the creative.

3. The creative may dispatch any tracking pixels via § 4.4.5 SIMID:Creative:reportTracking

4. The creative may wait for a § 4.4.5.1 resolve response message from the reportTracking message.

5. The creative dispatches resolve on the adSkipped message § 4.3.2.1 resolve.

6. The player unloads the ad.

6.3.5. Ad Errors Out

The SIMID creative or the player may terminate the ad unit with an error at any time. If the SIMID creative indicates an error, the player should try to stop ad unit playback. This might not be possible in server side stitched ads.

The player may error out if the ad does not respond with § 4.3.6.1 resolve in a reasonable amount of time.

When an player errors out it must follow these steps.

1. The player sends a § 4.3.5 SIMID:Player:fatalError message to the ad.

2. The player hides the creative.

3. The creative may dispatch any tracking pixels via § 4.4.5 SIMID:Creative:reportTracking

4. The creative may wait for a § 4.4.5.1 resolve response from the reportTracking message.

5. The creative dispatches resolve on the adSkipped message § 4.3.5.1 resolve.

6. The player unloads the ad.

6.3.6. User Experience

This specification does not define the user experience for a close control or other generic media interaction behavior by the ad creative or the media player. The publisher media player is in full control over its user experience and can present its controls (or hide them) as needed. The publisher media player may dismiss the ad creative at any point in time. The ad creative can also request to be dismissed at any point in time. Some implementations may have a publisher provided close control, as well as various other controls, and others may not. An ad creative may opt to show its own controls, including a close control. Both ad creatives and media players should ensure that consumers are presented with a good ad experience.

6.3.7. Additional Notes

The player may send a § 4.3.2 SIMID:Player:adStopped message at any time. The creative should respond with resolved after finishing its ad end logic. The player should allow 1 second between sending the § 4.3.2 SIMID:Player:adStopped message and receiving resolved. The implementer of the player should take into consideration that dropping a SIMID ad unit before it has dispatched resolved may result in tracking discrepancies, and that sending the § 4.3.2 SIMID:Player:adStopped message before the ad experience has ended (which is AFTER the optional lean-in phase) could harm the overall ad experience.

The SIMID creative may also dispatch § 4.4.14 SIMID:Creative:requestStop at any time, signaling to the player that the ad has finished and unloaded. Any further interaction with the SIMID creative after requestStop may not result in the desired outcome. The same is true for fatalError.

7. Error Handling and Timeouts

If the media cannot be played the player should terminate the ad and fire an error using the standard VAST errors.

If either the interactive ad or player wants to terminate with an error the player should fire a 902 error. In cases where this is not possible like live server side ad insertion the player should remove the ad overlay and continue tracking quartiles and completion.

The ad or player should pass a specific error code to indicate why it errored out. The ad can also hand back a string with extra details about the error.

8. Messaging Protocol

Messages sent using the standard postMessage API are processed asychronously. To facilitate asynchronous communication between the media player and the creative, SIMID employs a custom messaging protocol.

The protocol defines both the data structure of messages exchanged by both parties and the algorithms needed to reliably handle the exchange of these messages.

The protocol is designed to be easily implemented on top of the postMessage interface, available across the cross-domain iframe elements which are used to isolate the SIMID creative from the media player.

8.1. Transport Layer

A transport is a communication mechanism that can send serialized messages between two parties. In SIMID’s case, those are the video player and the creative.

A serialized message is a text string that one of the parties, the sender, forwards to the other party, the receiver, through the transport.

The transport must guarantee the following properties:

• It must guarantee that both parties of the channel are unambiguously defined and that only those two parties observe any serialized messages sent by either of them.

• It must guarantee that all serialized messages eventually get delivered to the other party.

• It must guarantee that the serialized messages are delivered intact, without any modifications.

• It must guarantee that all serialized messages are delivered in the order that they were sent by the sender.

The transport is not required to deliver serialized messages synchronously, but it must deliver them as soon as possible.

Note: This means that a sender can not assume that a message is delivered to the receiver unless the receiver sends a message back that acknowledges receipt. It also means that exceptions on the receiver’s side can’t be caught by the sender unless the receiver explicitly sends a message back to the sender with the exception.

8.1.1. postMessage Transport

In SIMID the media player and creative use the standard postMessage API to communicate across the cross-origin iframe boundary.

8.1.2. Message Serialization

To serialize a Message to a serialized message, apply JSON.stringify to the Message data structure. The resulting DOMString represents the serialized message.

To deserialize a serialized message to a Message data structure, apply JSON.parse to the serialized message. The resulting object has the Message data structure.

The sender should not transmit any serialized messages that cannot be correctly deserialized by the receiver.

The receiver should discard and ignore any serialized messages that it cannot correctly deserialize.

8.2. Session Layer

Multiple sessions may be active over a single transport at any given time.

A session is uniquely identified by a session identifier. All messages belonging to a session must reference the same session identifier.

8.2.1. Establishing a new session

A session is established by running the establish a new session algorithm.

8.2.2. Sending messages

To send a message through a session, run the send a message algorithm.

While most messages can be sent "fire-and-forget", some require the sender to be informed that they were properly received and handled by the receiver. The protocol uses semantics similar to the Promise API for this.

8.2.3. Receiving messages

To be able to detect new incoming sessions and receive messages from existing sessions, every party should start running the handle incoming messages algorithm as soon as possible.

8.3. Message Data Structure

A protocol message is represented by the Message data structure.

dictionary Message {
  required DOMString sessionId;
  required unsigned long messageId;
  required unsigned long timestamp;
  required DOMString type;
  any args;
};

A Message has an associated sessionId, a string that uniquely identifies the session to which the Message belongs.

A Message has an associated messageId, an integer that increments with each message sent by the sender over the session specified by sessionId.

Note: The combination of sessionId and messageId uniquely identifies a single message. The combination of the values of these two attributes may never occur twice.

A Message has timestamp property. timestamp is expressed in a number of milliseconds since January 1, 1970, 00:00:00 UTC (Epoch time). Message sender must set timestamp value as close as possible to the moment the underlying process occurs. However, the receiver should not assume that timestamp value reflects the exact instant Message triggering event chain was accomplished.

For example, if Message communicates ad video state change, media player sets timestamp value to the moment the corresponding video event arrives from HTMLVideoElement.

A Message has an associated type, a string that defines the type of message that is being sent and informs the receiver how to interpret the args parameter.

A Message may have associated args, which are type-specific additional arguments. The data structure and meaning of args is defined in the respective message type definitions.

8.3.1. resolve messages

type must be resolve

args must be a ResolveMessageArgs object:

dictionary ResolveMessageArgs {
  required unsigned long messageId;
  any value;
};

messageId refers to the messageId attribute of the message that is being resolved.

value may include a value associated with this resolve message.

8.3.2. reject messages

type must be reject

args must be a ResolveMessageArgs object.

value may include an error message associated with this reject message.

dictionary ResolveMessageArgsValue {
  unsigned long errorCode;
  DOMString message;
};

8.4. Error Codes

This table indicates defined SIMID error codes the player may fire.

9. Terminology

SIMID VAST

The VAST document that contains the SIMID ad unit components.

SIMID Ad Unit

The SIMID ad video and the SIMID ad creative.

SIMID Video

The SIMID ad video component if it’s a progressively downloaded video file.

SIMID Video Stream

The SIMID ad video component if it’s SSAI video.

SIMID Live Video Stream

The SIMID ad video component if live streaming video.

SIMID Creative

The SIMID ad creative component (html doc and assets) that overlays the SIMID ad video.

SIMID Secondary Video

Video assets that are loaded as part of the SIMID creative and not the primary video.

Content Video

Any reference to video that is NOT a component or asset of the ad unit.