Player Events

TABLE OF CONTENTS

Supported Events
Player Events Listener Example
Player Events On AMP Pages
AMP Player Events Example

Player lifecycle events are posted to the top window (and all its child frames) during run-time as post messages. This offers the ability to track and report player behavior in real-time, enabling better insight into user interactions and player performance.

The event will contain a unique event.data.type field equal to 'exco-event' which identifies it as a player event.

The specific events will be differentiated by the event.data.name field which will be in a kebab-cased format.

Each event contains a event.data.metadata field containing the relevant metadata. For instance, the player-id will appear within every event metadata.

NOTE: There is no URL targeting on these post message events, so all frames should be able to listen to them.

Supported Events

Event Name	Metadata	When	Info
player-load	playerId, title	Once player is initialized and loaded	The title field is the title of the first content playing
ad-impression	playerId	Once an ad is shown to the user and an ad impression is registered
ad-completed	playerId	Once an ad reached its end
cta-clicked	playerId, title	Once a user clicks the CTA button	The title field is the title of the content video played when the CTA was clicked
player-closed	playerId, title	Once the player is closed by the user	The title field is the title of the content video when the player was closed
player-muted	playerId, title	Once the player is muted by the user	The title field is the title of the content video when the player was muted
player-unmuted	playerId, title	Once the player is unmuted by the user	The title field is the title of the content video when the player was unmuted
player-playing	playerId, title	Once the user clicks play button	The title field is the title of the content video when the player starts playing
player-paused	playerId, title	Once the player is paused by the user	The title field is the title of the content video when the player was paused

NOTE: The ad-impression event is the preferred way to record the player ad-impression events and is intended to substitute the impression callback div function which will be deprecated in the future.

Player Events Listener Example

<script>
  window.addEventListener('message', event => {
    if (event.data.type === 'exco-event') {
      const { name, metadata } = event.data;
      if (name === 'player-load') {
        console.log(`EX.CO Player Loaded with id: ${metadata.playerId}`);
        /* Do Something */
      }

      if (name === 'ad-impression') {
        console.log('EX.CO Player Ad-Impression');
        /* Do Something */
      }
    }
  });
</script>

Player Events On AMP Pages

First see the AMP integration instructions on how to embed a player on an AMP page. After embedding the player, create an amp-iframe whose src attribute points to an HTML file hosted under the same domain as the page. In this HTML you should have the implementation of the event listener as described in the example above.

NOTE: 
        - If the domain of the listening amp-iframe is different from that on the page, you might  
          encounter a cross-origin block error when trying to listen to the player's post-messages. 
        - Take cared to include the allow-scripts and allow-same-origin under the sandbox attribute  
           on both the player embed and the listener amp-iframe.

AMP Player Events Example

<amp-iframe width="600" height="336"
  layout="responsive"
  sandbox="allow-scripts allow-same-origin"
  src="https://player.ex.co/amp/PLAYER_ID">
  <amp-img layout="fill" src="https://cdn.playbuzz.com/amp/mcd/logo_600x336.png" placeholder></amp-img>
</amp-iframe>
<amp-iframe width="200" height="200" 
  src="//your-domain.com/analytics/player-listener-code.html" 
  sandbox="allow-scripts allow-same-origin allow-popups">
  <iframe>
    #document
    ...
      <script>
        window.addEventListener('message', event => {
          if (event.data.type === 'exco-event') {
            const { name, metadata } = event.data;
            if (name === 'player-load') {
              console.log(`EX.CO Player Loaded with id: ${metadata.playerId}`);
              /* Do Something */
            }

            if (name === 'ad-impression') {
              console.log('EX.CO Player Ad-Impression');
              /* Do Something */
            }
          }
        });
      </script>
    ...
  </iframe>
</amp-iframe>