Embedding the Widget

In this guide:

What’s a Widget?

The widget is a player you can embed in your own website or blog. It basically consists of a HTML snippet you should add to your website that, once executed, replaces a link with the widget. The easiest way to configure the widget and generate the markup to embed is through our CMS but there’s some people who needs to manually generate it: this documentation is for them.

If I Were You

Two ways to embed the widget

There are two different ways to embed the widget:

  1. Using a tiny JS loader (recommended)
  2. Directly embedding an <iframe> tag

Embed via a tiny JS loader

The recommended way to embed the widget is to place one or more HTML anchors <a> in the page, each one with a set of custom data attributes (described below), and a tiny javascript file that parses the widget’s anchors and replace them with the widget itself. This is the recommended way because it’s more flexible and performant compared to the other way and should be used whenever you can embed a JS file in the hosting page.

To embed a widget, you should place an HTML anchor element in your page:

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="user_id=1" data-width="100%" data-height="200px">Listen to my podcast</a>

And a JS script tag right before the end of your </body>:

<script async src="https://widget.spreaker.com/widgets.js"></script>

The anchor accepts some custom data attributes that give you the freedom to configure many aspects of the widget itself.

Attribute Required Description
data-resource Yes The primary episode you do want to display in the widget. It can be a single episode data-resource="episode_id=EPISODE-ID", a show’s latest episode data-resource="show_id=SHOW-ID" or an user’s latest episode data-resource="user_id=USER-ID".
data-width No Widget’s width (can be in % or px).
data-height No Widget’s height (can be in % or px).
data-theme No Widget’s UI theme. Supported themes are: light (default) and dark.
data-cover No HTTPS url of an image to display as widget’s background.
data-playlist No Configures how the widget’s playlist should be built. It can be data-playlist="false" to disable the playlist, data-playlist="user" to display all user’s episodes in the playlist or data-playlist="show" to display all show’s episodes in the playlist. The default behavious depends on data-resource.
data-playlist-continuous No Enables or disables the playlist continuous playback. When true it continuously plays all episodes in the playlist until the end.
data-playlist-autoupdate No Enables or disables the playlist autoupdate, when a new episode is published. This feature is enabled by default.
data-autoplay No Enables or disables the autoplay. When true it automatically starts playing when the widget loads. Autoplay doesn’t work on most mobile browsers. Defaults to false.

IMPORTANT: the anchor must have the attribute class="spreaker-player" otherwise it gets ignored by the loader script, and won’t be replaced with the widget.

Example: share a single episode, without playlist

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="episode_id=9146245" data-width="100%" data-height="200px">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Example: share the latest episode by show, with playlist

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="show_id=1391532" data-width="100%" data-height="200px">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Example: share the latest episode by user, with playlist

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="user_id=8100025" data-width="100%" data-height="200px">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Example: share the latest episode by user, without playlist

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="user_id=8100025" data-width="100%" data-height="200px" data-playlist="false">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Example: share a specific episode, with playlist displaying all show’s episodes

<a class="spreaker-player" href="https://www.spreaker.com" data-resource="episode_id=9146245" data-width="100%" data-height="200px" data-playlist="show">Listen to my podcast</a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

Directly embedding an <iframe>

In some circumstances, it may happen that you want to embed the widget in a page that doesn’t allow to include javascript files. In such cases, you can directly embed the <iframe> in the page:

<iframe src="https://widget.spreaker.com/player?show_id=1391532" width="100%" height="200px" frameborder="0"></iframe>

To configure the widget, you can pass a set of options as query string parameters. The following parameters are supported:

Parameter Required Description
episode_id or show_id or user_id Yes The primary episode you do want to display in the widget. It can be a single episode episode_id=EPISODE-ID, a show’s latest episode show_id=SHOW-ID or an user’s latest episode user_id=USER-ID.
theme No Widget’s UI theme. Supported themes are: light (default) and dark.
cover_image_url No HTTPS url of an image to display as widget’s background.
playlist No Configures how the widget’s playlist should be built. It can be playlist=false to disable the playlist, playlist=user to display all user’s episodes in the playlist or playlist=show to display all show’s episodes in the playlist.
playlist-continuous No Enables or disables the playlist continuous playback. When true it continuously plays all episodes in the playlist until the end.
playlist-autoupdate No Enables or disables the playlist autoupdate, when a new episode is published. This feature is enabled by default.
autoplay No Enables or disables the autoplay. When true it automatically starts playing when the widget loads. Autoplay doesn’t work on most mobile browsers. Defaults to false.

Example: share a single episode, without playlist

<iframe src="https://widget.spreaker.com/player?episode_id=9146245" width="100%" height="200px" frameborder="0"></iframe>

Example: share the latest episode by show, without playlist

<iframe src="https://widget.spreaker.com/player?show_id=1391532&playlist=false" width="100%" height="200px" frameborder="0"></iframe>

 Widget API

If you choose to embed the widget using the tiny JS loader, you will also have a set of javascript API in the hosting page, through which you can control the widget programmatically.

The loader script exposes the SP.getWidget(IFRAME) function to the global scope, that returns an object through which you can control and get the state of the widget. The following methods are provided on the object returned by SP.getWidget():

Method Type Description
play() Sync Plays the current episode.
pause() Sync Pauses the current episode.
seek(POSITION) Sync Seeks the current episode to POSITION (expressed in milliseconds). This method doesn’t change the playback state, so if it was playing it will continue to play, otherwise it will not start to play.
load(EPISODE-ID) Sync Loads a different episode in the widget. The input EPISODE-ID must be an episode already loaded in the playlist.
playPrev() Sync Plays the previous episode in the playlist (if any).
playNext() Sync Plays the next episode in the playlist (if any).
getPosition(CB) Async This method takes in input a callback CB, that will get called with the current playback position, progress and duration: function(position, progress, duration) {}.
getDuration(CB) Async This method takes in input a callback CB, that will get called with the current playback duration: function(duration) {}.
getState(CB) Async This method takes in input a callback CB, that will get called with the current episode and its state: function (episode, state, isPlaying) {}.

Supported browsers: the two-way communication between the hosting page and the Widget has been implemented using MessageChannel. Modern browsers support it, but some old browsers could not be supported. If a method is called successfully it will return true, otherwise false (on unsupported browsers).

Example: play and pause buttons in the hosting page

<a id="my-widget" class="spreaker-player" href="https://www.spreaker.com/show/1391532" data-resource="show_id=1391532" data-width="100%" data-height="300px"></a>
<script async src="https://widget.spreaker.com/widgets.js"></script>

<button id="cmd-play">play()</button>
<button id="cmd-pause">pause()</button>

<script>
    window.onload = function() {
        var widget   = SP.getWidget("my-widget");
        var playBtn  = document.getElementById("cmd-play");
        var pauseBtn = document.getElementById("cmd-pause");

        playBtn.addEventListener("click", function() {
            widget.play();
        });

        pauseBtn.addEventListener("click", function() {
            widget.pause();
        });
    });
</script>

Live example

This live example shows how the Widget API works. Please click the following buttons to give it a try and checkout the page’s sources for more information (it’s pretty straightforward):

Getters output will be printed here.

If I Were You

Widget on WordPress

Spreaker provides a WordPress plugin to easily embed the Spreaker widget in your WordPress blog or website.

It basically adds the support for a shortcode in the form [spreaker type=player ...] to your WordPress, replacing all the shortcodes with the related widget.

The shortcode supports all the attributes supported by the JS loader without the data- prefix. For example, the resource is specified with the resource attribute (instead of data-resource), the background image with cover (instead of data-cover) and so on.

Example: share a single episode, without playlist

[spreaker type=player resource="episode_id=9146245" width="100%" height="200px"]

Example: share the latest episode by show, with playlist

[spreaker type=player resource="show_id=1391532" width="100%" height="200px"]