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
}