SIMID 1.1.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.

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.

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.

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.

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

volume,

The number between 0 and 1.*

muted,

true if audio is muted.*

1. 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 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 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.

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.

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 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 <AdParameters> node.

clickThruUrl,

Value of VAST <ClickThrough> 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. -1 indicates an unknown value.

fullscreen,

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

fullscreenAllowed,

Communicates the player’s capacity to toggle screen modes. The value true indicates that creative may request screen mode change. The value false denotes that the player will reject calls to change screen mode.*

variableDurationAllowed,

Communicates player’s capacities† to: interrupt ad playback progress – the ability to pause the media; extend ad user experience length beyond ad media duration after ad playback completion; accommodate creative’s ad stop request. The value true asserts that the player can: pause media playback in response to creative’s requests; extend ad experience after media playback completion (and abstaining from ad unloading) if the creative posts ad duration change instructions; accommodate creative’s ad stop request.‡

skippableState,

Expresses: player’s ability to skip the ad;† VAST skippability-associated instructions logic management; Skip Ad button handling delegation. The value playerHandles indicates that all of the following applies: the publisher controls skippability logic (including handling of VAST skipoffset directives); either VAST contains skipoffset or the skippability is the publisher-administered behavior; the player implements the Skip Ad button; the player will ignore skip requests from the creative. The value adHandles signals that the player: can skip the ad; does not implement internal Skip Ad button; disregards VAST skippability directives; will skip the ad in response to § 4.4.16 SIMID:Creative:requestSkip message.§ The value notSkippable declares that the player: cannot skip the ad; ignores VAST skippability instructions; 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. 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. adHandles Indicates that the creative should open tabs or windows in response to user clicks. Web platforms are often this way. notSupported The platform does not support clickthrough.

CloseButtonSupport,

Indicates what should render a close button for nonlinear ads. playerHandles Indicates the player will render a close button for nonlinear ads. 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.
2. 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.
3. 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.
4. SIMID does not expect device audio state information.
5. 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.

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.

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.

1. 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.

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.

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:init message, the creative does not provide an expand button or post the Creative:expandNonlinear message.

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

errorCode,

See § 9 Error Codes.

errorMessage,

Additional information.

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.

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:init message 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.

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.

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.

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.

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

Note: the player communicates its capacity to interrupt media playback with § 4.3.7 SIMID:Player:init message, 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