Embed player postMessage API

The Acast Embed Player has a simple postMessage API that can be used to control the player. This is a protocol that allows communication between an iFrame (the Acast Embed Player) and the 'parent' (the website which embeds the player).

You do not need an API key to use the postMessage API.

When using the PostMessage API to play the audio, you need to include the `allow= "autoplay"` attribute on the iframe tag. It won't autoplay the audio but permit the player to play the audio even if the user didn't interact with the player.

Example:

<iframe allow="autoplay" src="https://embed.acast.com/show/episode"></iframe>

More information on this here: https://developers.google.com/web/updates/2017/09/autoplay-policy-changes#iframe

The API uses the following commands:

const iframe = document.querySelector('iframe');
const message = {
eventName: '',
data: {},
};
iframe.contentWindow.postMessage(JSON.stringify(message), '*');

You can listen to the message event to get the data sent by the player. For instance, when you query the player with a postmessage:get:* event, it will dispatch the value back. Or events, such as postmessage:on:play and dispatched when the episode is playing.

window.addEventListener(
'message',
event => {
console.log(event.data); // >> { eventName, data }
},
false
);

API Details

Event Triggers

Load the metadata

{
eventName: 'postmessage:do:loadmetadata'
data: { show: 'show-name', episode: 'episode-name' }
}

Triggers `postmessage:on:loadmetadata` event.

Load the audio

{
eventName: 'postmessage:do:load'
}

Triggers `postmessage:on:load` event.

Play the episode

{
eventName: 'postmessage:do:play'
}

Triggers `postmessage:on:play` event.

Play a given episode

{
eventName: 'postmessage:do:play',
data: { show: 'show-name', episode: 'episode-name' }
}

Triggers `postmessage:on:play` event.

Pause

{
eventName: 'postmessage:do:pause'
}

Triggers `postmessage:on:pause` event.

Toggle play/pause

{
eventName: 'postmessage:do:toggle'
}

Triggers `postmessage:on:play` or `postmessage:on:pause` event.

Seek a given position

{
eventName: 'postmessage:do:seek',
data:{ position: 10 }
}

Triggers `postmessage:on:seek` event.

Seek 15s forward

{
eventName: 'postmessage:do:seekforward'
}

Triggers `postmessage:on:seek` event.

Seek 15s back

{
eventName: 'postmessage:do:seekback'
}

Triggers `postmessage:on:seek` event.

Get Queries

Get current episode

{
eventName: 'postmessage:get:current'
}

Response Body:

{
acast: “5930eq94f9ga90df”, //show id
channel: “sd9f8233fg9ogx”, //episode id
episode: “5930eq94f9ga90df”,
show: “sd9f8233fg9ogx”
}

Get episode duration

{
eventName: 'postmessage:get:duration'
}

Response Body:

{
duration: 100.304
}

Get episode progress

{
eventName: 'postmessage:get:progress'
}

Response Body:

{
progress: 9.134
}

Get the playing state

{
eventName: 'postmessage:get:isplaying'
}

Response Body:

{
acast: “5930eq94f9ga90df”, //show id
channel: “sd9f8233fg9ogx”, //episode id
episode: “5930eq94f9ga90df”,
isPlaying: true,
show: “sd9f8233fg9ogx”,
}

Listener Events

on:loadmetadata

Response Body:

{
acast: “episode-name”,
channel: “show-name”,
episode: “episode-name”,
show: “show-name”
}

This event only returns the values passed into `do:loadmetadata`. To get existing metadata, use `on:load`/`on:play`.

on:load

Response Body:

{
acast: “episode-name”,
channel: “show-name”,
episode: “episode-name”,
show: “show-name”
}

on:play

Response Body:

{
acast: “episode-name”;
channel: “show-name”,
episode: “episode-name”
show: “show-name”
}

on:pause

No response body returned.

on:seek

Response Body:

{
position: 10.034
}

Did this answer your question?