The player can communicate with the page that embeds it (and vice versa) through an event system.
This allows the client to directly interact with the player (such as controlling its appearance or functionality) and to receive information (like the zoom level, for example).
How it works
Communication between the player and its client is done via https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage .
The client must specify a source that must be valid for the event to be transmitted to the player
Valid sources
‘dam’
The client must also specify a name so that the message is correctly interpreted. The different valid event names and their purposes are described in the table below.
Reference of events managed (listened to) by the players
Event | Payload | Description | Players cibles |
|---|---|---|---|
| {
source: 'dam',
name: 'getMediaInfos'
}
| Request information for viewing the current media | Image |
| {
source: 'dam',
action: 'playerTogglePlayPause'
}
| For a video player, pause the media if it is currently playing; if it is not playing (paused, ended, etc.), switch it to play. | video / audio |
| {
source: 'dam',
action: 'playerPlay'
}
| For a video player, start playing the media. Please note that browsers restrict to start playing a video without user input or with a volume > 0. Once the video has been started by the user, this event is available. | video / audio |
| {
source: 'dam',
action: 'playerPause'
}
| For a video player, pause the media. | video / audio |
| {
source: 'dam',
action: 'playerSeekTo',
payload: 42
}
| For a video player, set the playback to the requested position. | video / audio |
| {
source: 'dam',
action: 'playerFullscreen'
}
| For a video player, set the playback to the requested position. | All |
| {
source: 'dam',
action: 'playerChromeless',
payload: Bool
}
| Toggle the player to or from chromeless mode. In chromeless mode, buttons and action bars are removed, leaving only the media display. | All |
| {
source: 'dam',
action: 'playerMute'
}
| For a video player, mute the media. | video / audio |
| {
source: 'dam',
action: 'playerUnmute'
}
| For a video player, unmute the media. | video / audio |
| {
source: 'dam',
action: 'playerSetVolume',
payload: Number (entre 0 et 100)
}
| For a video player, set the media volume to the requested level. | video / audio |
Sample code
iframe.contentWindow.postMessage(
{
source: 'dam',
name: 'foo',
},
'*',
);
iframe.contentWindow.postMessage(
{
source: 'dam',
action: 'bar',
payload: 42
},
'*',
);
Reference of events sent by the players
Event | Payload | Description | Players |
|---|---|---|---|
| {
name: 'mediaInfos',
source: 'wedia-player',
playerType: "video" | "image" | "document", // type de player qui envoie l'évènement
media: {
"width" : number (pixels), // dans le cas d'une image,
"height": number (pixels), // dans le cas d'une image,
"currentTimestamp": cas d'un player video => timestamp | null,
"index" : cas d'un document, indique la page courante ==> number
},
viewport: {
// Dans un repère où l’origine est le coin haut gauche de l’image :
"topLeft": {
"x" : Abscisse du coin supérieur gauche du frame (pixels),
"y" : Ordonnée du coin supérieur gauche du frame (pixels)
},
"bottomRight": {
"x" : Abscisse du coin inférieur droit du frame (pixels),
"y" : Ordonnée du coin inférieur droit du frame (pixels)
}
"zoom": niveau de zoom actuel (valeur en rapport), // dans le cas d'une image
}
}
| "Sent following:
See: WXM-15239 - Getting issue details... STATUS for a full description of the signature." | Image |
| {
name: 'PlayerDragleave',
source: 'wedia-player',
playerType: playerType: "video" | "image" | "document", // type de player qui envoie l'évènement
dataTransfer: {
types: event.dataTransfer.types // types présent dans l'event source
}
}
| "Sent when the component captures a native dragenter event. We simply relay the information to the integrator." | Image |
| {
name: 'PlayerDragleave',
source: 'wedia-player',
playerType: playerType: "video" | "image" | "document", // type de player qui envoie l'évènement
dataTransfer: {
types: event.dataTransfer.types // types présent dans l'event source
}
}
| "Sent when the component captures a native dragleave event. We simply relay the information to the integrator." | Image |
| {
name: 'PlayerLoaded',
source: 'wedia-player'
}
| Player is loaded | All |
| Par défaut aucun. Dans le cas d’un player video on envoie des infos sur le média : {
name: 'PlayerFullyLoaded',
source: 'wedia-player',
playerData: {
duration: this.player.getDuration(), // Durée du média en en secondes
position : this.player.getPosition(), // Position de départ en secondes
state: this.player.getState(), // Etat du player "playing" | "paused" | "ended"
volume : this.player.getVolume(), // Niveau de volume (0 à 100)
}
}
| "The player and its media are loaded. The image player sends this event when the image is loaded into the player's DOM, while the video player sends it when Other players send it simultaneously with | All |
| {
name: 'PlayerState',
source: 'wedia-player',
state: “playing” | “paused” | “ended”
}
| "In the case of a video player, it sends the media's state with each change of state." | video |
| {
name: 'PlayerVolume',
source: 'wedia-player',
volume: Int (entre 0 et 100)
}
| Dans le cas d’un player video, envoie le niveau de volume à chaque changement de volume. | video |
| {
name: 'PlayerProgress',
source: 'wedia-player',
position: Int (en secondes)
}
| "In the case of a video player, it sends the volume level with each change in volume." | video |
| {
name: 'PlayerFullscreen',
source: 'wedia-player',
fullscreen: Bool
}
| "Event sent on fullscreen enter/leave. Note: This event may not function correctly with v1 players. Consider implementing a solution at the launcher level, such as:
| All |
Sample code for receiving a player message
window.addEventListener('message', (message) => {
if (message.data.name === 'PlayerFullyLoaded') {
console.log('Player loaded')
}
});