Overview

Developers can use the iFrame API to programmatically create and interact with an 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 on your web page that refers to Spotify’s iFrame API script, https://open.spotify.com/embed-podcast/iframe-api/v1. We recommend adding this element somewhere in the <body> element of the page.

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

2. Create an element on your page for the iFrame

Create an HTML element with a unique id attribute on your page. 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:

<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.

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

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. An example can be found below.

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

5. Test your page

At this point, our 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. For my page, I’m going to add an unordered list of my favorite podcast episodes to the page. Each list item has a button with a data attribute that contains the Spotify ID of the episode.

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

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

let callback = (EmbedController) => {
  document.querySelectorAll('ul#episodes > li > button').forEach(
    episode => {
      episode.addEventListener('click', () => {
        // click event handler logic goes here
      });
    })
};

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

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

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 a little better. Let’s resize the Embed by adjusting the options object that we set when creating the controller.

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

I’m also going to add some CSS to the page to style the menu and float it to the left. You can do this by by linking to an external stylesheet or inline on the page using a <style> element. Here’s what my web page 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.

<html>
<head>
<style>
  body {
    font: 0.7rem sans-serif;
  }

  h1 {
    margin:  10px;
  }

  ul#episodes {
    float: left;
    margin:  0 10px;
    padding: 0;
    width: 35%;
  }

  ul#episodes > li {
    list-style-type: none;
  }

  button {
    border-radius:  7px;
    border: 0;
    background: #191414;
    color: #fff;
    padding:  10px;
    margin:  0 0 3px 0;
    width: 100%;
    cursor: pointer;
  }

  button:hover {
    background: #1Db954;
  }


</style>
  </head>
  <body>
    <h1>Pick an episode...</h1>
    <ul id="episodes">
      <li>
        <button data-spotify-id="spotify:episode:7makk4oTQel546B0PZlDM5">
          My Path to Spotify: Women in Engineering
        </button>
      </li>
      <li>
        <button data-spotify-id="spotify:episode:43cbJh4ccRD7lzM2730YK3">
          What is Backstage?
        </button>
      </li>
      <li>
        <button data-spotify-id="spotify:episode:6I3ZzCxRhRkNqnQNo8AZPV">
          Introducing Nerd Out@Spotify
        </button>
      </li>
    </ul>

    <div id="embed-iframe"></div>
    <script src="https://open.spotify.com/embed-podcast/iframe-api/v1" async>
    </script>
    <script type="text/javascript">
      window.onSpotifyIframeApiReady = (IFrameAPI) => {
        let element = document.getElementById('embed-iframe');
        let options = {
            width: '60%',
            height: '200',
            uri: 'spotify:episode:7makk4oTQel546B0PZlDM5'
          };
        let callback = (EmbedController) => {
          document.querySelectorAll('ul#episodes > li > button').forEach(
            episode => {
              episode.addEventListener('click', () => {
                EmbedController.loadUri(episode.dataset.spotifyId)
              });
            })
        };
        IFrameAPI.createController(element, options, callback);
      };
    </script>
  </body>
</html>