Self-declared spec version 1.0.0 · release basis 2019-06-27 · source file simid-1.0.html
取官方 Bikeshed 渲染稿 subtitle 的 Living Standard 日期（datetime 属性）
This page reproduces the official original for that version; parameter structures come from the WebIDL blocks in the text.
The official §4.1 API / resolve / reject table; per-message parameter trees are below — click a message name to jump.
All SIMID messages are sent via the § 8 Messaging Protocol
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:
Video messages should be reported immediately after player receives related event.
Message.timestamp property value is set to the time media element dispatches event.
parameters:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| 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. |
The official spec defines no args for this message.
parameters:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| error | DOMString | corresponds to videoElement.error.code. | |
| message | DOMString | corresponds to videoElement.error.message. |
The official spec defines no args for this message.
The official spec defines no args for this message.
The official spec defines no args for this message.
The official spec defines no args for this message.
The official spec defines no args for this message.
The official spec defines no args for this message.
parameters:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| 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. |
parameters:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| volume | number | corresponds to videoElement.volume attribute. |
For example:
{
type: "SIMID:Player:adStopped",
args: {
code: 0
}
}The official spec defines no args for this message.
Response · resolve §4.3.1.1
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:
The player should use the following table to determine which code to send.
In response to SIMID:Player:adStopped, creative finalizes the ad end logic and responds with resolve message.
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| code | int | reason for ad stopping |
Response · resolve §4.3.2.1
The official spec defines no args for this message.
Response · resolve §4.3.3.1
The official spec defines no args for this message.
The official spec defines no args for this message.
Response · resolve §4.3.5.1
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"};Parameter structureWebIDL dictionary · InitParameters
| Parameter | Type | Required | Values |
|---|---|---|---|
| environmentData | EnvironmentData | ✓ | |
| videoDimensions | VideoDimensions | ✓ | |
| x | long | ✓ | |
| y | long | ✓ | |
| width | long | ✓ | |
| height | long | ✓ | |
| creativeDimensions | CreativeDimensions | ✓ | |
| x | long | ✓ | |
| y | long | ✓ | |
| width | long | ✓ | |
| height | long | ✓ | |
| fullScreen | boolean | ✓ | |
| fullscreenAllowed | boolean | ✓ | |
| variableDurationAllowed | boolean | ✓ | |
| skippableState | SkippableState | ✓ | playerHandles / adHandles / notSkippable |
| version | DOMString | ✓ | |
| siteUrl | DOMString | ||
| appId | DOMString | ||
| useragent | DOMString | ||
| deviceId | DOMString | ||
| muted | boolean | ||
| volume | float | ||
| creativeData | CreativeData | ✓ | |
| adParameters | DOMString | ✓ | |
| clickThruUrl | DOMString |
Response · resolve §4.3.6.1
Response · reject §4.3.6.2
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:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| message | DOMString | Logging information from the player to the creative. |
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.
Parameter structureWebIDL dictionary · ResizeParameters
| Parameter | Type | Required | Values |
|---|---|---|---|
| videoDimensions | VideoDimensions | ✓ | |
| x | long | ✓ | |
| y | long | ✓ | |
| width | long | ✓ | |
| height | long | ✓ | |
| creativeDimensions | CreativeDimensions | ✓ | |
| x | long | ✓ | |
| y | long | ✓ | |
| width | long | ✓ | |
| height | long | ✓ | |
| fullScreen | boolean | ✓ |
SIMID:Player:startCreative must be sent when the player is ready to make the iframe visible.
The official spec defines no args for this message.
Response · resolve §4.3.9.1
Response · reject §4.3.9.2
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:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| 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. |
parameters:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| errorCode | int | reason for error. See § 8.4 Error Codes | |
| errorMessage | DOMString | Any optional additional information about the fatal error. |
The official spec defines no args for this message.
Response · resolve §4.4.3.1
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:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| message | DOMString | Logging information sent from the creative to the player. |
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.
The official spec defines no args for this message.
Response · resolve §4.4.5.1
Response · reject §4.4.5.2
parameters:
| Parameter | Type | Required | Values |
|---|---|---|---|
| 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 |
paramaters:
Parameter structureprose parameter list (SIMID 1.0 style)
| Parameter | Type | Required | Values |
|---|---|---|---|
| duration | int | The new duration of the creative. -2 indicates unknown ad duration. |
Response · resolve §4.4.6.1
Response · reject §4.4.6.2
The official spec defines no args for this message.
Response · resolve §4.4.7.1
Response · reject §4.4.7.2
The official spec defines no args for this message.
Response · resolve §4.4.8.1
Response · reject §4.4.8.2
The official spec defines no args for this message.
Response · resolve §4.4.9.1
Response · reject §4.4.9.2
The official spec defines no args for this message.
Response · resolve §4.4.10.1
Response · reject §4.4.10.2
The official spec defines no args for this message.
Response · resolve §4.4.11.1
Response · reject §4.4.11.2
Request resize should use the ResizeParameters which are explained in § 4.3.8 SIMID:Player:resize
The official spec defines no args for this message.
Response · resolve §4.4.12.1
Response · reject §4.4.12.2
If the player cannot stop video playback, the player must not unload the iframe in response to this request.
The official spec defines no args for this message.
Response · resolve §4.4.13.1
Response · reject §4.4.13.2
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.
The official spec defines no args for this message.
Response · resolve §4.4.14.1
Response · reject §4.4.14.2
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.
| Member | Type | Required |
|---|---|---|
| sessionId | DOMString | ✓ |
| messageId | unsigned long | ✓ |
| timestamp | unsigned long | ✓ |
| type | DOMString | ✓ |
| args | any |
Data layer
8.3Message 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.
Message categories
8.3.1resolve 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.2reject 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;
};Transport layer
8.1Transport 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:
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.1postMessage Transport
In SIMID the media player and creative use the standard postMessage API to communicate across the cross-origin iframe boundary.
8.1.2Message 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.
Session layer
8.2Session 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.1Establishing a new session
A session is established by running the establish a new session algorithm.
To establish a new session, you must run the following steps:
It is recommended to use a UUID for the session identifier.
8.2.2Sending messages
To send a message through a session, run the send a message algorithm.
To send a message, you must run the following steps synchronously:
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.
To send an acknowledgement message, you must run the following steps:
8.2.3Receiving 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.
To handle an incoming message, you must run the following steps:
| Enum | Values |
|---|---|
| SkippableState | playerHandles / adHandles / notSkippable |
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.
| Code | Type | Description |
|---|---|---|
| 1100 | Unspecified error. | Catchall error if the creative could not find a matching error code. The creative should be more specific in the error message. |
| 1101 | Resources could not be loaded. | The SIMID creative tried to load resources but failed. |
| 1102 | Playback area not usable by creative. | The dimensions the creative needed were not what it received. |
| 1103 | Wrong SIMID version. | The creative could not support the players version. |
| 1104 | Creative not playable for a technical reason on this site. | |
| 1105 | Request for expand not honored. | The creative requested to expand but the player did not allow it. |
| 1106 | Request for pause not honored. | The creative requested pause but the player did not pause. |
| 1107 | Play mode not adequate for creative. | The creative requires playback control but the player is not giving control. This error should only fire if the VAST for the ad specified that it needs playback control. |
| 1108 | Ad internal error. | The creative had an error not related to any external dependencies. |
| 1109 | Device not supported. | The creative could not play or render on the device. |
| 1110 | The player is not following the spec in the way it sends messages. | |
| 1111 | The player is not responding adequately to messages. |
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).
The player must follow this workflow for loading an ad.
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)).
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.
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.
Following are cases where ad can end:
Skip Ad Handled by Player
Skip Ad Handled by Ad
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.
This scenario is only possible when the variableDurationAllowed flag is set to true. Video duration must only be extended in response to user interaction.
When an ad finishes at the same time as its video.
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.
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.
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.
Examples are reproduced from the official code blocks. Most are JS object literals with unquoted keys — paste them straight into the decoder to verify.
4.3Messages from the playerJS literal
{
type: "SIMID:Player:adStopped",
args: {
code: 0
}
}