Player Events

TABLE OF CONTENTS


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>

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select atleast one of the reasons

Feedback sent

We appreciate your effort and will try to fix the article