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; `url`, a full Spotify URL 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. Use either `uri` or `url`. If both are provided, `url` takes precedence. See the samples below for examples.
callback	function	Function that receives the created controller object (EmbedController in the following examples)

Code sample using a URI


_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);

Code sample using a URL


_10let element = document.getElementById('embed-iframe');
_10let options = {
_10  width: 200,
_10  height: 400,
_10  url: 'https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5?si=abcdef',
_10};
_10let callback = EmbedController => {};
_10IFrameAPI.createController(element, options, callback);

`EmbedController.loadEntity(spotifyUriOrUrl, preferVideo, startAt)`

Use this method to dynamically load content into an Embed. It accepts either a Spotify URI or a full Spotify URL. Query parameters from a URL input are preserved on the embed player URL.

Parameters

Parameter	Type	Description
spotifyUriOrUrl	string	A Spotify URI (e.g. `spotify:episode:7makk4oTQel546B0PZlDM5`) or a full Spotify URL (e.g. `https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5?si=abcdef`)
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

Code samples


_10// Using a Spotify URI
_10EmbedController.loadEntity('spotify:episode:7makk4oTQel546B0PZlDM5');


_10// Using a full Spotify URL — query parameters are preserved
_10EmbedController.loadEntity(
_10  'https://open.spotify.com/episode/7makk4oTQel546B0PZlDM5?si=abcdef',
_10);

`EmbedController.loadUri(spotifyUri)`

This method remains available for existing integrations. It accepts Spotify URIs only. For new integrations, prefer loadEntity which also accepts full URLs.

Parameters

Parameter	Type	Description
spotifyUri	string	A Spotify URI to load in the Embed (e.g. `spotify:episode:7makk4oTQel546B0PZlDM5`)
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.