index.bs

<pre class='metadata'>
Title: Secure Interactive Media Interface Definition (SIMID) <br><img alt="IAB Tech Lab" src="images/IABTechLabLogo.jpg" >
Shortname: SIMID
Level: 1
Status: LS
Group: IAB Tech Lab
!License: <p style="fontsize:small">The SIMID Specification from the IAB Tech Lab is licensed a Creative Commons Attribution, Non Commercial, No Derivatives License. To view a copy of this license, visit <a href="creativecommons.org/licenses/by-nc-nd/4.0/legalcode">creativecommons.org/licenses/by-nc-nd/4.0/legalcode</a> or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.</p>
!About the IAB Technology Lab: The IAB Technology Laboratory (Tech Lab) is a non-profit consortium that engages a member community globally to develop foundational technology and standards that enable growth and trust in the digital media ecosystem.. Comprised of digital publishers, ad technology firms, agencies, marketers, and other member companies, IAB Tech Lab focuses on improving the digital advertising supply chain, measurement, and consumer experiences, while promoting responsible use of data. Its work includes the OpenRTB real-time bidding protocol, ads.txt anti- fraud specification, Open Measurement SDK for viewability and verification, VAST video specification, and DigiTrust identity service. Board members include ExtremeReach, Facebook, Google, GroupM, Hearst Digital Media, Index Exchange, Integral Ad Science, LinkedIn, LiveRamp, MediaMath, Microsoft, Oracle Data Cloud, Pandora, PubMatic, Quantcast, Rakuten Marketing, Telaria, The Trade Desk, Verizon Media Group, Xandr, and Yahoo! Japan. Established in 2014, the IAB Tech Lab is headquartered in New York City with staff in San Francisco, Seattle, and London. Learn more at https://www.iabtechlab.com.
URL: https://interactiveadvertisingbureau.github.io/SIMID/
Repository: InteractiveAdvertisingBureau/SIMID
Editor: IAB Tech Lab's Digital Video Technical Working Group, video@iabtechlab.com
Abstract: Establishes a common and secure communication protocol between media (video and audio) players and executable ad units, providing rich ad experiences for viewers.
Markup Shorthands: markdown yes, idl yes, dfn yes, markup yes
</pre>

# Version # {#version-number}
1.1.0

<style>

	body {
		counter-reset: diagram;
		counter-reset: table-num;
	}

	table.alternatecolor {
		border-collapse: collapse;
		width: 100%;
	}
	
	table.alternatecolor th, td {
		border: solid #CCCCCC;
  		padding: 5px;
		vertical-align: top;
		border-width: 0 1px 0 1px;
    }

	table.alternatecolor th{
		border-color: #000;
		background-color: #000;
		color:#FFFFFF;
	}
	
	table.alternatecolor tr:nth-child(odd) td {
		background-color: #EFEFEF; 
	}
	
	table.alternatecolor tr:nth-child(even) td {
		background-color: #FFF;
	}
	
	table.alternatecolor tr:last-child td, td.last-row {
		border-bottom-width: 1px;
	}
	
	table.two-col-split td:nth-child(3n+0){
		background: #FFF !important;
		border: 0;
	}
	table.two-col-split th:nth-child(3n+0){
		background: #FFF !important;
		border: 0;
	}
	table.two-col-split td:nth-child(3n+2){
		text-align: center;
	}
	table.two-col-split th:nth-child(3n+2){
		text-align: center;
	}
	
	table.two-col-split td:nth-child(3n+2):before{
		content: "\2716";
		color: #008000;
		
	}
	
	table.alternatecolor td.empty {
		display:none;
	}
	
	td[req]:before {
		content: "\2714" !important;
		color: #D20000 !important;
	}

	p[table-header]{
		counter-increment: table-num;
		font-weight: 700;

	}

	p[table-header]:before{
		content: "Table " counter(table-num) ". ";
		font-style: italic;
	}

	ul.footnote {
		list-style-type: none;  
		font-size: 0.9em;
		margin: 0;
	}

	ul.footnote li:before{
		width: 1em !important;
		margin-left: -1em;
		display: inline-block;
	}

	ul.footnote li:nth-child(1):before {
		content:'*';
	}
	ul.footnote li:nth-child(2):before {
		content:'†';
	}
	ul.footnote li:nth-child(3):before {
		content:'‡';
	}
	ul.footnote li:nth-child(4):before {
		content:'§';
	}
	ul.footnote li:nth-child(5):before {
		content:'◊';
	}
	ul.footnote li:nth-child(6):before {
		content:'¶';
	}
	
	ul.values-list{
		margin: 0;
		list-style-type: none;
	}
	
	ul.values-list > li:nth-child(odd){
		background: #FFF;
	}
	
	ul.values-list code{
		margin: 0 1em 0 1em;
	}
	
	ul.values-list li{
		margin: 0;
	}
	
	table.messages-summary td code:before{
		content: "\2023" !important;
		margin-right: 0.5em;
	}
	
	table.messages-summary td:nth-child(1) code:before{
		content: "" !important;
		margin-right: 0;
	}

	table.messages-summary td a{
		font-family: Menlo, Consolas, "DejaVu Sans Mono", Monaco, monospace;
		font-size: 0.9em;
	}
	
	pre.idl{
		margin-bottom: 0 !important;
		border-width: 8px !important;
	}
	
	dl.idl{
		margin-top: 0 !important;
		border-width: 8px !important;
	}
	ul[collapse], ol[collapse]{
		margin: 0;
	}

	p[warning]{
		border-color: rgb(243, 87, 87);
    	background-color: rgb(245, 230, 230);
	}
	
	ul[collapse] li {
		margin-top: 0;
		line-height: 1.5em;
	}
	ol[collapse] li {
		margin-top: 0;
		line-height: 1.5em;
	}
	
	ol[alpha]{
		list-style-type: lower-alpha;
	}

	

	div[diagram]{
		counter-increment: diagram;
		position: relative;
		border: 1px solid silver;
		border-radius: 7px;
		padding: 10px;
		margin: 10px 0 10px 0;
		overflow: hidden;
	}

	div[diagram] p:first-child::before{
		content: "Diagram " counter(diagram) ". ";
		margin-left: 10px;
	}

	div[diagram] > p:first-child{
		font-weight: 600;
		font-style:italic;
		
		padding-left: 28px;
		margin: 0 0 20px 0;
		background-repeat: no-repeat;
		background-size: 1.5em;
		background-position-y: 2px;
		background-image: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+DQo8c3ZnIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgMzYgMjYiPg0KCTxwYXRoIGZpbGw9IiM1ODU5NWIiIGQ9Ik0yNCwxMGMwLDAuNTUyLTAuNDQ4LDEtMSwxSDEzYy0wLjU1MiwwLTEtMC40NDgtMS0xVjRjMC0wLjU1MiwwLjQ0OC0xLDEtMWgxMGMwLjU1MiwwLDEsMC40NDgsMSwxVjEweiIvPg0KCTxwYXRoIGZpbGw9IiM1ODU5NWIiIGQ9Ik0xMSwyMmMwLDAuNTUyLTAuNDQ4LDEtMSwxSDRjLTAuNTUyLDAtMS0wLjQ0OC0xLTF2LTRjMC0wLjU1MiwwLjQ0OC0xLDEtMWg2YzAuNTUyLDAsMSwwLjQ0OCwxLDFWMjJ6Ii8+DQoJPHBhdGggZmlsbD0iIzU4NTk1YiIgZD0iTTIyLDIyYzAsMC41NTItMC40NDgsMS0xLDFoLTZjLTAuNTUyLDAtMS0wLjQ0OC0xLTF2LTRjMC0wLjU1MiwwLjQ0OC0xLDEtMWg2YzAuNTUyLDAsMSwwLjQ0OCwxLDFWMjJ6Ii8+DQoJPHBhdGggZmlsbD0iIzU4NTk1YiIgZD0iTTMzLDIyYzAsMC41NTItMC40NDgsMS0xLDFoLTZjLTAuNTUyLDAtMS0wLjQ0OC0xLTF2LTRjMC0wLjU1MiwwLjQ0OC0xLDEtMWg2YzAuNTUyLDAsMSwwLjQ0OCwxLDFWMjJ6Ii8+DQoJPHBhdGggZmlsbD0iIzU4NTk1YiIgZD0iTTI5LDEzSDE5VjloLTJ2NEg3Yy0wLjU1MiwwLTEsMC40NDgtMSwxdjZoMnYtNWg5djRoMnYtNGg5djVoMnYtNkMzMCwxMy40NDgsMjkuNTUyLDEzLDI5LDEzeiIvPg0KCTxwYXRoIGZpbGw9IiM1ODU5NWIiIGQ9Ik0zNiwyYzAtMS4xMDQtMC44OTYtMi0yLTJIMkMwLjg5NiwwLDAsMC44OTYsMCwydjIyYzAsMS4xMDQsMC44OTYsMiwyLDJoMzJjMS4xMDQsMCwyLTAuODk2LDItMlYyeiBNMzUsMjQNCgkJYzAsMC41NTItMC40NDgsMS0xLDFIMmMtMC41NTIsMC0xLTAuNDQ4LTEtMVYyYzAtMC41NTIsMC40NDgtMSwxLTFoMzJjMC41NTIsMCwxLDAuNDQ4LDEsMVYyNHoiLz4NCjwvc3ZnPg0K');
	}

  ol[dgrm-details]{
    counter-reset: dgrm-sequence;
    list-style: none;
    border: 0px dotted silver;
    border-radius: 5px;
    padding: 10px 10px 10px 10px;
    background-size: 1.5em;
    background-position: 10px 10px;
    background-repeat: no-repeat;
    background-image-x: url('data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+DQo8c3ZnIHZlcnNpb249IjEuMSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIiB2aWV3Qm94PSIwIDAgMzYgMzYiIHhtbDpzcGFjZT0icHJlc2VydmUiPg0KPHBhdGggZmlsbD0iIzU4NTk1YiIgZD0iTTM2LDMzYzAsMS42NTctMS4zNDMsMy0zLDNIM2MtMS42NTcsMC0zLTEuMzQzLTMtM1YzYzAtMS42NTcsMS4zNDMtMywzLTNoMzBjMS42NTcsMCwzLDEuMzQzLDMsM1YzM3oiLz4NCjxjaXJjbGUgZmlsbD0iI0ZGRkZGRiIgY3g9IjE4IiBjeT0iMTgiIHI9IjE1Ii8+DQo8Y2lyY2xlIGZpbGw9IiM1ODU5NWIiIGN4PSIxOCIgY3k9IjE4IiByPSIxMSIvPg0KPHJlY3QgeD0iMTIiIHk9IjEyIiBmaWxsPSIjRkZGRkZGIiB3aWR0aD0iMyIgaGVpZ2h0PSIzIi8+DQo8cmVjdCB4PSIxNi41IiB5PSIxMiIgZmlsbD0iI0ZGRkZGRiIgd2lkdGg9IjMiIGhlaWdodD0iMyIvPg0KPHJlY3QgeD0iMjEiIHk9IjEyIiBmaWxsPSIjRkZGRkZGIiB3aWR0aD0iMyIgaGVpZ2h0PSIzIi8+DQo8cmVjdCB4PSIxMiIgeT0iMTYuNSIgZmlsbD0iI0ZGRkZGRiIgd2lkdGg9IjMiIGhlaWdodD0iMyIvPg0KPHJlY3QgeD0iMTYuNSIgeT0iMTYuNSIgZmlsbD0iI0ZGRkZGRiIgd2lkdGg9IjMiIGhlaWdodD0iMyIvPg0KPHJlY3QgeD0iMjEiIHk9IjE2LjUiIGZpbGw9IiNGRkZGRkYiIHdpZHRoPSIzIiBoZWlnaHQ9IjMiLz4NCjxyZWN0IHg9IjEyIiB5PSIyMSIgZmlsbD0iI0ZGRkZGRiIgd2lkdGg9IjMiIGhlaWdodD0iMyIvPg0KPHJlY3QgeD0iMTYuNSIgeT0iMjEiIGZpbGw9IiNGRkZGRkYiIHdpZHRoPSIzIiBoZWlnaHQ9IjMiLz4NCjxyZWN0IHg9IjIxIiB5PSIyMSIgZmlsbD0iI0ZGRkZGRiIgd2lkdGg9IjMiIGhlaWdodD0iMyIvPg0KPC9zdmc+DQo=')
  }

  ol[dgrm-details]{
    counter-reset: dgrm-sequence;
    list-style: none;
    padding-left: 40px;
    border: 0px dotted silver;
    border-radius: 5px;
    background-size: 1.5em;
    background-position: 10px 10px;
    background-repeat: no-repeat;
  }

  ol[dgrm-details] ol{
    padding-left: 40px;
  }

  ol[dgrm-details] li{
    position: relative;
  }

 ol[dgrm-details] li::before{
    position: absolute;
    --fontsize: 0.75em;
    font-size: var(--fontsize);
    background-color: #5b5b5b;
    color: #FFF;
    border-radius: 3px;
    left: -26px;
    --side: 1.6em;
    width: var(--side);
    height: var(--side);
    text-align: center;
    padding-top: 0.13em;
  }

  ol[dgrm-details-x] li::before{
    position: absolute;
    font-size: 0.75em;
    background-color: #5b5b5b;
    color: #FFF;
    padding: 4px 6px;
    border-radius: 3px;
    left: -40px;
  }

  ol[dgrm-details] > li::before{
    counter-increment: dgrm-sequence;
    content: "" counter(dgrm-sequence) "";
  }
  
  ol[dgrm-details] > li > ol{
    list-style: none;
    counter-reset: dgrm-sequence-level-2;
  }

  ol[dgrm-details] > li > ol > li::before{
	  display: block;
    width: calc(var(--side) * 1.5);
    left:-40px;
    counter-increment: dgrm-sequence-level-2;
    content: "" counter(dgrm-sequence) "." counter(dgrm-sequence-level-2) "";
  }

  ol[dgrm-details] > li > ol > li > ol{
    list-style: none;
    counter-reset: dgrm-sequence-level-3;
  }

  ol[dgrm-details] > li > ol > li > ol > li::before{
	  display: block;
    counter-increment: dgrm-sequence-level-3;
    width: calc(var(--side) * 2);
    left:-46px;
    content: "" counter(dgrm-sequence) "." counter(dgrm-sequence-level-2) "." counter(dgrm-sequence-level-3) "";
  }

	span[steps]:before{
		content:"steps ";
	}
	span[steps] b{
		font-size: 0.75em;
		margin-right: 0.5em;
		background-color: #5b5b5b;
		color: #FFF;
		padding: 2px 6px;
		border-radius: 3px;
	}

	span[step]:before{
		content:"step ";
	}
	span[step] b{
		font-size: 0.75em;
		margin-right: 0.5em;
		background-color: #5b5b5b;
		color: #FFF;
		padding: 2px 6px;
		border-radius: 3px;
	}

	[skip-ad]{
		background-color: #5b5b5b;
		color: #FFFFFF;
		border: 1px solid #5b5b5b;
		border-radius: 2px;
		outline: none;
		padding: 4px 6px;
	}

	[skip-ad]::after{
		content: "\25BA""|";
		font-weight: 700;
		letter-spacing: -3px;
		margin-left: 4px;
	}

	#xml-highlight{

	}
	.xml-highlight .hnode{
		color: #008000; 
		font-weight: bold;
	}

	.xml-highlight .hattr{
		color: #7D9029; 
	}

	.xml-highlight .hattrval{
		color: #BA2121;
	}

	.xml-highlight .hcdata{
		color: #BC7A00; 
	}

	.js-highlight {

	}

	.js-highlight .hstr{
		color: #BA2121;
	}

	.js-highlight .hnum{
		color: #008c00;
	}

	.js-highlight .hbool{
		color: #00ff00;
	}

</style>

# Executive Summary # {#exec-summary}

Secure Interactive Media Interface Definition (SIMID) is a standard for providing rich interactivity in the context of
streaming audio and video (media) 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 media 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.


<div diagram id="diagram-simid-overlay">
	<p>SIMID ads sandboxing from the publisher player environment</p>
	<img src="images/simid_diagram_1_overlay.png" alt="Normal Creative Initialization Sequence"/>
</div>

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 <a href="http://bit.ly/videoAdVision">this blog post</a> 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.

## SIMID vs. VPAID Comparison ## {#simid-vs-vpaid}

<div diagram id="diagram-simid-api-models">
	<p>VPAID vs. SIMID APIs</p>
	<img src="images/simid_diagram_2_api_models.png" alt="Normal Creative Initialization Sequence" style="margin-left: -10px;"/>
</div>

<p table-header id="simid-vs-vapid">SIMID vs. VPAID Comparison.</p>
<table class="alternatecolor">
  <tbody>
	<tr>
      <th width="20%">Feature</th>
      <th width="40%">VPAID</th>
      <th width="40%">SIMID</th>
    </tr>
   
    <tr>
      <td>Security</td>
      <td>Creative directly accesses player DOM and shared global JavaScript context.</td>
      <td>Creative is sandboxed into a cross-origin iframe. No player DOM access or shared JavaScript context.</td>
    </tr>
    <tr class="c13">
      <td>Ad media asset management</td>
      <td>Creative manages ad video loading and playback.</td>
      <td>Player manages ad media loading and playback (audio or video).</td>
    </tr>
    <tr>
      <td>Pre-caching</td>
      <td>Only the VPAID script can be reliably pre-cached. Video asset cannot be pre-cached.</td>
      <td>Audio or video asset and SIMID creative can both be pre-cached.</td>
    </tr>
    <tr>
      <td>Errors influence on performance or UX</td>
      <td>Fatal script errors from ad creative can result in significant player or publisher site performance and user experience deterioration (due to shared security sandbox).</td>
      <td>Fatal script errors from ad creative do not affect player or publisher site directly. Impact is limited to performance and user experience of the creative, only.</td>
    </tr>
    <tr>
      <td>SSAI feasibility</td>
      <td>SSAI is not possible.</td>
      <td rowspan="1">Interactive creatives can be rendered in SSAI context.</td>
    </tr>
    <tr>
      <td>Latencies</td>
      <td>Publishers are at the mercy of VPAID creative implementation efficiency and uncontrollable internal processes (verification, trading, wrapping, etc.). Each of these behaviors can impose significant latencies.</td>
      <td>Players can pre-load media and creative assets due to maintaining full control over decisioning, loading and displaying of the ad unit. Ad decisioning latency is removed, risks of internal processes are minimized due to separate security sandboxes.</td>
    </tr>
    <tr>
      <td>API</td>
      <td>Both the player and creative must support specific JavaScript functions. Each component calls functions directly on the other in a shared security sandbox (insecure).</td>
      <td>No functions are directly called on either component by the other. All communication is achieved using standard postMessage API and SIMID messaging protocol across separate security sandboxes.</td>
    </tr>
    <tr>
      <td>Ad blocking</td>
      <td>VPAID can prevent an ad from rendering.</td>
      <td>SIMID is built for interactivity and was not designed for ad blocking. The Open Measurement SDK (OMID) is expected to support this capability in the future.</td>
    </tr>
    <tr>
      <td>Verification services</td>
      <td>Verification features can be fully implemented and executed in shared DOM and global Javascript context.</td>
      <td>SIMID creative cannot access any DOM, elements, or JS context outside of its own security sandbox so is unable to handle any verification use cases. OMID handles the use case for verification allowing SIMID to be focused on interactivity only.</td>
    </tr>
    <tr>
      <td>Creative wrapping</td>
      <td>VPAID ads can load other ads (including other VPAID ads).</td>
      <td>Cannot be executed.</td>
    </tr>
    <tr>
      <td>Audio advertising</td>
      <td>Out of standard scope.</td>
      <td>Enables interactive components serving with audio ads.</td>
    </tr>
    <tr>
      <td>Environment constraints</td>
      <td>Player must be an HTML video element.</td>
      <td>Player can be native or web so long as the SIMID creative has sandboxed DOM access (such as a web view).</td>
    </tr>
    <tr>
      <td>Resource MIME type</td>
      <td>application/javascript</td>
      <td>text/html</td>
    </tr>
  </tbody>
</table>

## Intended Audience ## {#intended-audience}

The SIMID standard is geared toward the digital media advertising community. Anyone who works with digital media advertising products or services can benefit from reading the Introduction sections of this document. The Messaging Protocol, API Reference, and later sections predominantly target software engineers.

## Changes In SIMID 1.1 ## {#simid-11-changes}

SIMID version 1.1 introduces the following enhancements:
1. Support for nonlinear ads.
  * New messages [[#simid-creative-expandNonlinear]], [[#simid-creative-collapseNonlinear]], and [[#simid-player-collapseNonlinear]] and related data.
  * Additional [[#error-codes]].
  * Additional workflows for nonlinear playback.
  * New sample code for nonlinear ads.
1. Player handling user navigation to external landing pages for the in-mobile apps servings. For this purpose, SIMID:
  * New message [[#simid-creative-requestNavigation]] and related data.
  * Additional related [[#error-codes]].

# Introduction # {#intro}

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 <a href="https://tools.ietf.org/html/rfc2119">https://tools.ietf.org/html/rfc2119</a>
for RFC 2119 for enforcement terminology used in this standard.

## SIMID Interactive Creative Nature ## {#simid-interactive-creative-nature}
<div diagram id="diagram-simid-api-models">
	<p>SIMID Assets loading</p>
	<img src="images/simid_diagram_3_assets.png" alt="SIMID Interactive Creative Nature" style="margin-left: -10px;"/>
</div>

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 [[#api-vast]] section.

<!--- code syntax formatters: 
https://pygments.org/demo/#try 
https://tohtml.com/jScript/
--->

<div class="example">
<div class="xml-highlight"><pre style="line-height: 125%">
<span class="hnode">&lt;MediaFiles&gt;</span>
    <span class="hnode">&lt;MediaFile&gt;</span>
        <span class="hcdata">&lt;![CDATA[https://example.com/mediafile.mp4]]&gt;</span>
    <span class="hnode">&lt;/MediaFile&gt;</span>
    <span class="hnode">&lt;InteractiveCreativeFile</span> <span class="hattr">type=</span><span class="hattrval">"text/html"</span> <span class="hattr">apiFramework=</span><span class="hattrval">"SIMID"</span> <span class="hattr">variableDuration=</span><span class="hattrval">"true"</span><span class="hnode">&gt;</span>
        <span class="hcdata">&lt;![CDATA[https://adserver.com/ads/creative.html]]&gt;</span>
    <span class="hnode">&lt;/InteractiveCreativeFile&gt;</span>
<span class="hnode">&lt;/MediaFiles&gt;</span>
</pre></div>
</div>




## SIMID Ad Serving Flow ## {#video-ad-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 into a single ad unit, and ensures a cohesive ad experience.

<div diagram id="diagram-simid-api-models">
	<p>SIMID creative loading and presentation process.</p>
	<img src="images/simid_diagram_4_loading.png" alt="SIMID creative loading and presentation process." style="margin-left: -10px;"/>
</div>


## Player and Creative Communication ## {#player-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 [[#msg-proto]], [[#api]] for more information.

## Scope and Limitations ## {#scope}

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: Certain devices, including TV sets and OTT boxes, restrict loading of external assets, have limited HTML rendering capabilities, or are unable to display HTML along with audio or video. These devices are incapable of implementing SIMID. Devices that support HTML and JavaScript can support SIMID - on both client side as well as in 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.

## Introduction to Nonlinear Ads ## {#nonlinear-intro}

Nonlinear ads are served and displayed concurrently with the primary media content. In video players, nonlinear ads overlay a portion of the video.

Nonlinear ads implement two states: collapsed and expanded. The player renders the nonlinear ad in the original state, collapsed, while media content progresses uninterrupted. The expanded ad state typically occupies the entire player viewport and requires the media content to be paused. The expanded state of the nonlinear ad usually occurs via user interaction with the creative.
<div diagram id="diagram-nonlinear-states">
	<p>Nonlinear Ad States</p>
	 <img src="images/nonlinear-intro.png" alt="Nonlinear states."/>
</div> 

Unlike the linear ads, there is no media asset that the player needs to render with a nonlinear ad. 

SIMID supports nonlinear ads by providing a nonlinear specific API. Both linear and nonlinear ads share the same communication protocol and data providers. As with linear ads, the interactive creative is a single resource that the player loads into a cross-origin iframe. 

<div diagram id="diagram-nonlinear-user-experience">
	<p>Nonlinear Ad User Experience</p>
	 <img src="images/nonlinear-user-experience.png" alt="Nonlinear state."/>
	<ol dgrm-details>
		<li>User clicks on expand button. The player pauses content and expands the creative.
			<ol>
				<li>User clicks collapse button.
					<ol>
						<li>Player resizes the creatigve to its default state and resumes content playback.</li>
					</ol>
				</li>
				<li>User clicks close button.
					<ol>
						<li>Player unloads the creative and resumes media content.</li>
					</ol>
				</li>
			</ol>
		</li>
		<li>User clicks close button provided by the default state. Player unloads the creative.</li>
	</ol>
</div> 


### Nonlinear Ads VAST Response ### {#nonlinear-vast-response}

VAST supports nonlinear ads since version 2.0 including interactive ads that implement API frameworks. 

VAST response describes nonlinear ads in the `<NonLinear>` node children. The `<NonLinear>` node attribute’s `apiFrmawork` value is `SIMID`. The node <IFrameResource> delivers a URI to the SIMID interactive component. The node `<AdParameters>` contains custom ad data for the creative’s consumption.

<div class="example">
<div class="xml-highlight"><pre style="line-height: 125%">
<span class="hnode">&lt;Creative&gt;</span>
    <span class="hnode">&lt;NonLinear&gt;</span>
        <span class="hnode">&lt;IFrameResource</span> <span class="hattr">type=</span><span class="hattrval">"text/html"</span> <span class="hattr">apiFramework=</span><span class="hattrval">"SIMID"</span><span class="hnode">&gt;</span>
            <span class="hcdata">&lt;![CDATA[https://adserver.com/videoads/simidshell.html]&gt;</span>
        <span class="hnode">&lt;/IFrameResource&gt;</span>
        <span class="hnode">&lt;AdParameters&gt;</span>
            <span class="hcdata">&lt;![CDATA[{adid:345893,cturi:"https://mycar.com/modelS.html"}]&gt;</span>
        <span class="hnode">&lt;/AdParameters&gt;</span>
    <span class="hnode">&lt;/NonLinear&gt;</span>
<span class="hnode">&lt;/Creative&gt;</span>
</pre></div>
</div>
 


# API Reference # {#api}

SIMID API is a set of messages and data structures that ad-rendering parties exchange via [[#msg-proto]].

## Reference Table ## {#reference-table}

<table class="alternatecolor">
  <tbody>
    <tr>
      <th width="40%">API</th>
      <th width="30%">resolve</th>
      <th width="30%">reject</th>
    </tr>
    <tr>
      <td>[[#simid-media-durationchange]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-ended]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-error]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-pause]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-play]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-playing]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-seeked]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-seeking]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-stalled]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-timeupdate]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-media-volumechange]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-adSkipped]]</td>
      <td>[[#simid-player-adSkipped-resolve]]</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-adStopped]]</td>
      <td>[[#simid-player-adStopped-resolve]]</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-app-backgrounded]]</td>
      <td>[[#simid-player-app-backgrounded-resolve]]</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-app-foregrounded]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-collapseNonlinear]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-fatalError]]</td>
      <td>[[#simid-player-fatalError-resolve]]</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-init]]</td>
      <td>[[#simid-player-init-resolve]]</td>
      <td>[[#simid-player-init-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-player-log]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-resize]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-player-startCreative]]</td>
      <td>[[#simid-player-startCreative-resolve]]</td>
      <td>[[#simid-player-startCreative-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-clickThru]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-creative-collapseNonlinear]]</td>
      <td>[[#simid-creative-collapseNonlinear-resolve]]</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-creative-expandNonlinear]]</td>
      <td>[[#simid-creative-expandNonlinear-resolve]]</td>
      <td>[[#simid-creative-expandNonlinear-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-fatalError]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-creative-getMediaState]]</td>
      <td>[[#simid-creative-getMediaState-resolve]]</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-creative-log]]</td>
      <td>n/a</td>
      <td>n/a</td>
    </tr>
    <tr>
      <td>[[#simid-creative-reportTracking]]</td>
      <td>[[#simid-creative-reportTracking-resolve]]</td>
      <td>[[#simid-creative-reportTracking-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestChangeAdDuration]]</td>
      <td>[[#simid-creative-requestChangeAdDuration-resolve]]</td>
      <td>[[#simid-creative-requestChangeAdDuration-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestChangeVolume]]</td>
      <td>[[#simid-creative-requestChangeVolume-resolve]]</td>
      <td>[[#simid-creative-requestChangeVolume-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestFullscreen]]</td>
      <td>[[#simid-creative-requestFullscreen-resolve]]</td>
      <td>[[#simid-creative-requestFullscreen-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestExitFullscreen]]</td>
      <td>[[#simid-creative-requestExitFullscreen-resolve]]</td>
      <td>[[#simid-creative-requestExitFullscreen-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestPause]]</td>
      <td>[[#simid-creative-requestPause-resolve]]</td>
      <td>[[#simid-creative-requestPause-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestPlay]]</td>
      <td>[[#simid-creative-requestPlay-resolve]]</td>
      <td>[[#simid-creative-requestPlay-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestResize]]</td>
      <td>[[#simid-creative-requestResize-resolve]]</td>
      <td>[[#simid-creative-requestResize-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestSkip]]</td>
      <td>[[#simid-creative-requestSkip-resolve]]</td>
      <td>[[#simid-creative-requestSkip-reject]]</td>
    </tr>
    <tr>
      <td>[[#simid-creative-requestStop]]</td>
      <td>[[#simid-creative-requestStop-resolve]]</td>
      <td>[[#simid-creative-requestStop-reject]]</td>
    </tr>
  </tbody>
</table>

## Messages Triggered by Media Element Events ## {#media-messages}

SIMID specifies a group of messages that describe ad media states. The player prepends such messages with the `SIMID:Media namespace`.

SIMID borrows media-related semantics and naming conventions from the standard `HTMLMediaElement` behavior. In player implementations where an `HTMLMediaElement` is not used, the player must translate events and property values into the associated `SIMID:Media` message.

In HTML environments, `SIMID:Media` messages contain the original media event type.
<div class="example">
1. `HTMLMediaElement` dispatches event `play`.
1. Player sets `Message.type = SIMID:Media:play`.
</div>

The player must report `SIMID:Media` messages immediately after the associated event occurs.

The player must not queue messages in cases where the creative iframe initialization happens in the middle of the ad media playback. The player posts only messages that communicate events that occur after the iframe initialization.

`SIMID:Media` messages are information-only; they do not trigger `resolve/reject` responses from the creative.

The player may elect to report all standard HTML media events to the creative. However, the creative should not expect to receive messages with optional types. (See <a href="#table-media-events">table</a> below.)

Some `SIMID:Media` messages - `durationchange`, `error`, `timeupdate`, and `volumechange` - require additional data provided with `Message.args` parameters. 

<p table-header id="table-media-events">Required and optional media event types.</p>

<table class="alternatecolor two-col-split">
  <tbody>
    <tr>
      <th>Event Name</th>
      <th>Required</th>
      <th width="2%" style="background:#FF0000"></th>
	  <th>Event Name</th>
      <th>Required</th>
	  <th width="2%" style="background:#FF0000"></th>
	  <th>Event Name</th>
      <th>Required</th>
    </tr>
<tr><td>`abort`</td><td></td><td></td><td>`interruptend`</td><td></td><td></td><td>`seeked`</td><td req></td></tr>
<tr><td>`canplay`</td><td></td><td></td><td>`loadeddata`</td><td></td><td></td><td>`seeking`</td><td req></td></tr>
<tr><td>`canplaythrough`</td><td></td><td></td><td>`loadedmetadata`</td><td></td><td></td><td>`stalled`</td><td req></td></tr>
<tr><td>`durationchange`</td><td req></td><td></td><td>`loadstart`</td><td></td><td></td><td>`suspend`</td><td></td></tr>
<tr><td>`emptied`</td><td></td><td></td><td>`pause`</td><td req></td><td></td><td>`timeupdate`</td><td req></td></tr>
<tr><td>`encrypted`</td><td></td><td></td><td>`play`</td><td req></td><td></td><td>`volumechange`</td><td req></td></tr>
<tr><td>`ended`</td><td req></td><td></td><td>`playing`</td><td req></td><td></td><td class="last-row">`waiting`</td><td class="last-row"></td></tr>
<tr><td>`error`</td><td req></td><td></td><td>`progress`</td><td></td><td></td><td class="empty"></td><td class="empty"></td></tr>
<tr><td>`interruptbegin`</td><td></td><td></td><td>`ratechange`</td><td></td><td></td><td class="empty"></td><td class="empty"></td></tr>

  </tbody>
</table>
### SIMID:Media:durationchange ### {#simid-media-durationchange}

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.

<xmp class="idl">
dictionary MessageArgs {
	required float duration;
};
</xmp>

<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
  <dt><dfn>duration</dfn>
  <dd>The duration of the media in seconds. In HTML, HTMLMediaElement.duration value.*
</dl>
<ul class="footnote">
<li>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.</li>
</ul>
### SIMID:Media:ended ### {#simid-media-ended}
When the media playback completes (in HTML, `HTMLMediaElement` dispatches an `ended` event), the player posts a `SIMID:Media:ended` message. 

### SIMID:Media:error ### {#simid-media-error}
When playback throws an exception (in HTML, `HTMLMediaElement` dispatches an `error` event), the player posts a `SIMID:Media:error` message.

<xmp class="idl">
dictionary MessageArgs {
	required unsigned short error;
	required DOMString message;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>error</dfn>
	<dd>In HTML, the value of `HTMLMediaElement.error.code`. Codes:
	<ul class="values-list">
		<li>`1` The media download was canceled</li>
		<li>`2` Network error</li>
		<li>`3` The player failed to decode the media</li>
		<li>`4` Environment does not support media resource</li>
	</ul>
  <dt><dfn>message</dfn>
  <dd>In HTML, the value of `HTMLMediaElement.error.message`.
</dl>

### SIMID:Media:pause ### {#simid-media-pause}
When the media pauses (in HTML, `HTMLMediaElement` dispatches a `pause` event), the player posts a `SIMID:Media:pause` message.

### SIMID:Media:play ### {#simid-media-play}
When media playback starts as a result of autoplay or its state is no longer paused (in HTML, `HTMLMediaElement` dispatches a `play` event),  the player posts a `SIMID:Media:play` message.


### SIMID:Media:playing ### {#simid-media-playing}
The player posts a `SIMID:Media:playing` message in one of the following cases:
* the media has enough data to start playback;
* the media recovered from `stalled` state;
* playback restarts;
* after seek operation completion. 

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


### SIMID:Media:seeked ### {#simid-media-seeked}
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.


### SIMID:Media:seeking ### {#simid-media-seeking}
When the user initiates seek operation (in HTML, `HTMLMediaElement` dispatches a `seeking` event), the player posts a `SIMID:Media:seeking` message.


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

### SIMID:Media:timeupdate ### {#simid-media-timeupdate}
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 when` HTMLMediaElement` dispatches a `timeupdate` event.
<xmp class="idl">
dictionary MessageArgs {
	required float currentTime;
};
</xmp>

<dl dfn-type=attribute dfn-for=MessageArgs class="idl highlight def">
  <dt><dfn>currentTime</dfn>
  <dd>The value in seconds. In HTML, `HTMLMediaElement.currentTime` property value.
</dl>
<p class="note">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.</p>


### SIMID:Media:volumechange ### {#simid-media-volumechange}
When the media audio state changes (in HTML, `HTMLMediaElement` dispatches a `volumechange` event), the player posts a `SIMID:Media:volumechange` message.
<xmp class="idl">
dictionary MessageArgs {
	required float volume;
	required boolean muted;
};
</xmp>

<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
  <dt><dfn>volume</dfn>
  <dd>The number between `0` and `1`.*
  <dt><dfn>muted</dfn>
  <dd>`true` if audio is muted.*
</dl>
<ul class="footnote">
<li>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.</li>
</ul>

## Messages from the player ## {#player-messages}
SIMID specifies a group of messages that enables the player to transmit data, instructions, or state changes to the creative. The player prepends such message types with the `SIMID:Player` namespace.

`SIMID:Player` messages do not communicate ad media states; SIMID dedicates [[#media-messages]] to report media status.

While some `SIMID:Player` messages expect `resolve` and/or `reject` creative responses, other messages do not require replies.

<p table-header id="table-player-messages">`SIMID:Player` messages summary.</p>
<table class="alternatecolor messages-summary">
	<tbody>
		<tr>
			<th width="40%">Message type</th>
			<th width="30%">parameters</th>
			<th width="30%">Responses</th>
		</tr>
		<tr>
			<td>[[#simid-player-adSkipped]]</td>
			<td>n/a</td>
			<td>[[#simid-player-adSkipped-resolve]]</td>
		</tr>
		<tr>
			<td>[[#simid-player-adStopped]]</td>
			<td>`code`</td>
			<td>[[#simid-player-adStopped-resolve]]</td>
		</tr>
		<tr>
			<td>[[#simid-player-app-backgrounded]]</td>
			<td>n/a</td>
			<td>[[#simid-player-app-backgrounded-resolve]]</td>
		</tr>
		<tr>
			<td>[[#simid-player-app-foregrounded]]</td>
			<td>n/a</td>
			<td>n/a</td>
		</tr>
		<tr>
			<td>[[#simid-player-fatalError]]</td>
			<td>`errorCode`<br>`errorMessage`</td>
			<td>[[#simid-player-fatalError-resolve]]</td>
		</tr>
		<tr>
			<td>[[#simid-player-init]]</td>
			<td>`environmentData`<br>`creativeData`</td>
			<td>[[#simid-player-init-resolve]]<br>[[#simid-player-init-reject]]</td>
		</tr>
		<tr>
			<td>[[#simid-player-log]]</td>
			<td>`message`</td>
			<td>n/a</td>
		</tr>
		<tr>
			<td>[[#simid-player-resize]]</td>
			<td>`mediaDimensions`<br>`creativeDimensions`<br>`fullscreen`</td>
			<td>n/a</td>
		</tr>
		<tr>
			<td>[[#simid-player-startCreative]]</td>
			<td>n/a</td>
			<td>[[#simid-player-startCreative-resolve]]<br>[[#simid-player-startCreative-reject]]</td>
		</tr>
		
	</tbody>
</table>

### SIMID:Player:adSkipped ### {#simid-player-adSkipped}
The player posts a `SIMID:Player:adSkipped` message immediately after the user ends ad experience. For example, by clicking on the player-owned <button skip-ad>Skip Ad</button> 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.  

#### resolve #### {#simid-player-adSkipped-resolve}
The creative must respond to `Player:adSkipped` with `resolve` once its internal ad-end processes finalize. When the player receives `resolve`, it unloads the creative iframe.

### SIMID:Player:adStopped ### {#simid-player-adStopped}
The player posts a `SIMID:Player:adStopped` message immediately after it terminates the ad for any reason other than a user generated skip.  See [[#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.
<xmp class="idl">
dictionary MessageArgs {
	required unsigned short code;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>code</dfn>
	<dd>Ad stop cause code. Values:
	<ul class="values-list">
		<li>`0` Unspecified</li>
		<li>`1` User-initiated close</li>
		<li>`2` Auto-close due to media playback completion</li>
		<li>`3` Player-initiated close before media playback completion</li>
		<li>`4` Creative-initiated close</li>
    <li>`5` Nonlinear duration complete.</li>
	</ul>
</dl>

#### resolve #### {#simid-player-adStopped-resolve}
The creative must respond to `Player:adStopped` with `resolve` once its internal ad-end processes finalize. When the player receives `resolve`, it unloads the creative iframe.

### SIMID:Player:appBackgrounded ### {#simid-player-app-backgrounded}
Within mobile in-app ads, when the app moves to the background, the player posts a `SIMID:Player:appBackgrounded` message.

#### resolve #### {#simid-player-app-backgrounded-resolve}
The creative resonds to `appBackgrounded` with `resolve` message.

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

### SIMID:Player:collapseNonlinear ###  {#simid-player-collapseNonlinear}

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 [[#simid-player-collapseNonlinear]] message before it resizes the creative iframe.

The [[#simid-player-collapseNonlinear]] is an information-only message; there are no associated resolution responses.

### SIMID:Player:fatalError ### {#simid-player-fatalError}
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 [[#workflow-error]]

<xmp class="idl">
dictionary MessageArgs {
	required unsigned short errorCode;
	DOMString errorMessage;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>errorCode</dfn>
	<dd>See [[#error-codes]].
	<dt><dfn>errorMessage</dfn>
	<dd>Additional information
</dl>

#### resolve #### {#simid-player-fatalError-resolve}
The creative must respond to `Player:fatalError` with `resolve`. After `resolve` arrives, the player should remove the iframe. 

See [[#workflow-error]]

### SIMID:Player:init ### {#simid-player-init}
The purpose of the `SIMID:player:init` message is to transport data to assist with the interactive component initialization. See [[#workflow-initialization]] and [[#workflow-uninterupted-initialization]].

The creative must respond to `Player:init` with either [[#simid-player-init-resolve]] or [[#simid-player-init-reject]]. 

<xmp class="idl">
dictionary MessageArgs {
	required EnvironmentData environmentData;
	required CreativeData creativeData;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>environmentData</dfn>
	<dd>Information about publisher’s environment and media player capacities.
	<dt><dfn>creativeData</dfn>
	<dd>Information that pertains to the specific creative.
</dl>


<xmp class="idl">
dictionary CreativeData {
	required DOMString adParameters;
	DOMString clickThruUrl;
	DOMString clickThruUri;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>adParameters</dfn>
	<dd>Typically, the value of VAST `<AdParameters>` node.
	<dt><dfn>clickThruUrl</dfn>
	<dd>Value of VAST `<ClickThrough>` node. Deprecated in favor of `clickThruUri`.
	<dt><dfn>clickThruUri</dfn>
	<dd>Value of VAST `<ClickThrough>` node.
</dl>

<xmp class="idl">
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"};
</xmp>

<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>videoDimensions</dfn>
	<dd>Communicates media element coordinates and size. -1 indicates an unknown value.
	<dt><dfn>creativeDimensions</dfn>
	<dd>Communicates creative iframe coordinates and size the player will set when iframe becomes visible. -1 indicates an unknown value.
	<dt><dfn>fullscreen</dfn>
	<dd>The value `true` indicates that the player is currently in fullscreen mode.
	<dt><dfn>fullscreenAllowed</dfn>
	<dd>Communicates the player’s capacity to toggle screen modes.
	<ul collapse>
		<li>The value `true` indicates that creative may request screen mode change.</li>
		<li>The value `false` denotes that the player will reject calls to change screen mode.*</li>
	</ul>

	<dt><dfn>variableDurationAllowed</dfn>
	<dd>Communicates player’s capacities† to:
		<ol collapse alpha>
			<li>interrupt ad playback progress – the ability to pause the media;</li>
			<li>extend ad user experience length beyond ad media duration after ad playback completion;</li>
			<li>accommodate creative’s ad stop request.</li>
		</ol>
		The value `true` asserts that the player can:
		<ul collapse>
			<li>pause media playback in response to creative’s requests;</li>
			<li>extend ad experience after media playback completion (and abstaining from ad unloading) if the creative posts ad duration change instructions;</li>
			<li>accommodate creative’s ad stop request.‡</li>
		</ul>
	<dt><dfn>skippableState</dfn>
		<dd>Expresses:
			<ol collapse alpha>
				<li>player’s ability to skip the ad;†</li>
				<li>VAST skippability-associated instructions logic management;</li>
				<li><button skip-ad>Skip Ad</button> button handling delegation.</li>
			</ol>
			The value `playerHandles` indicates that all of the following applies:
			<ul collapse>
				<li>the publisher controls skippability logic (including handling of VAST `skipoffset` directives);</li>
				<li>either VAST contains `skipoffset` or the skippability is the publisher-administered behavior;</li>
				<li>the player implements the <button skip-ad>Skip Ad</button> button;</li>
				<li>the player will ignore skip requests from the creative.</li>
			</ul>
			The value `adHandles` signals that the player:
			<ul collapse>
				<li>can skip the ad;</li>
				<li>does not implement internal <button skip-ad>Skip Ad</button> button;</li>
				<li>disregards VAST skippability directives;</li>
				<li>will skip the ad in response to [[#simid-creative-requestSkip]] message.§</li>
			</ul>
			The value `notSkippable` declares that the player:
			<ul collapse>
				<li>cannot skip the ad;</li>
				<li>ignores VAST skippability instructions;</li>
				<li>will disregard skip request from the creative.</li>
			</ul>
			With both `playerHandles` and `notSkippable`, the creative avoids the <button skip-ad>Skip Ad</button> button drawing.
	<dt><dfn>skipoffset</dfn>
	<dd>Optional parameter that communicates the time the ad becomes skippable for the current session. 
	<p>The `skipoffset` value format is `"HH:MM:SS"` or `"HH:MM:SS.mmm"`.</p>
	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 <button skip-ad>Skip Ad</button> button when media playback arrives at the time specified by the `skipoffset` parameter.
	<dt><dfn>version</dfn>
	<dd>The SIMID version the player implements.
	<dt><dfn>muted</dfn>
	<dd>`true` if the player § is muted.◊
	<dt><dfn>volume</dfn>
	<dd>player’s § volume – expressed as a number between `0` and `1.0`.
	<dt><dfn>siteUrl</dfn>
	<dd>The URI of the publisher’s site. May be full or partial URL.
	<dt><dfn>appId</dfn>
	<dd>The ID of the mobile app, if applicable.
	<dt><dfn>useragent</dfn>
	<dd>The information about SDKs as well as the player’s vendor and version. The value should comply with VAST-specified conventions.
	<dt><dfn>deviceId</dfn>
	<dd>IDFA or AAID
  <dt><dfn>NavigationSupport</dfn>
  <dd> Indicates how clickthroughs should be handled.
      <ul collapse>
        <li><b>playerHandles</b> Indicates that because of the platform, the player should handle clickthrough via [[#simid-creative-requestNavigation]]. Mobile platforms are often this way.</li>
        <li><b>adHandles</b> Indicates that the creative should open tabs or windows in response to user clicks. Web platforms are often this way.</li>
        <li><b>notSupported</b> The platform does not support clickthrough.</li>
      </ul>
  <dt><dfn>CloseButtonSupport</dfn>
  <dd> Indicates what should render a close button for nonlinear ads.
      <ul collapse>
        <li><b>playerHandles</b> Indicates the player will render a close button for nonlinear ads.</li>
        <li><b>adHandles</b> 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.</li>
      </ul>
  <dt><dfn>nonlinearDuration</dfn>
  <dd>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.
	
</dl>

<ul class="footnote">
	<li>see [[#simid-creative-requestFullscreen]] and [[#simid-creative-requestExitFullscreen]] messages.</li>
	<li>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.</li>
	<li>see [[#simid-creative-requestPause]], [[#simid-creative-requestPlay]], [[#simid-creative-requestChangeAdDuration]], and [[#simid-creative-requestStop]].</li>
	<li>SIMID does not expect device audio state information.</li>
	<li>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.</li>
</ul>

#### resolve #### {#simid-player-init-resolve}

The creative acknowledges the initialization parameters.

If the creative delays calling resolve, see [[#workflow-delayed-init-resolve]].

#### reject #### {#simid-player-init-reject}

The creative may respond with a reject based on its internal logic.


<xmp class="idl">
dictionary MessageArgs {
	required unsigned short errorCode;
	DOMString reason;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>errorCode</dfn>
	<dd>See [[#error-codes]].
	<dt><dfn>reason</dfn>
	<dd>Optional information about rejection cause.
</dl>

The player then will follow the rejection workflow. See [[#workflow-reject-initialization]].

### SIMID:Player:log ### {#simid-player-log}
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.

<xmp class="idl">
dictionary MessageArgs {
	required DOMString message;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>message</dfn>
	<dd>Logging information.
</dl>

### SIMID:Player:resize ### {#simid-player-resize}
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.

<xmp class="idl">
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;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>mediaDimensions</dfn>
	<dd>Media element size and coordinates.
	<dt><dfn>creativeDimensions</dfn>
	<dd>SIMID iframe size and coordinates.*
	<dt><dfn>fullscreen</dfn>
	<dd>Value is `true` when the ad is in fullscreen mode.
</dl>
<ul class="footnote">
	<li>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.</li>
</ul>

### SIMID:Player:startCreative ### {#simid-player-startCreative}

See [[#workflow-startCreative]]

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 [[#simid-player-startCreative-resolve]] response to display the SIMID iframe. The interactive creative should be ready to reply to `Player:startCreative` immediately.

[[#simid-player-init]] section describes the flow that precedes the instant the player emits a `Player:startCreative` message.  

#### resolve #### {#simid-player-startCreative-resolve}
By posting `resolve`, the interactive creative acknowledges that it is ready for display. The creative should be ready to respond immediately. The player makes the iframe visible upon a resolve receipt

Refer to [[#workflow-startCreative]] <span step><b>2</b></span>.

If the creative fails to reply with a `resolve` by the time ad media playback completes, the player reports VAST error tracker with the errorCode 1213. See [[#error-codes]].

#### reject #### {#simid-player-startCreative-reject}
When the creative responds with a reject, the player may unload the iframe. The player reports VAST error tracker with the `errorCode` the creative supplied.

<xmp class="idl">
dictionary MessageArgs {
	required unsigned short errorCode;
	DOMString reason;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>errorCode</dfn>
	<dd>See [[#error-codes]].
	<dt><dfn>reason</dfn>
	<dd>Additional information.
	
</dl>

## Messages from the Creative to the Player ## {#creative-messages}
The creative posts messages to the player to requests the ad’s state changes, obtain data, and to send notifications. The creative prefixes its messages with the namespace `SIMID:Creative`.

`SIMID:Creative` messages may require the player to accept and process arguments. With some messages, the creative expects the player to respond with resolutions.

Note: In SIMID, the creative initializes the session and posts the first message, `createSession`. See [[#protocol-session-layer]].

<p table-header id="table-creative-messages">`SIMID:Creative` messages summary.</p>

<table class="alternatecolor messages-summary">
	<tbody>
		<tr>
			<th width="50%">Message type</th>
			<th width="25%">`ars` parameters</th>
			<th width="25%">Responses</th>
		</tr>
		<tr>
			<td>[[#simid-creative-clickThru]]</td>
			<td>`x`<br>`y`</td>
			<td>n/a</td>
		</tr>
		<tr>
			<td>[[#simid-creative-fatalError]]</td>
			<td>`errorCode`<br>`errorMessage`</td>
			<td>n/a</td>
		</tr>
		<tr>
			<td>[[#simid-creative-getMediaState]]</td>
			<td>n/a</td>
			<td>[[#simid-creative-getMediaState-resolve]]</td>
		</tr>
		<tr>
			<td>[[#simid-creative-log]]</td>
			<td>`message`</td>
			<td>n/a</td>
		</tr>
			<td>[[#simid-creative-reportTracking]]</td>
			<td>`trackingUrls`</td>
			<td>[[#simid-creative-reportTracking-resolve]]<br>[[#simid-creative-reportTracking-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestChangeAdDuration]]</td>
			<td>`duration`</td>
			<td>[[#simid-creative-requestChangeAdDuration-resolve]]<br>[[#simid-creative-requestChangeAdDuration-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestChangeVolume]]</td>
			<td>`volume`<br>`muted`</td>
			<td>[[#simid-creative-requestChangeVolume-resolve]]<br>[[#simid-creative-requestChangeVolume-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestExitFullscreen]]</td>
			<td>n/a</td>
			<td>[[#simid-creative-requestExitFullscreen-resolve]]<br>[[#simid-creative-requestExitFullscreen-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestFullscreen]]</td>
			<td>n/a</td>
			<td>[[#simid-creative-requestFullscreen-resolve]]<br>[[#simid-creative-requestFullscreen-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestPause]]</td>
			<td>n/a</td>
			<td>[[#simid-creative-requestPause-resolve]]<br>[[#simid-creative-requestPause-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestPlay]]</td>
			<td>n/a</td>
			<td>[[#simid-creative-requestPlay-resolve]]<br>[[#simid-creative-requestPlay-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestResize]]</td>
			<td>n/a</td>
			<td>[[#simid-creative-requestResize-resolve]]<br>[[#simid-creative-requestResize-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestSkip]]</td>
			<td>n/a</td>
			<td>[[#simid-creative-requestSkip-resolve]]<br>[[#simid-creative-requestSkip-reject]]</td>
		</tr>
		</tr>
			<td>[[#simid-creative-requestStop]]</td>
			<td>n/a</td>
			<td>[[#simid-creative-requestStop-resolve]]<br>[[#simid-creative-requestStop-reject]]</td>
		</tr>
		
	</tbody>
</table>


### SIMID:Creative:clickThru ### {#simid-creative-clickThru}

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 [[#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](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API).

<xmp class="idl">
dictionary MessageArgs {
	short x;
	short y;
	boolean playerHandles;
	DOMString url;
	DOMString uri;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>x</dfn>
	<dd>The click left offset in the creative’s coordinate system.
	<dt><dfn>y</dfn>
	<dd>The click top offset in the creative’s coordinate system.
	<dt><dfn>playerHandles</dfn>
	<dd>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 [[#simid-player-init]] message argument `navigationSupport` value is not `playerHandles`.
	<dt><dfn>url</dfn>
	<dd>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`. Deprecated in favor of `uri`.
	<dt><dfn>uri</dfn>
	<dd>Landing page address. In the cases when the creative handles landing page redirect internally, it may not provide `uri` value. In such scenarios, the creative sets `playerHandles` value to `false`.
</dl>

<div diagram id="diagram-creative-clickThru">
	<p>Creative:clickThru Handling</p>
	 <img src="images/dgrm-Creative-clickThru.png" alt="Creative clickThru flow."/>
	<ol dgrm-details>
		<li>User clicks on clickthrough button.</li>
		<li>Creative sets `playerHandles = true` and posts [[#simid-creative-clickThru]] message.</li>
		<li>Player posts [[#simid-creative-clickThru-resolve]] message before redirecting user to the landing page.</li>
		<li>Player opens the landing page window.</li>
	</ol>
</div> 



#### resolve #### {#simid-creative-clickThru-resolve}
In the scenarios when the player handles landing page redirects, it responds with `resolve` before the landing page opens.

#### reject #### {#simid-creative-clickThru-reject}
The player posts `reject` if the creative requested the player to handle navigation when the player does not implement user redirects, creative fails to provide URI, or the URI is invalid. The player provides the `errorCode` 1214.

<xmp class="idl">
dictionary MessageArgs {
	required short errorCode;
	DOMString reason;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>errorCode</dfn>
	<dd>1214.
	<dt><dfn>reason</dfn>
	<dd>Additional information. For example: "Invalid URI".
	
</dl>


### SIMID:Creative:collapseNonlinear ### {#simid-creative-collapseNonlinear}
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.

<div diagram id="diagram-creative-collapseNonlinear">
	<p>Creative:collapseNonlinear Handling</p>
	 <img src="images/dgrm-Creative-collapseNonlinear.png" alt="Creative collapseNonlinear flow."/>
	<ol dgrm-details>
		<li>User clicks on collapse button.</li>
		<li>Creative posts [[#simid-creative-collapseNonlinear]] message.</li>
		<li>Player resizes the creative to its original (default) dimensions.</li>
		<li>Player resumes media playback.</li>
		<li>Player posts [[#simid-creative-collapseNonlinear-resolve]] message.</li>
	</ol>
</div> 


#### resolve #### {#simid-creative-collapseNonlinear-resolve}
When the player resizes the ad, it posts a resolve message.

### SIMID:Creative:expandNonlinear ### {#simid-creative-expandNonlinear}

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 [[#simid-player-init]] message, the creative does not provide an expand button or post the `Creaitve:expandNonlinear` message.

<div diagram id="diagram-creative-expandNonlinear">
	<p>Creative:expandNonlinear Handling</p>
	 <img src="images/dgrm-Creative-expandNonlinear.png" alt="Creative expandNonlinear flow."/>
	<ol dgrm-details>
		<li>User clicks on expand button.</li>
		<li>Creative posts [[#simid-creative-expandNonlinear]] message.</li>
		<li>Player pauses media.</li>
		<li>Player resizes the creative to its expanded dimensions.</li>
		<li>Player posts [[#simid-creative-expandNonlinear-resolve]] message.</li>
	</ol>
</div> 

#### resolve #### {#simid-creative-expandNonlinear-resolve}
Once the player resizes the ad, it posts a `resolve` message. The player provides the expanded size dimensions and position with the resolve message.args

<xmp class="idl">
dictionary MessageArgs {
	required Dimensions creativeDimensions;
};

dictionary Dimensions {
	required long x;
	required long y;
	required long width;
	required long height;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>creativeDimensions</dfn>
	<dd>SIMID iframe size and coordinates.
</dl>

#### reject #### {#simid-creative-expandNonlinear-reject}
If the player declines the expansion request, it posts a `reject` message.

### SIMID:Creative:fatalError ### {#simid-creative-fatalError}
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.

<xmp class="idl">
dictionary MessageArgs {
	required unsigned short errorCode;
	DOMString errorMessage;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>errorCode</dfn>
	<dd>See [[#error-codes]].
	<dt><dfn>errorMessage</dfn>
	<dd>Additional information.
	
</dl>

### SIMID:Creative:getMediaState ### {#simid-creative-getMediaState}
The creative posts a `SIMID:Creative:getMediaState` message to request the current ad media states values.


#### resolve #### {#simid-creative-getMediaState-resolve}
The player should always respond  to `Creative:getMediaState` with a `resolve`, including situations when the player is unable to provide all expected values. 

<xmp class="idl">
dictionary MessageArgs {
	DOMString currentSrc;
	float currentTime;
	float duration;
	boolean ended;
	boolean muted;
	boolean paused;
	float volume;
	boolean fullscreen;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>currentSrc</dfn>
	<dd>The URI to the media publisher chooses for the playback. This value is optional and may not be provided in the case of server side ad insertion.
	<dt><dfn>currentTime</dfn>
	<dd>The time elapsed since the first ad media frame.
	<dt><dfn>duration</dfn>
	<dd>Ad media duration.
	<dt><dfn>ended</dfn>
	<dd>In HTML, the value of `HTMLMediaElement.ended` attribute. 
	<dt><dfn>muted</dfn>
	<dd>In HTML, the value of `HTMLMediaElement.muted` attribute. 
	<dt><dfn>paused</dfn>
	<dd>In HTML, the value of `HTMLMediaElement.paused` attribute. 
	<dt><dfn>volume</dfn>
	<dd>In HTML, the value of `HTMLMediaElement.volume` attribute. 
	<dt><dfn>fullscreen</dfn>
	<dd>he value is `true` if the media element is in full screen.. 
	
	
</dl>

### SIMID:Creative:log ### {#simid-creative-log}
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.

<xmp class="idl">
dictionary MessageArgs {
	required DOMString message;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>message</dfn>
	<dd>Logging information.
</dl>

### SIMID:Creative:reportTracking ### {#simid-creative-reportTracking}

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:
	<ul collapse>
		<li>Send the trackers specified by the message as soon as possible.</li>
		<li>Replace VAST-supported macros with the corresponding values.</li>
		<li>Accept and send the trackers with custom macros – leave non-standard macros intact unless the publisher-ad integration involves custom macros processing.</li>
	</ul>
 
<xmp class="idl">
dictionary MessageArgs {
	required Array trackingUrls;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>trackingUrls</dfn>
	<dd>`Array` of URIs.
</dl>

#### resolve #### {#simid-creative-reportTracking-resolve}
The player posts a `resolve` after it sends the trackers. 

#### reject #### {#simid-creative-reportTracking-reject}
The player posts a `reject` if it did not send the trackers.

<xmp class="idl">
dictionary MessageArgs {
	required unsigned short errorCode;
	DOMString reason;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>errorCode</dfn>
	<dd>See [[#error-codes]].
	<dt><dfn>reason</dfn>
	<dd>Additional information.
</dl>

### SIMID:Creative:requestChangeAdDuration ### {#simid-creative-requestChangeAdDuration}

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 [[#workflow-extend]] <span steps><b>4</b><b>5</b><b>6</b></span>).

When the duration value is `-2`, the player displays the ad indefinitely until the creative posts [[#simid-creative-requestStop]]. See [[#workflow-ad-duartion-changed-unknown]] step <span step><b>4</b></span>). 

Note: The player communicates its capacities to modify the ad duration with  [[#simid-player-init]] message args parameter `variableDurationAllowed`. If the value of `variableDurationAllowed` is `false`, the creative refrains from posting `requestChangeAdDuration` message.

<xmp class="idl">
dictionary MessageArgs {
	required float duration;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>duration</dfn>
	<dd>Value in seconds for a known duration.<br>
	The value `-2` indicates an unknown duration. 
</dl>

See [[#workflow-change-duration]].

#### resolve #### {#simid-creative-requestChangeAdDuration-resolve}
By posting `resolve` response to `requestChangeAdDuration` message, the player signals that it will respect requested duration by modifying the ad duration-dependent behaviors.

Note: The player must accommodate an ad duration change directive if the value of the [[#simid-player-init]] message parameter `variableDurationAllowed` is `true`. 


#### reject #### {#simid-creative-requestChangeAdDuration-reject}
By posting `reject` response to `requestChangeAdDuration` message, the player states that:
	<ul collapse>
		<li>It ignored the duration change request;</li>
		<li>Ad media playback continues uninterrupted;</li>
		<li>The player will stop and unload the ad once any of the prescribed player-side ad-end triggers arise.</li>
	</ul>

Note: The single SIMID-supported reason for a `reject` in response to `requestChangeAdDuration` is the player’s inability to alter media progress. 


### SIMID:Creative:requestChangeVolume ### {#simid-creative-requestChangeVolume}
The creative requests ad volume change by posting a `SIMID:Creative:requestChangeVolume` message.

<xmp class="idl">
dictionary MessageArgs {
	required float volume;
	required boolean muted;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>volume</dfn>
	<dd>The number between `0` and `1`.*
	<dt><dfn>muted</dfn>
	<dd>`true` if media audio should be muted.* 
</dl>
<ul class="footnote">
<li>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.
</li>
</ul>

#### resolve #### {#simid-creative-requestChangeVolume-resolve}
By posting `resolve` message, the player signals it has changed the media audio states to the requested values.
#### reject #### {#simid-creative-requestChangeVolume-reject}
By posting `reject` message, the player signals that it did not change the audio state.

### SIMID:Creative:requestFullscreen ### {#simid-creative-requestFullscreen}
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 [[#simid-player-init]] message parameter `fullscreenAllowed`. When the value of `fullscreenAllowed` is `false`, the creative refrains from posting `Creative:requestFullscreen` message.

#### resolve #### {#simid-creative-requestFullscreen-resolve}
By posting `resolve` response to `requestFullscreen` message, the player signals that it moved both the media element and the SIMID iframe into fullscreen mode.

#### reject #### {#simid-creative-requestFullscreen-reject}
By posting `reject` response to `requestFullscreen` message, the player signals that it did not change the screen mode because it is either:
	<ul collapse>
		<li>Incapable of toggling between screen modes.</li>
		<li>Already in the fullscreen mode.</li>
		<li>Disallows fullscreen mode.</li>
	</ul>

### SIMID:Creative:requestExitFullscreen ### {#simid-creative-requestExitFullscreen}
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 [[#simid-player-init]] message parameter `fullscreenAllowed`. When the value of `fullscreenAllowed` is false, the creative refrains from posting `Creative:requestExitFullscreen` message.

#### resolve #### {#simid-creative-requestExitFullscreen-resolve}
By posting `resolve` response to `requestExitFullscreen` message, the player signals that it moved both the media element and the SIMID iframe into normal-screen mode.

#### reject #### {#simid-creative-requestExitFullscreen-reject}
The player responds to `requestExitFullscreen` message with a `reject` when it did not change the screen mode because it is either:
	<ul collapse>
		<li>Incapable of toggling between screen modes or</li>
		<li>Already in the normal-screen mode.</li>
	</ul>

### SIMID:Creative:requestNavigation ### {#simid-creative-requestNavigation}

In environments like mobile apps, the player manages redirections of the user to external landing pages. In response to [[#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 [[#simid-creative-requestNavigation]] in response to the user’s interaction. The creative does not request navigation without user interaction.

<xmp class="idl">
dictionary MessageArgs {
  required DOMString uri;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
  <dt><dfn>uri</dfn>
  <dd>The address of the landing page.
</dl>

<div diagram id="diagram-creative-requestNavigation">
	<p>Creative:requestNavigation Handling</p>
	<img src="images/dgrm-Creative-requestNavigation.png" alt="SIMID Request Navigation.">
	<ol dgrm-details>
		<li>User clicks on navigation button.</li>
		<li>Creative posts `requestNavigation` message.</li>
		<li>Player responds to [[#simid-creative-requestNavigation]].
			<ol>
				<li>Player responds with [[#simid-creative-requestNavigation-reject]] message if it cannot redirect the user.</li>
				<li>Player responds with [[#simid-creative-requestNavigation-resolve]] message before opening the landing page.</li>
				<ol>
					<li>Player pauses media.</li>
					<li>Player opens the landing page.</li>
				</ol>
			</ol>
		</li>
	</ol>
</div> 

#### resolve #### {#simid-creative-requestNavigation-resolve}

The player posts resolve before it opens the window to assure the creative receives the message prior to app backgrounding. 

#### reject #### {#simid-creative-requestNavigation-reject}

The player did not navigate to a new window.

### SIMID:Creative:requestPause ### {#simid-creative-requestPause}
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 [[#simid-player-init]] message, parameter `variableDurationAllowed`. The creative must not post `requestPause` if the player sets `variableDurationAllowed` value to `false`. 

#### resolve #### {#simid-creative-requestPause-resolve}
The player replies to `Creative:requestPause` with a `resolve` if it paused the media.
#### reject #### {#simid-creative-requestPause-reject}
The player replies to `Creative:requestPause` with a `reject` if it did not pause the media or the playback is already paused.

### SIMID:Creative:requestPlay ### {#simid-creative-requestPlay}
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 [[#simid-player-init]] message, parameter `variableDurationAllowed`. The creative must not post `requestPlay` if the player sets `variableDurationAllowed` value to `false`.


#### resolve #### {#simid-creative-requestPlay-resolve}
The player replies to `Creative:requestPlay` with a `resolve` if it resumed media playback.

#### reject #### {#simid-creative-requestPlay-reject}
The player replies to `Creative:requestPlay` with a `reject` if it did not resume the media or the playback is already in progress.

### SIMID:Creative:requestResize ### {#simid-creative-requestResize}

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 [[#simid-creative-requestFullscreen]] and [[#simid-creative-requestExitFullscreen]] messages.

<xmp class="idl">
dictionary MessageArgs {
	required Dimensions mediaDimensions;
	required Dimensions creativeDimensions;
};
dictionary Dimensions {
	required long x;
	required long y;
	required long width;
	required long height;
};

</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>mediaDimensions</dfn>
	<dd>Media element size and coordinates.
	<dt><dfn>creativeDimensions</dfn>
	<dd>SIMID iframe size and coordinates.
</dl>

#### resolve #### {#simid-creative-requestResize-resolve}
The player replies to `requestResize` with a `resolve` if it has resized the ad and set the dimensions to the values specified by the `requestResize` message.

#### reject #### {#simid-creative-requestResize-reject}
The player responds to `requestResize` with `reject` when it ignores the message or is unable to complete the resizing. 


### SIMID:Creative:requestSkip ### {#simid-creative-requestSkip}

The creative requests the player skip ad playback if possible.

See [[#workflow-creative-skips]]

#### resolve #### {#simid-creative-requestSkip-resolve}
If the player skips the ad, it responds with a `resolve`. The player then goes through its skip workflow. See [[#simid-player-adSkipped]] <span steps><b>5</b><b>6</b><b>7</b></span>

#### reject #### {#simid-creative-requestSkip-reject}
The player replies with a `reject` if it cannot skip the ad. With the skip rejection:
	<ul collapse>
		<li>The media playback continues.</li>
		<li>The iframe remains visible.</li>
		<li>The player continues posting `SIMID:Media` and `SIMID:Player` messages to the SIMID iframe.</li>
		<li>The creative maintains two-way communication with the player; it waits for, and responds to, the player transmitting ad completion related messages.</li>
	</ul>

### SIMID:Creative:requestStop ### {#simid-creative-requestStop}

The creative requests the player stop video playback if possible.

See [[#workflow-request-stop]]


#### resolve #### {#simid-creative-requestStop-resolve}
If the player can stop the ad, it responds with a `resolve` (<a href="#diagram-requestStop">diagram 13</a>, <span step><b>4</b></span>). The player then goes through [[#workflow-request-stop]] workflow (<a href="#diagram-requestStop">diagram 13</a>, <span steps><b>5</b><b>6</b><b>7</b></span>).


#### reject #### {#simid-creative-requestStop-reject}
If the player cannot stop the ad, it responds with a `reject`. With the requestStop rejection:
<ul collapse>
	<li>The media playback continues - if not previously ended;</li>
	<li>The iframe remains visible;</li>
	<li>The player continues posting messages to the iframe.</li>
</ul>

The creative keeps communication with the player open; it waits for, and responds to, the player transmitting ad completion related messages.


# Referencing a SIMID creative from VAST # {#api-vast}

The VAST 4.x response designates the `<InteractiveCreativeFile>` element to describe the ad's interactive component data. For SIMID, `<InteractiveCreativeFile>` element must include the following required attributes and their values: `type="text/html"` and `apiFramework="SIMID"`.

<div class="example">
<div class="xml-highlight"><pre style="line-height: 125%">
<span class="hnode">&lt;InteractiveCreativeFile</span> <span class="hattr">type=</span><span class="hattrval">"text/html"</span> <span class="hattr">apiFramework=</span><span class="hattrval">"SIMID"</span> <span class="hattr">variableDuration=</span><span class="hattrval">"true"</span><span class="hnode">&gt;</span>
    <span class="hcdata">&lt;![CDATA[https://adserver.com/ads/creative.html]]&gt;</span>
<span class="hnode">&lt;/InteractiveCreativeFile&gt;</span>
</pre></div>
</div>

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
[[#workflow-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).

# Common Workflows # {#common-workflows}

## How to Handle Ad Loading ## {#workflow-ad-loading}

The player must follow this workflow for loading an ad. See <a href="#diagram-simid-initialization">Diagram - SIMID Loading and Initialization</a> below.

1. The player creates an iframe for the SIMID interactive component. The iframe should start hidden. While invisible, the iframe must be capable of executing JavaScript and loading resources.
1. The player starts listening to the `message` event on the window that is the parent of the creative iframe.
1. The player sets the iframe src attribute to the URL provided by the creative's VAST `<InteractiveCreativeFile/>` element. The player must assume the iframe is cross-origin.
1. The player waits until the creative initializes a session and posts `createSession` message (see [[#protocol-session-layer]]). The player responds to the session initialization with a `resolve` message. 

1. The player sends a [[#simid-player-init]] message with relevant parameters. The player waits until the creative responds with [[#simid-player-init-resolve]]. If the creative responds with [[#simid-player-init-reject]], the player should unload the creative's iframe.

1. Where possible, to synchronize media playback and the creative UI, the player should wait until both the creative has responded to the [[#simid-player-init]] with [[#simid-player-init-resolve]] and the media is ready to play. Media readiness means sufficient payload arrived, and the first frame shows.

1. When the media starts, the player sends a [[#simid-player-startCreative]] message. The creative should respond to [[#simid-player-startCreative]] message with [[#simid-player-startCreative-resolve]] immediately. 

1. The player makes the iframe visible. With video ads, the player must position the iframe over media element at player's upper-left corner and set iframe dimensions to media's width and height.

<div diagram id="diagram-simid-initialization">
	<p>SIMID Loading and Initialization</p>
	<img src="images/dgrm-simid-initialization.png" alt="SIMID Initialization.">
	<ol dgrm-details>
		<li>Player starts listening to `message` event on the window.</li>
		<li>Player creates hidden `iframe`.
			<ol>
				<li>Player sets `iframe.src` to the value of the VAST `<InteractiveCreativeFile>` element.</li>
				<li>Player appends `iframe` to its container.</li>
			</ol>
		</li>
		<li>Creative loads and posts `createSession` message.
			<ol>
				<li>Player responds with `resolve` immediately.</li>
			</ol>
		</li>
		<li>
			Player posts [[#simid-player-init]] immediately.
			<ol>
				<li>Creative responds with [[#simid-player-init-resolve]] as soon as possible.</li>
				<li>Alternatively, the creative may reject `Player:init`. In such cases:
					<ol>
						<li>Creative posts [[#simid-player-init-reject]].</li>
						<li>Player unloads creative.</li>
					</ol>
				</li>
			</ol>
		</li>
		<li>Player initializes media at its discretion.
			<ol>
				<li>Media playback begins.</li>
			</ol>
		</li>
		<li>Player posts [[#simid-player-startCreative]] immediately.
			<ol>
				<li>Creative should respond to `Player:startCreative` with [[#simid-player-startCreative-resolve]] immediately.</li>
			</ol>
		</li>
		<li>Player makes SIMID iframe visible.</li>
	</ol>
</div>

## Typical Initialization WorkFlow ## {#workflow-initialization}

The ideal user ad experience has the simultaneous start of media playback and display of the  interactive overlay (the SIMID creative). Once the SIMID creative recieves the `Player:init` message, its may not yet be ready to display (for example it maybe be loading assets). To accommodate this latency, the player posts a `Player:init` message before ad media playback begins and waits for the SIMID iframe to respond with [[#simid-player-init-resolve]]. 

The player should post `Player:init` as soon as the creative dispatches a `createSession` message (section [[#protocol-establish-session]]) <a href="#diagram-player-init-normal">Normal Ad Initialization Sequence</a>, <span steps><b>1</b><b>2</b></span>. SIMID creative code must be ready to process the `Player:init` message immediately <span step><b>3</b></span>).

After the player gets a resolve message <a href="#diagram-player-init-normal">Normal Ad Initialization Sequence</a>, <span step><b>4</b></span>, it initializes media playback at its discretion <span step><b>5</b></span>. Once media rendering begins <span step><b>6</b></span>, the player reports impression <span step><b>7</b></span> and posts [[#simid-player-startCreative]] <span step><b>8</b></span>.

<div diagram id="diagram-player-init-normal">
  <p>Normal Ad Initilaization Sequence</p>
  <img src="images/dgrm-init-normal.png" alt="Normal Ad Initialization Sequence"/>
  <ol dgrm-details>
    <li>Creative initializes the session.</li>
    <li>Player posts `Player:init` message immediately upon session creation.</li>
    <li>Creative proccesses initialization data and finalizes assets loading.</li>
    <li>Creative responds with [[#simid-player-init-resolve]].</li>
    <li>Player starts media playback at its discretion.</li>
    <li>Media renders.</li>
    <li>Player reports impression.</li>
    <li>Player posts [[#simid-player-startCreative]] immediately.</li>
  </ol>
</div>

## Typical Start Creative WorkFlow ## {#workflow-startCreative}

<div diagram id="diagram-player-startcreative">
 <p>Normal `Player:startCreative` Sequence</p>
 <img src="images/dgrm-startCreative-normal.png" alt="startCreative normal sequence.">
 <ol dgrm-details>
   <li>Media playback begins.</li>
   <li>Player posts `Player:startCreative`.</li>
   <li>Creative responds with a `resolve`.</li>
   <li>Player displays the creative iframe.</li>
 </ol>
</div>

## Uninterrupted Initialization WorkFlow ## {#workflow-uninterupted-initialization}

In the case where publisher environments prohibit media playback interruptions, waiting for the creatives is not possible. The media player renders the ad media immediately - before the creative confirms its readiness (<a href="#diagram-player-init-special">Special Creative Initialization Cases</a>, <span step><b>1</b></span>). Some examples include SSAI and live broadcasts.

In these situations, the player keeps the iframe invisible and refrains from posting messages to the creative until it responds to the `Player:init` with a `resolve` message.

<div diagram id="diagram-player-init-special">
  <p>Special Creative Initialization Cases</p>
  <img src="images/dgrm-init-special.png" alt="Creative initialization special cases sequence">
  <ol dgrm-details>
    <li>Player initializes ad media playback.</li>
    <li>Player posts `Player:init` message after ad media playback started.</li>
    <li>Creative proccesses initialization data and finalizes assets loading. Sub-loading routines may cause latencies.</li>
    <li>Creative responds with [[#simid-player-init-resolve]].</li>
    <li>Player posts [[#simid-player-startCreative]] immediately.</li>
  </ol>
</div>


## Creative Delays Resolving Init ## {#workflow-delayed-init-resolve}

The interactive creative responding to a `Player:init` message with a `resolve` message is a critical step in the SIMID ad serving flow (<a href="#diagram-player-init-normal">Init Diagram</a>,  <span step><b>4</b></span> above). The player keeps the SIMID iframe invisible and does not post either `SIMID:Player` or `SIMID:Media` messages until the iframe replies with a `resolve` message.

If the interactive creative fails to respond to a `Player:init` message within the allotted time, the player may continue with ad media rendering only (<a href="#diagram-player-init-resolve-timeout">Player:init resolve</a> <span step><b>2</b></span>). 

The player maintains the hidden interactive creative until ad media playback completion.

If the interactive creative does not resume communication by the playback end, the player must report the VAST error tracker (if available) with the code 1212. See <a href="#diagram-player-init-resolve-timeout">Player:init resolve</a> <span step><b>5</b></span>).

<div diagram id="diagram-player-init-resolve-timeout">
  <p>`Player:init resolve` delay</p>
  <img src="images/dgrm-init-resolve-delay.png" alt="Player:init resolve delay">
  <ol dgrm-details>
    <li>Player posts `Player:init` message and establishes a timeout.</li>
    <li>Player starts ad media playback upon timeout expiration.</li>
    <li>Player reports impression.</li>
    <li>Media playback completes.</li>
    <li>Player reports error tracker.</li>
    <li>Player unloads the iframe.</li>
  </ol>
</div>


## Creative Rejects Init ## {#workflow-reject-initialization}

The creative may respond with a `reject` based on its internal logic. In response to `reject`, the player proceeds with the ad media playback. The player may unload the iframe. The player reports VAST error trackers with the `errorCode` specified by the creative.

<div diagram id="diagram-player-init-reject">
  <p>`Player:init reject` Sequence</p>
  <img src="images/dgrm-init-reject.png" alt="Player:init reject sequence.">
  <ol dgrm-details>
    <li>Player posts `Player:init` message.</li>
    <li>Creative responds with a `reject`.</li>
    <li>Player unloads the creative iframe.</li>
    <li>Player reports VAST error tracker.</li>
    <li>Player starts media.</li>
  </ol>
</div>


## Nonlinear Initialization and Start WorkFlow ## {#workflow-initialization-nonlinear}

1. The player creates a hidden iframe and loads the creative.  This can happen before the ad display time to preload the ad.
1. The creative will initialize a session.
1. If the creative doesn’t initialize a session within a reasonable time, the player drops the creative and reports an error.
1. The player sends a [[#simid-player-init]] message with relevant parameters.
1. If the player can initialize, the creative responds with resolve.
1. If the creative responds with reject, or doesn’t respond in time, the player drops the creative's iframe and reports an error.
1. When the player is ready to show the iframe, the player sends a [[#simid-player-startCreative]] message.
1. If the creative responds with reject, or doesn’t respond in time, the player drops the creatives iframe and reports an error.
1. When the creative responds with resolve, the player makes the iframe visible.


## How to Handle Ad Playback ## {#workflow-ad-playback}

The media player is responsible for ad media playback handling as well as tracking media related events. The SIMID creative manages interactive content and internal tracking related to interactivity.


### Ad Pause ### {#workflow-ad-pause}

If the {{EnvironmentData/variableDurationAllowed}} flag is set to `true` then
the player should enable media 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 media playback, it should send a
SIMID:Creative:requestPlay message. The player must
respond to SIMID:Creative:requestPlay message with resolve and play the media.


### Ad Resizing and Fullscreen ### {#workflow-resizing}

The player may resize the ad slot. The player must send a [[#simid-player-resize]] message any time the ad slot size is changed.

If {{EnvironmentData/fullscreenAllowed}} is `true`, the SIMID creative may
send a [[#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 [[#simid-player-resize]] message to the SIMID creative
with {{ResizeParameters/fullscreen}} set to `true` and {{ResizeParameters/videoDimensions}} and
{{ResizeParameters/creativeDimensions}} set to the fullscreen dimensions.

If player goes fullscreen on its own. Then the player must send a [[#simid-player-resize]] message to the SIMID creative
with {{ResizeParameters/fullscreen}} set to `true` and {{ResizeParameters/videoDimensions}} and
{{ResizeParameters/creativeDimensions}} set to the fullscreen dimensions.


## How to Handle Ad End and Unload ## {#workflow-end}

Following are cases where ad can end:
1. Ad was skipped, either by player (see [[#workflow-player-skips]]) or creative (See [[#workflow-creative-skips]]).
2. The creative has fired [[#simid-creative-requestStop]] message and the player has allowed the ad to stop.
3. The player has fired [[#simid-player-adStopped]] message and the creative resolved.
4. Ad errors out. See [[#workflow-error]].

### Player Skips Ad ### {#workflow-player-skips}

**Skip Ad Handled by Player**
1. The player sends a [[#simid-player-adSkipped]] message to the ad.
2. The player hides the creative.
3. The creative may dispatch any tracking pixels via [[#simid-creative-reportTracking]]
3. The creative may wait for [[#simid-creative-reportTracking-resolve]] from the reportTracking message.
4. The creative dispatches `resolve` on the `adSkipped` message [[#simid-player-adSkipped-resolve]].
5. The player fires any skip tracking pixels.
6. The player unloads the ad.

### Creative Skips Ad ### {#workflow-creative-skips}
The creative requests ad skip by posting a `SIMID:Creative:requestSkip` message. If feasible, in response to `requestSkip`, the player terminates the ad and goes through the [[#simid-player-adSkipped]] message sequence. 
 
Note: the SIMID interactive component implements skip related behavior and features (<button skip-ad>Skip Ad</button> button) only if the player delegates skippability to the creative - the value of [[#simid-player-init]] message `args.environmentData.skippableState` is `"adHandles"`. 


<div diagram id="diagram-requestSkip">
  <p>`Creative:requestSkip` Sequence</p>
  <img src="images/dgrm-requestSkip.png" alt="Creative:requestSkip sequence.">
  <ol dgrm-details>
    <li>Creative posts `Creative:requestSkip` message.</li>
    <li>Player hides the SIMID iframe.</li>
    <li>Player stops the ad media playback.</li>
    <li>Player responds with [[#simid-creative-requestSkip-resolve]].</li>
    <li>Player posts [[#simid-player-adSkipped]] message.</li>
    <li>Creative responds to `Player:adSkipped` with [[#simid-player-adSkipped-resolve]].</li>
    <li>Player unloads the SIMID iframe.</li>
  </ol>
</div>

### Ad Ends Before Media Completion ### {#workflow-end-before-complete}

This scenario applies when the creative signal to the player to dismiss the ad, typically at the prompting of the user. A good example is a survey that allows the viewer to skip immediately to content when completed.
1. The ad cleans up and dispatches [[#simid-creative-requestStop]].
2. The player unloads the ad.

### Ad Completes at Media Completion ### {#workflow-complete}

When an ad finishes at the same time as its media.
1. The player sends a [[#simid-player-adStopped]] message to the ad.
2. The player hides the creative.
3. The creative may dispatch any tracking pixels via [[#simid-creative-reportTracking]]
4. The creative may wait for a [[#simid-creative-reportTracking-resolve]] response message from the reportTracking message.
5. The creative dispatches `resolve` on the `adStopped` message [[#simid-player-adStopped-resolve]].
6. The player unloads the ad.

### Ad Errors Out ### {#workflow-error}

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
[[#simid-player-init-resolve]] in a reasonable amount of time.

When an player errors out it must follow these steps.
1. The player sends a [[#simid-player-fatalError]] message to the ad.
2. The player hides the creative.
3. The creative may dispatch any tracking pixels via [[#simid-creative-reportTracking]]
4. The creative may wait for a [[#simid-creative-reportTracking-resolve]] response from the reportTracking message.
5. The creative dispatches `resolve` on the `fatalError` message [[#simid-player-fatalError-resolve]].
6. The player unloads the ad.

### Ad Requests Stop ### {#workflow-request-stop}

The creative stops the ad by posting a `SIMID:Creative:requestStop` message.

If feasible, the player hides the iframe, stops media playback that is still in progress, and responds with a [[#simid-creative-requestStop-resolve]]. Subsequently, the player proceeds with the [[#simid-player-adStopped]].

The SIMID interactive component engages ad stop functionality only if the player states its ability to vary ad duration. See [[#simid-player-init]], `Message.args.variableDurationAllowed` details. The interactive component logic must expect that the player will unload SIMID iframe immediately upon posting a `resolve` response under the SIMID-compliant circumstances.

In the event the interactive component disregards or fails to accommodate player’s ability to resolve `requestStop`, the iframe remains visible and the player continues sending `SIMID:Media` and `SIMID:Player` messages. The creative should maintain communication with the player. See [[#simid-creative-requestStop-reject]].


<div diagram id="diagram-requestStop">
  <p>`Creative:requestStop` Sequence</p>
  <img src="images/dgrm-requestStop.png" alt="Creative:requestStop sequence.">
  <ol dgrm-details>
    <li>Creative posts `Creative:requestStop` message.</li>
    <li>Player hides the SIMID iframe.</li>
    <li>Player stops the ad media playback.</li>
    <li>Player responds with [[#simid-creative-requestStop-resolve]].</li>
    <li>Player posts [[#simid-player-adStopped]] message.</li>
    <li>Creative responds to `Player:adStopped` with [[#simid-player-adStopped-resolve]].</li>
    <li>Player unloads the SIMID iframe.</li>
  </ol>
</div>

## Ad Duration Changed Workflow ## {#workflow-change-duration}

### Ad Extends Beyond Media Completion ### {#workflow-extend}

This scenario is only possible when the
{{EnvironmentData/variableDurationAllowed}} flag is set to `true`. Media
duration must only be extended in response to user interaction.
1. User interacts at any point during playback of the media, triggering extended ad portion.
2. The Creative dispatches [[#simid-creative-requestChangeAdDuration]] message with the new duration.
3. The ad enters its extended phase.
4. The creative dispatches [[#simid-creative-requestStop]] when extended phase is finished.

### Ad Duration Changed Workflow - Known Time ### {#workflow-ad-duartion-changed-known}
<div diagram id="diagram-durationchange-known">
  <p>Known Ad Duration Change Sequence</p>
  <img src="images/dgrm-requestChangeAdDuration-known.png" alt="requestChangeAdDuration known duration change handling.">
  <ol dgrm-details>
    <li>Player starts countdown. Countdown depends on the media progress.</li>
    <li>Creative posts `requestChangeAdDuration` with the `duration` value greater than zero.</li>
    <li>Player modifies countdown that now depends on the specified by the creative ad duration.</li>
    <li>Countdown finishes.</li>
    <li>Player receives countdown completion notification.</li>
    <li>Player posts [[#simid-player-adStopped]] message.</li>
  </ol>
</div>

### Ad Duration Changed Workflow - Unknown Time ### {#workflow-ad-duartion-changed-unknown}
<div diagram id="diagram-durationchange-unknown">
  <p>Unknown Ad Duration Change Sequence</p>
  <img src="images/dgrm-requestChangeAdDuration-unknown.png" alt="requestChangeAdDuration unknown duration change handling.">
  <ol dgrm-details>
    <li>Player starts countdown. Countdown depends on the media progress.</li>
    <li>Creative posts `requestChangeAdDuration` with the `duration` value `-2`.</li>
    <li>Player stops countdown.</li>
    <li>Creative posts [[#simid-creative-requestStop]] message.</li>
  </ol>
</div>

## User Experience ## {#user-experience}

Both ad creatives and media players should ensure that consumers are presented with a good ad experience.

This specification does not define the user experience for a close control (close button) 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.  Some implementations may have a publisher provided close control, as well as various other controls, and others may not.

The ad creative can also request to be dismissed at any point in time.  An ad creative may opt to show its own controls, including a close control.

# Error Handling and Timeouts # {#errors}

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.

# Messaging Protocol # {#msg-proto}

In SIMID, the media player and the creative overlay communicate by exchanging asynchronous signals that maintain a custom messaging protocol. This protocol governs  [[#protocol-data-layer]], [[#protocol-transport-layer]], and [[#protocol-session-layer]].

## Data Layer ## {#protocol-data-layer}
SIMID messages transport data. In HTML environments, the data is the `message` argument of the `Window.postMessage()` function.

### Data Structure ### {#message-data-structure}

The `message` data implements the following data structure:
<xmp class="idl">
dictionary Message {
  required DOMString sessionId;
  required unsigned long messageId;
  required unsigned long timestamp;
  required DOMString type;
  any args;
};
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>sessionId</dfn>
	<dd>A string that uniquely identifies the session to which Message belongs. See [[#protocol-session-layer]].
	<dt><dfn>messageId</dfn>
	<dd>A message sequence number in the sender's system. Each participant establishes its own independent sequence counter for the session. The first message `messageId` value is `0`. The sender increments each subsequent messageId value by `1`. In practice, this means that the creative and the player `messageId` values will be different based on the number of sent messages.
	<dt><dfn>timestamp</dfn>
	<dd>A number of milliseconds since January 1, 1970, 00:00:00 UTC (Epoch time). The message sender must set `timestamp` value as close as possible to the moment the underlying process occurs. However, the receiver should not assume that the `timestamp` value reflects the exact instant the message-triggering event occurred.
	<dt><dfn>type</dfn>
	<dd>A string that describes the message-underlying event and informs the receiver how to interpret the `args` parameter.
	<dt><dfn>args</dfn>
	<dd>Additional information associated with the message `type`. 
</dl>

<div class="example">
<b>Example of message data:</b>
<div class="js-highlight">
<pre style="line-height: 125%">
{
    sessionId: <span class="hstr">"173378a4-b2e1-11e9-a2a3-2a2ae2dbcce4"</span>,
    messageId: <span class="hnum">10</span>,
    timestamp: <span class="hnum">1564501643047</span>,
    type: <span class="hstr">"SIMID:Player:adStopped"</span>,
    args: {
        code: <span class="hnum">0</span>
    }
}
</pre>
</div>
</div>



## Messages Categories ## {#protocol-message-categories}

The protocol defines two message classes: 
<ul>
<li><strong><i>Primary</i></strong> messages - the signals triggered by the sender's internal logic.</li>
<li><strong><i>Response</i></strong> messages - the signals the receiver transmits as acknowledgments of the primary message receipt and processing. There are two response Message types: [[#protocol-message-categories-resolve]] and [[#protocol-message-categories-reject]].</li>
</ul>

Both primary and response messages implement the same data structure (see [[#message-data-structure]]). 

### `resolve` Messages ### {#protocol-message-categories-resolve}

The receiver confirms successful message processing by replying with a resolution message.

`Message.type` must be `resolve`.

`Message.args` must be a `ResolveMessageArgs` object:
<xmp class="idl">
    dictionary ResolveMessageArgs {
        required unsigned long messageId;
        any value;
    };
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>messageId</dfn>
	<dd>The value of the messageId attribute of the message to which the receiver responds.
	<dt><dfn>value</dfn>
	<dd>Additional data associated with this `resolve` message.
</dl>

<div class="example">
<b>Example of `resolve` message:</b>
<div class="js-highlight">
<pre style="line-height: 125%">
{
    sessionId: <span class="hstr">"173378a4-b2e1-11e9-a2a3-2a2ae2dbcce4"</span>,
    messageId: <span class="hnum">10</span>,
    timestamp: <span class="hnum">1564501643047</span>,
    type: <span class="hstr">"resolve"</span>,
    args: {
        messageId: <span class="hnum">5</span>,
        value: {
            id: <span class="hnum">45</span>
        }
    }
}
</pre>
</div>
</div>


### `reject` Messages ### {#protocol-message-categories-reject}

When the receiver is unable to process the message, it responds with rejection.

`Message.type` must be `reject`.

`Message.args.value` must be a `RejectMessageArgsValue` object:

<xmp class="idl">
    dictionary RejectMessageArgsValue {
        unsigned long errorCode;
        DOMString message;
    };
</xmp>
<dl dfn-type=attribute dfn-for=FooInterface class="idl highlight def">
	<dt><dfn>errorCode</dfn>
	<dd>The error code associated with the reason the receiver `rejects` the message.
	<dt><dfn>message</dfn>
	<dd>Additional information.
</dl>

<div class="example">
<b>Example of `reject` message:</b>
<div class="js-highlight">
<pre style="line-height: 125%">
{
    sessionId: <span class="hstr">"173378a4-b2e1-11e9-a2a3-2a2ae2dbcce4"</span>,
    messageId: <span class="hnum">10</span>,
    timestamp: <span class="hnum">1564501643047</span>,
    type: <span class="hstr">"reject"</span>,
    args: {
        messageId: <span class="hnum">5</span>,
        value: {
            errorCode: <span class="hnum">902</span>,
            message: <span class="hstr">"The feature is not available."</span>
        }
    }
}
</pre>
</div>
</div>



## Transport Layer ## {#protocol-transport-layer}

Transport is a communication mechanism that can send serialized messages between two parties. 

### `postMessage` Transport

In HTML environments, where the player loads creative overlay in a cross-origin iframe, the parties utilize the standard `Window.postMessage()` API as the message transport mechanism.

### Message Serialization

The message sender serializes data into a `JSON` string. The deserialized `JSON` must result in a clone of the original Message data object. 

In JavaScript, `JSON.stringify()` performs serialization; `JSON.parse()` - deserialization. 


## Session Layer ## {#protocol-session-layer}

The media player may manage several ads that are in different phases of their lifespans; multiple concurrent sessions may be active. For example, while the player is rendering ad-A, it preloads and engages ad-B. Simultaneous two-way communication between the player and both ads persists. 

Each session has a unique identifier. All messages that belong to a specific session must reference the same session id. 

### Establishing a New Session ### {#protocol-establish-session}

SIMID delegates the session initialization to the creative overlay. The creative generates a unique session id and posts the first session message with the `Message.type createSession`. By posting the `createSession` message, the creative acknowledges its readiness to receive messages from the player. 

Note: There is no expectation for the interactive component to be entirely able to participate in ad rendering at the time the creative signals `createSession` message. Full creative initialization may occur at later stages when the player provides complete data - see [[#simid-player-init]]. 

<div class="example">
<b>Example of `createSession` Message data:</b>
<div class="js-highlight">
<pre style="line-height: 125%">
{
    sessionId: <span class="hstr">"173378a4-b2e1-11e9-a2a3-2a2ae2dbcce4"</span>,
    messageId: <span class="hnum">0</span>,
    timestamp: <span class="hnum">1564501643047</span>,
    type: <span class="hstr">"createSession"</span>,
    args: { }
}
</pre>
</div>
</div>

Creative should initialize the session as soon as possible. The player should establish a reasonable timeout for the session initialization message receipt.

The player responds to `createSession` with a `resolve` message.

<div diagram id="diagram-durationchange-unknown">
	<p>Typical Session Initialization Sequence</p>
	<img src="images/dgrm-session-init-sequence.png" alt="Typical session initialization.">
	<ol dgrm-details>
		<li>The player starts a `createSession` message timeout.</li>
		<li>The player loads creative.</li>
		<li>Creative posts `createSession` message.</li>
		<li>The player cancels the timeout.</li>
		<li>The player responds with a `resolve` message.</li>
		<li>The player initializes creative. See [[#simid-player-init]].</li>
	</ol>
</div>

### Session Establishing Delays and Failures

Typically, the player should wait for the creative to post a `createSession` message before proceeding to the simultaneous rendering of both ad media and the interactive component. However, SIMID recognizes scenarios when:
<ul>
<li>The creative fails to establish a session within the allotted time.</li>
<li>The player's environment restricts timeout usage (effectively, the timeout is zero). Specifically, SSAI and live broadcasts force zero-timeout use cases.</li>
</ul>

The creative's failure to establish a session does not prevent the player from rendering the ad media. 
If the creative does not post a `createSession` message on time, the player may proceed with the ad media rendering. However, the player allows the creative to recover in the middle of the ad media playback. The player: 
<ul>
<li>Does not unload the creative.</li>
<li>Does not post messages to the creative.</li>
<li>Maintains the `creativeSession` message handler. </li>
</ul>

If the creative has not established a session before the media playback is complete, the player will report a VAST Error tracker with the proper error code. Examples of situations when this may occur are listed below.

<b>Sequence for a failed session initialization</b>
<ol>
<li>The timeout expires.</li>
<li>The `createSession` message does not arrive.</li>
<li>The player starts ad media.</li>
<li>The player reports the impression.</li>
<li>The ad media playback completes.</li>
<li>The player reports the VAST error tracker.</li>
<li>The player unloads the creative iframe.</li>
</ol>

<b>Creative posts a `createSession` message after the timeout occurs</b>
<ol>
<li>The timeout expires.</li>
<li>The player retains the interactive component.</li>
<li>The player initiates ad media playback.</li>
<li>The player reports the impression.</li>
<li>The player does not post messages to the creative.</li>
<li>The creative posts `createSession` message.</li>
<li>The player proceeds with the creative initialization.</li>
</ol>

# Error Codes # {#error-codes}
The table below is the list of error codes the player and the creative use with `reject` messages. SIMID allocates the range `1100-1199` to the errors that the creative reports; the range `1200-1299` to the errors the player reports.
<p table-header id="table-error-codes">Error Codes.</p>
<table class="alternatecolor">
  <tbody>
    <tr>
      <th>Error Code</th>
      <th>Error Type</th>
      <th>Description</th>
    </tr>
    <tr>
      <td>1100</td>
      <td>Unspecified error.</td>
      <td>Catchall error if the creative could not find a matching error code.
      The creative should be more specific in the error message.</td>
    </tr>
    <tr>
      <td>1101</td>
      <td>Resources could not be loaded.</td>
      <td>The SIMID creative tried to load resources but failed.</td>
    </tr>
    <tr>
      <td>1102</td>
      <td>Playback area not usable by creative.</td>
      <td>The dimensions the creative needed were not what it received.</td>
    </tr>
    <tr>
      <td>1103</td>
      <td>Wrong SIMID version.</td>
      <td>The creative could not support the players version.</td>
    </tr>
    <tr>
      <td>1104</td>
      <td>Creative not playable for a technical reason on this site.</td>
      <td></td>
    </tr>
    <tr>
      <td>1105</td>
      <td>Request for expand not honored.</td>
      <td>The creative requested to expand the media player but the player did not allow it.</td>
    </tr>
    <tr>
      <td>1106</td>
      <td>Request for pause not honored.</td>
      <td>The creative posted [[#simid-creative-requestPause]] but the player did not pause.</td>
    </tr>
    <tr>
      <td>1107</td>
      <td>Play mode not adequate for creative.</td>
      <td>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.</td>
    </tr>
    <tr>
      <td>1108</td>
      <td>Ad internal error.</td>
      <td>The creative had an error not related to any external dependencies.</td>
    </tr>
    <tr>
      <td>1109</td>
      <td>Device not supported.</td>
      <td>The creative could not play or render on the device.</td>
    </tr>
    <tr>
      <td>1110</td>
      <td>The player is not following the spec in the way it sends messages.</td>
      <td></td>
    </tr>
    <tr>
      <td>1111</td>
      <td>The player is not responding adequately to messages.</td>
      <td></td>
    </tr>
    <tr>
      <td>1200</td>
      <td>Unspecified error.</td>
      <td>Catchall error if the player could not find a matching error code.
		      The player should be more specific in the error message.</td>
    </tr>
    <tr>
      <td>1201</td>
      <td>Wrong SIMID version.</td>
      <td>The player could not support the creatives version.</td>
    </tr>
    <tr>
      <td>1202</td>
      <td>The creative is requesting more time than the player
          is willing to support.</td>
      <td></td>
    </tr>
    <tr>
      <td>1203</td>
      <td>The creative is requesting more functionality than the player is
          willing to support.</td>
      <td></td>
    </tr>
    <tr>
      <td>1204</td>
      <td>The creative is doing actions not supported on this site.</td>
      <td></td>
    </tr>
    <tr>
      <td>1205</td>
      <td>The creative is overloading the postmessage channel.</td>
      <td></td>
    </tr>
    <tr>
      <td>1206</td>
      <td>The SIMID media could not be loaded.</td>
      <td></td>
    </tr>
    <tr>
      <td>1207</td>
      <td>Media Timeout.</td>
      <td>The ad media creative buffered
          for too long and timed out.</td>
    </tr>
    <tr>
      <td>1208</td>
      <td>The creative is taking too long to resolve or reject messages.</td>
      <td></td>
    </tr>
    <tr>
      <td>1209</td>
      <td>The SIMID media from the VAST response is not supported
          on this device.</td>
      <td></td>
    </tr>
    <tr>
      <td>1210</td>
      <td>The creative is not following the spec when initializing.</td>
      <td></td>
    </tr>
    <tr>
      <td>1211</td>
      <td>The creative is not following the spec in the way it
          sends messages.</td>
      <td></td>
    </tr>
    <tr>
      <td>1212</td>
      <td>The creative did not reply to the [[#simid-player-init]] message.</td>
      <td></td>
    </tr>
    <tr>
      <td>1213</td>
      <td>The creative did not reply to the [[#simid-player-startCreative]] message.</td>
      <td></td>
    </tr>
    <tr>
      <td>1214</td>
      <td>Environment does not support navigation.</td>
      <td>The creative posted [[#simid-creative-requestNavigation]], but the environment doesn’t support it. The creative should be opening the navigation window.</td>
    </tr>
    <tr>
      <td>1215</td>
      <td>Navigation not possible at all on this device.</td>
      <td>The creative posted [[#simid-creative-requestNavigation]]. However, navigation window opening is not possible at all on this device.</td>
    </tr>
    <tr>
      <td>1216</td>
      <td>Too many calls to [[#simid-creative-requestNavigation]].</td>
      <td>The creative asked for request navigation too many times and call will be blocked.</td>
    </tr>
    <tr>
      <td>1217</td>
      <td>Invalid navigation request URL.</td>
      <td>The posted [[#simid-creative-requestNavigation]] with invalid url.</td>
    </tr>
    <tr>
      <td>1218</td>
      <td>Invalid navigation request app.</td>
      <td>The creative requested a play store/app store url but that is not valid on this device.</td>
    </tr>
    <tr>
      <td>1219</td>
      <td>Extra clickthrough blocked.</td>
      <td>Clickthrough has been reported once, but the creative has requested clickthrough again. No click through will be reported.</td>
    </tr>
    <tr>
      <td>1220</td>
      <td>Nonlinear expasion not possible due to problem pausing the media.</td>
      <td>Player is rejecting [[#simid-creative-expandNonlinear]] because it cannot pause media. The player should have informed creative it cannot pause the media on [[#simid-player-init]].</td>
    </tr>
    <tr>
      <td>1221</td>
      <td>Nonlinear expansion rejected by user.</td>
      <td>The user has indicated that the ad should be collapsed so the player will not allow a nonlinear expansion.</td>
    </tr>
    <tr>
      <td>1222</td>
      <td>Player received excessive number of [[#simid-creative-expandNonlinear]] messages.</td>
      <td>The player limits a number of nonlinear ad expands and that limit has been exceeded.</td>
    </tr>
    <tr>
      <td>1223</td>
      <td>Session not created.</td>
      <td>The creative did not create a session. This error could be triggered after a timeout or upon the end of the media playback.</td>
    </tr>
  </tbody>
</table>

# Terminology # {#terminology}

: <dfn>SIMID VAST</dfn>
:: The VAST document that contains the SIMID ad unit components.

: <dfn>SIMID Ad Unit</dfn>
:: The SIMID ad media and the SIMID ad creative.

: <dfn>SIMID Media</dfn>
:: The SIMID ad media component if it's a progressively downloaded media file.

: <dfn>SIMID Media Stream</dfn>
:: The SIMID ad media component if it's SSAI media.

: <dfn>SIMID Live Media Stream</dfn>
:: The SIMID ad media component if live streaming media.

: <dfn>SIMID Creative</dfn>
:: The SIMID ad creative component (HTML document and assets) that overlays the SIMID
	ad video.

: <dfn>SIMID Secondary Video</dfn>
:: Video assets that are loaded as part of the SIMID creative and not the
	primary media.

: <dfn>Content Media</dfn>
:: Any reference to media that is NOT a component or asset of the ad unit.