SIMID 1.2.0

When the duration of the media changes due to the player receiving the media resource metadata (in HTML, HTMLMediaElement dispatches the durationchange event), the player posts a SIMID:Media:durationchange message.

dictionary MessageArgs{
required float duration
;
};

duration,

The duration of the media in seconds. In HTML, HTMLMediaElement.duration value.

1. In SSAI, HTMLMediaElement.duration value does not express the actual ad media duration. In such cases, the player must compute the ad’s actual media length.

When the media playback completes (in HTML, HTMLMediaElement dispatches an ended event), the player posts a SIMID:Media:ended message.

When playback throws an exception (in HTML, HTMLMediaElement dispatches an error event), the player posts a SIMID:Media:error message.

dictionary MessageArgs {
required unsigned short error;
required DOMString message;
};

error,

In HTML, the value of HTMLMediaElement.error.code. Codes:

1 The media download was canceled 2 Network error 3 The player failed to decode the media 4 Environment does not support media resource

message,

In HTML, the value of HTMLMediaElement.error.message.

When the media pauses (in HTML, HTMLMediaElement dispatches a pause event), the player posts a SIMID:Media:pause message.

When media playback starts as a result of autoplay or its state is no longer paused (in HTML, HTMLMediaElementdispatches a play event), the player posts a SIMID:Media:play message.

The player posts a SIMID:Media:playing message in one of the following cases:

1. the media has enough data to start playback;
2. the media recovered from stalled state;
3. playback restarts;
4. after seek operation completion.

In HTML, the player posts a Media:playing message when HTMLMediaElement dispatches a playing event.

When the user finished moving playhead into a new position (in HTML, HTMLMediaElement dispatches a seeked event), the player posts a SIMID:Media:seeked message.

When the user initiates seek operation (in HTML, HTMLMediaElement dispatches a seeking event), the player posts a SIMID:Media:seeking message.

When media data is not available for rendering (in HTML, HTMLMediaElement dispatches a stalled event), the player posts a SIMID:Media:stalled message.

The player communicates media playhead position by posting a SIMID:Media:timeupdate message. The message Media:timeupdate frequency should be not less than every 250ms.

In HTML, the player sends a Media:timeupdate message HTMLMediaElement dispatches a timeupdate event.

dictionary MessageArgs { required float currentTime;
};

currentTime,

The value in seconds. In HTML, HTMLMediaElement.currentTime property value.

In Server-Side Ad Insertion, the client-side media playback is a continuous stream which requires additional currentTime calculations. For the current ad, the player must compute the currentTime value as a delta between the actual playhead position and the time the ad started.

When the media audio state changes (in HTML, HTMLMediaElement dispatches a volumechange event), the player posts a SIMID:Media:volumechange message.

dictionary MessageArgs { required float volume; required boolean muted;
};

volume,

The number between 0 and 1.*

muted,

true if audio is muted.*

The properties volume and muted describe two independent audio states. While the media is muted, its volume may be greater than zero; while volume is zero, the media may be unmuted.

The player posts a SIMID:Player:adSkipped message immediately after the user ends ad experience. For example, by clicking on the player-owned Skip Ad button. The player must stop the media and hide the creative iframe before sending the Player:adSkipped message.

The player waits for the resolve creative response. The player may time out if the creative takes too long to respond and unload the iframe. The timeout should be reasonable to allow creative to conclude ad-end logic.

The player posts a SIMID:Player:adStopped message immediately after it terminates the ad for any reason other than a user generated skip. See § 4.3.1 SIMID:Player:adSkipped.

The player must stop media playback and hide the creative iframe before reporting Player:adStopped. The player must wait for a resolve response from the creative allotting a reasonable timeout to accommodate creative’s needs to finalize the ad-end logic.

dictionary MessageArgs {
required unsigned short code;
};

code,

Ad stop cause code. Values:

0 Unspecified 1 User-initiated close 2 Auto-close due to media playback completion 3 Player-initiated close before media playback completion 4 Creative-initiated close 5 Nonlinear duration complete.

Within mobile in-app ads, when the app moves to the background, the player posts a SIMID:Player:appBackgrounded message.

Within mobile in-app ad executions, when the app moves from the background to the foreground, the player posts a SIMID:Player:appForegrounded message.

The player may resize the ad to its default dimensions without the creative requesting a collapse. The player may collapse the ad based on its internal logic or in response to the user resuming media playback.

The player posts the § 4.3.5 SIMID:Player:collapseNonlinear message before it resizes the creative iframe.

The § 4.3.5 SIMID:Player:collapseNonlinear is an information-only message; there are no associated resolution responses.

The player posts a SIMID:Player:fatalError message when it encounters exceptions that disqualify the ad from displaying any longer. If feasible, the player stops the ad media.

Regardless of the player’s ability to terminate playback, the player should hide creative iframe and wait for resolve response before unloading iframe.

See § 6.9.5 Ad Errors Out

dictionary MessageArgs {
required unsigned short errorCode;
DOMString errorMessage;
};

errorCode

See § 9 Error Codes.

errorMessage,

Additional information

The purpose of the SIMID:player:init message is to transport data to assist with the interactive component initialization. See § 6.2 Typical Initialization WorkFlow and § 6.4 Uninterrupted Initialization WorkFlow.

The creative must respond to Player:init with either § 4.3.7.1 resolve or § 4.3.7.2 reject.

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

environmentData,

Information about publisher’s environment and media player capacities.

creativeData,

Information that pertains to the specific creative.

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

adParameters,

Typically, the value of VAST node.

clickThruUrl,

Value of VAST node.

dictionary EnvironmentData {
required Dimensions videoDimensions;
required Dimensions creativeDimensions;
required boolean fullscreen;
required boolean fullscreenAllowed;
required boolean variableDurationAllowed;
required SkippableState skippableState;
DOMString skipoffset;
required DOMString version;
DOMString siteUrl;
DOMString appId;
DOMString useragent;
DOMString deviceId;
boolean muted;
float volume;
NavigationSupport navigationSupport;
CloseButtonSupport closeButtonSupport;
float nonlinearDuration;
};
dictionary Dimensions {
required long x;
required long y;
required long width;
required long height;
};
enum SkippableState {"playerHandles", "adHandles", "notSkippable"};
enum NavigationSupport {"adHandles", "playerHandles", "notSupported"};
enum CloseButtonSupport {"adHandles", "playerHandles"};

videoDimensions,

Communicates media element coordinates and size. -1 indicates an unknown value.

creativeDimensions,

Communicates creative iframe coordinates and size the player will set when iframe becomes visible. The value of -1 indicates an unknown value, such as when responsive dimensions are dependent on the environment.

fullscreen,

The value true indicates that the player is currently in fullscreen mode. fullscreenAllowed,

Communicates the player’s capacity to toggle screen modes.

1. The value true indicates that creative may request screen mode change.
2. The value false denotes that the player will reject calls to change screen mode.*

variableDurationAllowed,

Communicates player’s capacities† to:

a. interrupt ad playback progress – the ability to pause the media;

b. extend ad user experience length beyond ad media duration after ad playback completion;

c. accommodate creative’s ad stop request.

The value true asserts that the player can:

1. pause media playback in response to creative’s requests;
2. extend ad experience after media playback completion (and abstaining from ad unloading) if the creative posts ad duration change instructions;
3. accommodate creative’s ad stop request.‡

skippableState,

Expresses:

a. player’s ability to skip the ad;†

b. VAST skippability-associated instructions logic management;

c. Skip Ad button handling delegation.

The value playerHandles indicates that all of the following applies:

1. the publisher controls skippability logic (including handling of VAST skipoffset directives);
2. either VAST contains skipoffset or the skippability is the publisher-administered behavior;
3. the player implements the Skip Ad button;
4. the player will ignore skip requests from the creative.

The value adHandles signals that the player:

1. can skip the ad;
2. does not implement internal Skip Ad button;
3. disregards VAST skippability directives;
4. will skip the ad in response to § 4.4.16 SIMID:Creative:requestSkip message.§

The value notSkippable declares that the player:

1. cannot skip the ad;
2. ignores VAST skippability instructions;
3. will disregard skip request from the creative.

With both playerHandles and notSkippable, the creative avoids the Skip Ad button drawing.

skipoffset,

Optional parameter that communicates the time the ad becomes skippable for the current session.

The skipoffset value format is "HH:MM:SS" or "HH:MM:SS.mmm".

The value can differ from the skipoffset in the VAST response when the player controls skippability. If the parameter’s skippableState value is "adHandles", the creative must display the Skip Ad button when media playback arrives at the time specified by the skipoffset parameter.

version,

The SIMID version the player implements.

muted,

true if the player § is muted.◊

volume, player’s § volume – expressed as a number between 0 and 1.0.

siteUrl,

The URI of the publisher’s site. May be full or partial URL.

appId,

The ID of the mobile app, if applicable.

useragent,

The information about SDKs as well as the player’s vendor and version. The value should comply with VAST-specified conventions.

deviceId,

IDFA or AAID

NavigationSupport,

Indicates how clickthroughs should be handled.

1. playerHandles Indicates that because of the platform, the player should handle clickthrough via § 4.4.12 SIMID:Creative:requestNavigation. Mobile platforms are often this way.
2. adHandles Indicates that the creative should open tabs or windows in response to user clicks. Web platforms are often this way.
3. notSupported The platform does not support clickthrough.

CloseButtonSupport,

Indicates what should render a close button for nonlinear ads.

1. playerHandles Indicates the player will render a close button for nonlinear ads.
2. adHandles Indicates that the creative may render a close button. If the player will not render a close button it should always use adHandles for this parameter.

nonlinearDuration,

The duration in seconds that a nonlinear ad will play for. Often, this might be the same as minSuggestedDuration from the VAST response or the duration of the content.

1. see § 4.4.10 SIMID:Creative:requestFullscreen and § 4.4.11 SIMID:Creative:requestExitFullscreen messages.

In SSAI, live broadcast, and other time-constrained environments, the player must support uninterrupted media (both content and ads) playback progress. Specifically, the player may not be able to pause the media, shorten ad, or extend user ad experience. see § 4.4.13 SIMID:Creative:requestPause, § 4.4.14 SIMID:Creative:requestPlay, § 4.4.8 SIMID:Creative:requestChangeAdDuration, and § 4.4.17 SIMID:Creative:requestStop.

SIMID does not expect device audio state information.

Values of muted and volume are independent. While the player is muted, volume can be greater than zero; the volume zero does not mean the player is muted.

The purpose of the Player:log message is to convey optional, primarily debugging, information to the creative.

Note: In SIMID prefixing log messages with “WARNING:” has a specific meaning. The player is communicating performance inefficiencies or specification deviations aimed at creative developers. For example, if the creative sends the requestChangeVolume message but does not use the correct parameters, a “WARNING:” message is appropriate.

dictionary MessageArgs {
required DOMString message;
};

message,

Logging information.

When the player changes any of ad components’ size, it posts the SIMID:Player:resize message. The message describes the media and creative sizes, independently, even if the dimensions are identical.

dictionary MessageArgs {
required Dimensions videoDimensions;
required Dimensions creativeDimensions;
required boolean fullscreen;
};
dictionary Dimensions {
required long x;
required long y;
required long width;
required long height;
};

mediaDimensions,

Media element size and coordinates.

creativeDimensions,

SIMID iframe size and coordinates.*

fullscreen,

Value is true when the ad is in fullscreen mode.

If the iframe is invisible at the time the player posts resize message, the parameter creativeDimensions communicates forthcoming values: iframe’s size, and coordinates once it is displayed.

See § 6.3 Typical Start Creative WorkFlow

The player posts SIMID:Player:startCreative message when it is ready to make the iframe visible. The player must transmit Player:startCreative as close to the first media frame rendering as possible. The player waits for a § 4.3.10.1 resolve response to display the SIMID iframe. The interactive creative should be ready to reply to Player:startCreative immediately.

§ 4.3.7 SIMID:Player:init section describes the flow that precedes the instant the player emits a Player:startCreative message.

The SIMID:Creative:clickThru message notifies the player of a clickthrough for event tracking. SIMID delegates clickthrough execution to the creative, including redirecting the user to the landing page. The interactive component posts clickThru only when the creative classifies a user interaction as a clickthrough.

The interactive component posts the Creative:clickThru message only when the creative classifies a user interaction as a clickthrough. To open the landing page in the situations when user interaction does not constitute clickthrough, the creative must utilize § 4.4.12 SIMID:Creative:requestNavigation message.

Note: Not all clickthrough metrics require the opening of a landing page. The player must assume that a clickThru message that does not provide a landing page URL is still a valid clickthrough notification, such as in the case of “deep links” or links to the app store in a device.

Deep Links

Deep links navigate the user to an app or the app store in a device. The URL for navigating to an app generally contains query parameters that can take a user to a specific view in the app and may involve a process for getting setup before a deep link will be allowed or recognized. For example in iOS, advertisers must register a SKAdNetwork ID for their deep links. SIMID can support launching a deep link, but ad developers must include the relevant details depending on environment in order for the device OS to execute the link.

The message, clickThru, is not an explicit media-pausing directive to the player. If the environment permits, the player must pause ad media in all cases when the user navigates away from the player-hosting page or app, including clickthrough. See Page Visibility API.

dictionary MessageArgs {
short x;
short y;
boolean playerHandles;
DOMString url;
};

x,

The click left offset in the creative’s coordinate system.

y,

The click top offset in the creative’s coordinate system.

playerHandles,

When true - creative requests the player to open the landing page. The creative must not require the player to open the external page if the § 4.3.7 SIMID:Player:init message argument navigationSupport value is not playerHandles.

url,

Landing page address. In the cases when the creative handles landing page redirect internally, it may not provide url value. In such scenarios, the creative sets playerHandles value to false.

*Creative:clickThru Handling*

1. User clicks on clickthrough button.
2. Creative sets playerHandles = true and posts § 4.4.1 SIMID:Creative:clickThru message.
3. Player posts § 4.4.1.1 resolve message before redirecting user to the landing page.
4. Player opens the landing page window.

When the creative is ready to collapse, it posts a Creative:collapseNonlinear message. In response to collapseNonlinear, the player resizes the ad to its original state and resumes the content media playback.

*Creative:collapseNonlinear Handling*

1. User clicks on collapse button.
2. Creative posts § 4.4.2 SIMID:Creative:collapseNonlinear message.
3. Player resizes the creative to its original (default) dimensions.
4. Player resumes media playback.
5. Player posts § 4.4.2.1 resolve message.

The creative posts Creative:expandNonlinear when a user wants to expand the ad (by clicking expand control/button that the default creative provides). Auto-expand is strongly discouraged and goes against industry guidelines.

Under normal circumstances, the player pauses the media. In cases when the content is video, the player resizes the creative iframe to the dimensions of the video and places the expanded creative at video zero coordinates.

If the player communicates to the creative that it has no capacity to expand the ad with § 4.3.7 SIMID:Player:initmessage, the creative does not provide an expand button or post the Creaitve:expandNonlinear message.

*Creative:expandNonlinear Handling*

1. User clicks on expand button.
2. Creative posts § 4.4.3 SIMID:Creative:expandNonlinear message.
3. Player pauses media.
4. Player resizes the creative to its expanded dimensions.
5. Player posts § 4.4.3.1 resolve message.

The creative posts SIMID:Creative:fatalError in cases when its internal exceptions prevent the interactive component from further execution. In response to the Creative:fatalError message, the player unloads the SIMID iframe and reports VAST error tracker with the errorCode specified by the creative. The ad media playback must stop, if possible.

dictionary MessageArgs{ required unsigned short errorCode;
DOMString errorMessage;
};

errorCode,

See § 9 Error Codes.

errorMessage,

Additional information.

The creative posts a SIMID:Creative:getMediaState message to request the current ad media states values.

The message SIMID:Creative:log enables the creative to communicate arbitrary information to the player.

Note: If the log message purpose is to notify the player about the player’s non-standard behavior, the creative prepends Message.args.message value with “WARNING:” string.

Warning messages are used to inform player developers about occurances of non-fatal issues.

dictionary MessageArgs {
required DOMString message;
};

message,

Logging information.

The SIMID:Creative:reportTracking message enables a creative to delegate arbitrary metrics reporting to the player.

The creative may inject macros into trackers URIs.

In response to the reportTracking message, the player must:

1. Send the trackers specified by the message as soon as possible.
2. Replace VAST-supported macros with the corresponding values.
3. Accept and send the trackers with custom macros – leave non-standard macros intact unless the publisher-ad integration involves custom macros processing.

dictionary MessageArgs {
required Array trackingUrls;
};

trackingUrls,

Array of URIs.

In response to user interaction, the creative is requesting a new ad duration. User interaction is required for a change ad duration request. Ad duration cannot be extended as part of an automated process in the ad, such as adding an end card. Time for the end card must be allotted within the original duration of the ad.

In SIMID, ad’s media determines the initial ad duration. The ad span may change due to user interaction. When ad duration changes, the creative posts Creative:requestChangeAdDuration message that communicates an updated value. In response to the requestChangeAdDuration message, the player adjusts ad-end timing and updates its ad progress UI (eg., countdown).

The creative expresses a known duration value in seconds. In cases where the duration is unknown (typically due to user interaction), the value is -2. With a known duration, the player unloads the ad automatically once the countdown (ad remaining time) reaches zero. See § 6.10.1 Ad Extends Beyond Media Completion 456).

When the duration value is -2, the player displays the ad indefinitely until the creative posts § 4.4.17 SIMID:Creative:requestStop. See § 6.10.3 Ad Duration Changed Workflow - Unknown Time step 4).

Note: The player communicates its capacities to modify the ad duration with § 4.3.7 SIMID:Player:initmessage args parameter variableDurationAllowed. If the value of variableDurationAllowed is false, the creative refrains from posting requestChangeAdDuration message.

dictionary MessageArgs {
required float duration;
};

duration,

Value in seconds for a known duration.

The value -2 indicates an unknown duration.

See § 6.10 Ad Duration Changed Workflow.

The creative requests ad volume change by posting a SIMID:Creative:requestChangeVolume message.

dictionary MessageArgs {
required float volume;
required boolean muted;
};

volume,

The number between 0 and 1.*

muted,

true if media audio should be muted.*

1. Properties volume and muted describe two independent audio states. While media is muted, its volume may be greater than zero; at the same time with zero volume, media may be unmuted.

The creative requests the player to transition the ad into fullscreen mode by posting a SIMID:Creative:requestFullscreen message.

Note: the player communicates its capacity to toggle screen modes with § 4.3.7 SIMID:Player:init message parameter fullscreenAllowed. When the value of fullscreenAllowed is false, the creative refrains from posting Creative:requestFullscreen message.

The creative requests the player to transition the ad into normal-screen mode by posting a SIMID:Creative:requestExitFullscreen message.

Note: the player communicates its capacity to toggle screen modes with § 4.3.7 SIMID:Player:init message parameter fullscreenAllowed. When the value of fullscreenAllowed is false, the creative refrains from posting Creative:requestExitFullscreen message.

In environments like mobile apps, the player manages redirections of the user to external landing pages. In response to § 4.4.12 SIMID:Creative:requestNavigation, the player opens a browser window with the location the creative provides with the message.args.uri parameter.

In web environments, the creative manages navigation.

The creative sends § 4.4.12 SIMID:Creative:requestNavigation in response to the user’s interaction. The creative does not request navigation without user interaction.

dictionary MessageArgs {
required string uri;
};

uri,

The address of the landing page.

*Creative:requestNavigation Handling*

1. User clicks on navigation button.
2. Creative posts requestNavigation message.
3. Player responds to § 4.4.12 SIMID:Creative:requestNavigation.
4. Player responds with § 4.4.12.2 reject message if it cannot redirect the user.
5. Player responds with § 4.4.12.1 resolve message before opening the landing page.
6. Player pauses media.
7. Player opens the landing page.

The creative requests the player to pause media playback by posting a SIMID:Creative:requestPause message.

Note: the player communicates its capacity to interrupt media playback with § 4.3.7 SIMID:Player:initmessage, parameter variableDurationAllowed. The creative must not post requestPause if the player sets variableDurationAllowed value to false.

The creative requests the player to resume media playback by posting a SIMID:Creative:requestPlay message.

Note: the player communicates its capacity to interrupt media playback with § 4.3.7 SIMID:Player:initmessage, parameter variableDurationAllowed. The creative must not post requestPlay if the player sets variableDurationAllowed value to false.

The creative requests ad resize by posting a SIMID:Creative:requestResize message.

The player must not resize the ad unless it can change the dimensions of both media element and SIMID iframe to the values specified by the Creative:requestResize message.

Note: the message requestResize must not be used to change screen mode. See the § 4.4.10 SIMID:Creative:requestFullscreen and § 4.4.11 SIMID:Creative:requestExitFullscreen messages.

dictionary MessageArgs {
required Dimensions mediaDimensions;
required Dimensions creativeDimensions;
};
dictionary Dimensions {
required long x;
required long y;
required long width;
required long height;
};

mediaDimensions,

Media element size and coordinates.

creativeDimensions,

SIMID iframe size and coordinates.

The creative requests the player skip ad playback if possible.

See § 6.9.2 Creative Skips Ad

The creative requests the player stop video playback if possible.

See § 6.9.6 Ad Requests Stop