Skip to content

Using the iFrame API

Overview

Developers can use the iFrame API to programmatically create and interact with a single Embed or with multiple Embeds in the same web app. The iFrame API includes methods that you can use to start playback, change the content rendering in an Embed, or stop playback. This step-by-step guide explains one way you might implement the iFrame API in an existing web site.

1. Add the iFrame API script tag to your HTML page

Begin by including a <script> element to your web page that refers to Spotify's iFrame API script, https://open.spotify.com/embed/iframe-api/v1. We recommend adding this element somewhere in the <body> element of the page:


_10
<script src="https://open.spotify.com/embed/iframe-api/v1" async></script>

2. Create an element for the iFrame

Add an HTML element with a unique id attribute to your document. This element will be replaced with the Embed iFrame.

For example, you could add a <div> element like this one after the <body> HTML tag:


_10
<div id="embed-iframe"></div>

3. Define the window.onSpotifyIframeApiReady function

After the browser has loaded the iFrame API script, the window.onSpotifyIframeApiReady function is called. This signals to your app that it is now safe to rely on the methods of the iFrame API.


_10
window.onSpotifyIframeApiReady = (IFrameAPI) => {
_10
//
_10
};

4. Create a controller object

Each instance of the Embed should have a controller object associated with it. The controller object has methods that you can use to configure the Embed and to control playback.

The window.onSpotifyIframeApiReady function receives an object parameter, IFrameAPI in our example. You can use the createController method of the IFrameAPI to create a controller for your Embed. createController accepts three mandatory parameters: the element that we defined earlier, an options object, and a callback function:


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

5. Test your page

At this point, your page displays an Embed!

Web page with an Embed for the Life at Spotify podcast

6. Add episode switching logic

Let's use the capabilities of the iFrame API to change the contents of the Embed. We'll add three podcast episodes to the page. Each episode has a button with a data attribute that contains the Spotify ID of the episode.


_13
<div class="episodes">
_13
<button class="episode" data-spotify-id="spotify:episode:7makk4oTQel546B0PZlDM5">
_13
My Path to Spotify: Women in Engineering
_13
</button>
_13
_13
<button class="episode" data-spotify-id="spotify:episode:43cbJh4ccRD7lzM2730YK3">
_13
What is Backstage?
_13
</button>
_13
_13
<button class="episode" data-spotify-id="spotify:episode:6I3ZzCxRhRkNqnQNo8AZPV">
_13
Introducing Nerd Out@Spotify
_13
</button>
_13
</div>

Next, let's modify the callback function we defined earlier. We're going to add a click event listener to each of the buttons.


_10
const callback = (EmbedController) => {
_10
document.querySelectorAll('.episode').forEach(
_10
episode => {
_10
episode.addEventListener('click', () => {
_10
// click event handler logic goes here
_10
});
_10
})
_10
};

Each of the buttons has a data attribute that contains the episode's Spotify URI. As a final step, we're going to use the iFrame API's loadUri method to tell the Embed to load the episode that has been clicked on.


_10
episode.addEventListener('click', () => {
_10
EmbedController.loadUri(episode.dataset.spotifyId)
_10
});

Now we have a menu that loads Spotify episodes in the Embed as each button is clicked!

7. Customize the appearance of the Embed

Our app works, but the design could look better. Let's resize the Embed by adjusting the options object that we set when creating the controller.


_10
const options = {
_10
width: '60%',
_10
height: '200',
_10
uri: 'spotify:episode:7makk4oTQel546B0PZlDM5'
_10
};

Next let's add some CSS to the page to style the menu. You can do this by by linking to an external stylesheet or inline on the page using a <style> element. Here's what our UI looks like now:

Now we have a working example that uses the iFrame API and one of its methods. You can expand on this further by implementing the togglePlay() method or other available methods of the iFrame API. Full source code for this sample page is below:


_72
<html lang="en">
_72
<head>
_72
<title>A Spotify Embed Example</title>
_72
<meta name="viewport" content="width=device-width, initial-scale=1" />
_72
<style>
_72
.episodes {
_72
display: flex;
_72
flex-direction: column;
_72
}
_72
_72
.episode {
_72
min-width: max-content;
_72
margin-bottom: .8rem;
_72
padding: .8rem 1rem;
_72
border-radius: 10px;
_72
border: 0;
_72
background: #191414;
_72
color: #fff;
_72
cursor: pointer;
_72
}
_72
_72
.episode:hover {
_72
background: #1Db954;
_72
}
_72
_72
@media screen and (min-width: 860px) {
_72
body {
_72
display: flex;
_72
flex-direction: row;
_72
gap: 1rem;
_72
}
_72
}
_72
</style>
_72
</head>
_72
_72
<body>
_72
<div class="episodes">
_72
<button class="episode" data-spotify-id="spotify:episode:7makk4oTQel546B0PZlDM5">
_72
My Path to Spotify: Women in Engineering
_72
</button>
_72
<button class="episode" data-spotify-id="spotify:episode:43cbJh4ccRD7lzM2730YK3">
_72
What is Backstage?
_72
</button>
_72
<button class="episode" data-spotify-id="spotify:episode:6I3ZzCxRhRkNqnQNo8AZPV">
_72
Introducing Nerd Out@Spotify
_72
</button>
_72
</div>
_72
_72
<div id="embed-iframe"></div>
_72
<script src="https://open.spotify.com/embed/iframe-api/v1" async>
_72
</script>
_72
<script type="text/javascript">
_72
window.onSpotifyIframeApiReady = (IFrameAPI) => {
_72
const element = document.getElementById('embed-iframe');
_72
const options = {
_72
width: '100%',
_72
height: '160',
_72
uri: 'spotify:episode:7makk4oTQel546B0PZlDM5'
_72
};
_72
const callback = (EmbedController) => {
_72
document.querySelectorAll('.episode').forEach(
_72
episode => {
_72
episode.addEventListener('click', () => {
_72
EmbedController.loadUri(episode.dataset.spotifyId)
_72
});
_72
})
_72
};
_72
IFrameAPI.createController(element, options, callback);
_72
};
_72
</script>
_72
</body>
_72
</html>