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
Feedback sent
We appreciate your effort and will try to fix the article