iFrame API

Methods

`window.onSpotifyIframeApiReady(object)`

Define this global function so that your app knows when the iFrame API is ready to use. It receives an object (IFrameAPI in our example) which you can use to create controllers.

Parameters

Parameter	Type	Description
IFrameAPI	object	Object you can use to create iFrame API controllers

Code sample


_10window.onSpotifyIframeApiReady = IFrameAPI => {
_10  let element = document.getElementById('embed-iframe');
_10  let options = {
_10    uri: 'spotify:episode:7makk4oTQel546B0PZlDM5',
_10  };
_10  let callback = EmbedController => {};
_10  IFrameAPI.createController(element, options, callback);
_10};

`IFrameAPI.createController(element, options, callback)`

Call createController for each Embed that you'd like to position on the web page.

Parameters

Parameter	Type	Description
element	object	DOM element that you'd like replaced by the Embed
options	object	Key value pairs that configure the new controller. The available options are `uri`, the Spotify URI of the content you'd like loaded first; `width`, the width in pixels of the Embed, and `height`, the height in pixels of the Embed. See the sample below for an example.
callback	function	Function that receives the created controller object (EmbedController in the following examples)

Code sample


_10let element = document.getElementById('embed-iframe');
_10let options = {
_10  width: 200,
_10  height: 400,
_10  uri: 'spotify:episode:7makk4oTQel546B0PZlDM5',
_10};
_10let callback = EmbedController => {};
_10IFrameAPI.createController(element, options, callback);

`EmbedController.loadUri(spotifyUri)`

Use this method to load a new podcast episode into an Embed that you have created.

Parameters

Parameter	Type	Description
spotifyUri	string	String of a podcast episode URI you'd like to load in the Embed
preferVideo	boolean	An optional parameter to play the video of a podcast episode, if available
startAt	number	The timestamp (in seconds) from where playback should start when the `play` method is called
theme	string	An optional parameter to set the theme of the Embed. Possible value is `dark`

Code sample


_10EmbedController.loadUri('spotify:episode:7makk4oTQel546B0PZlDM5');

`EmbedController.play()`

This method begins playing the content that had been previously loaded.

Code sample


_10EmbedController.play();

`EmbedController.pause()`

This method pauses playback.

Code sample


_10EmbedController.pause();

`EmbedController.resume()`

If playback is paused, this method can be used to resume it. If playback was not started, this method will start playback.

Code sample


_10EmbedController.resume();

`EmbedController.togglePlay()`

This method toggles between play and pause.

Code sample


_10EmbedController.togglePlay();

`EmbedController.restart()`

Use this method to restart playback from the beginning.

Code sample


_10EmbedController.restart();

`EmbedController.seek(seconds)`

Use this method to seek to a given point in the podcast episode that has been loaded in the Embed.

Parameters

Parameter	Type	Description
seconds	integer	The number of seconds into the podcast episode after which you would like to move the cursor

Code sample


_10EmbedController.seek(200);

`EmbedController.destroy()`

Destroys the Embed and removes its DOM element from the page.

Code sample


_10EmbedController.destroy();

Events

`ready`

This event fires after an Embed has initialized and is ready to stream content

Code sample


_10EmbedController.addListener('ready', () => {
_10  console.log('The Embed has initialized');
_10});

`playback_started`

This event fires when a track or podcast episode starts playing. For tracks in a collection like playlist or album, it will be fired once for each track as and when it starts playing. Additionally, it also fires if the playback was restarted after it was completed. The event handler will receive an object with a property describing the currently playing entity: playingURI (string).

Code sample


_10EmbedController.addListener('playback_started', e => {
_10  console.log('The playback has started for: ' + e.data.playingURI);
_10});

`playback_update`

This event fires after the state of playback changes. Playback state changes can occur by the user tapping on the playback controls in the Embed, or programmatically through methods of the iFrame API, such as the seek() method.

The event handler will receive an object with four properties describing the current playback state: playingURI (string), isPaused (bool), isBuffering (bool), duration (number) and position (number). duration describes the length of the loaded podcast episode in milliseconds and position describes the cursor location in milliseconds.

Code sample


_10EmbedController.addListener('playback_update', e => {
_10  document.getElementById('progressTimestamp').innerText = `${parseInt(
_10    e.data.position / 1000,
_10    10,
_10  )} s`;
_10});

Notes

The iFrame API's play method, which starts playback of the Embed player without user interaction, might not be supported in all browsers and for all users. For instance, Safari blocks autoplay without user interaction. Read more about autoplay policy or autoplay policy in Chrome.