PostMessage API

The Smartzer player can be controlled by sending events to it. This can be done using the postMessage API. The Smartzer Player is configured to listen to events if the usingExternalComms parameter is set to true in the src URL. Additionally setting the carousel and autoplay parameters to true will configure the player to be preloaded out of view and autoplayed via the postMessage API, for example in a custom media or advertisement carousel, when the iframe comes into view.

Event Structure

The structure of the expected events is as follows:

{
  "source": "SmartzerCommunicator",
  "eventType": "AUTO",
  "eventSource": "PLAYER",
  "eventName": "<event_name>",
  "data": {}
}

The eventName can be any of the following:

Event Name	Description
play	Resume playback of the video at the current timestamp
pause	Pause playback of the video at the current timestamp
stop	Stop the video playback and seek the beginning
mute	Mute the video audio track
unmute	Unmute the video audio track (if allowed*)

*Note: Depending on the browser and the users interaction index, the unmute event will only work if the user has previously muted the video. If the user interacted with the player, the unmute event will not always work, and should wait until a user has interacted with the player.

Sample Usage

For a given iframe embed:

<iframe
  id="frame"
  src="http://player.smartzer.com/{projectTypePrefix}/{projectId}?usingExternalComms=true&carousel=true&autoplay=true"
  allow="autoplay"
></iframe>

The player can be controlled as follows:

frame.contentWindow.postMessage(
  {
    source: 'SmartzerCommunicator',
    eventType: 'AUTO',
    eventSource: 'PLAYER',
    eventName: 'play',
    data: {},
  },
  '*'
);

Iframe loaded event

If a play or pause event is sent to the player while the iframe is still loading, the events might not be intercepted properly and not take effect. To solve this issue, the video within an iframe fires a custom videoReady event once it is ready to be played:

const message = {
  source: 'SmartzerCommunicator',
  eventType: 'AUTO',
  eventSource: 'PLAYER',
  eventName: 'videoReady',
  data: projectId,
};
window.parent.postMessage(message, '*');

This event can be listened to on the parent window object with the following code:

window.addEventListener('message', (event) => fn(event));

The event object contains a projectId, which can be used to identify the correct iframe.

The event handler function can then take in the event object and send the play event back to the correct iframe. This ensures that the events will be intercepted properly after when the iframe has fully loaded.