Embedding the Widget
In this guide:
- What’s a Widget?
- Two ways to embed the widget
- Embed via a tiny JS loader
- Directly embedding an iFrame
- Widget API
- Widget on WordPress
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.
Two ways to embed the widget
There are two different ways to embed the widget:
- Using a tiny JS loader (recommended)
- 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.
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"]