Web integration

⚙️ Web integration
1

Web integration means putting dynamic content from Spinitron in pages of your web site, for example

  • put on the now-playing spin somewhere on your front page
  • display the 5 most recent spins in a sidebar
  • list the next 3 programs coming up
  • display a complete program schedule
  • show DJ profiles

Resources

Resources for web developers that we provide

Also, Radio Rethink’s AirPocket is a web audio player that integrates with Spinitron to display playlist and schedule information. It’s an excellent player regardless of the Spinitron integration.

Techniques

Spinitron supports three techniques to incorporate such data from Spinitron into your web pages

  • Custom layout
  • iframes
  • JavaScript widget
  • API

They each have their own characteristics and their own pros and cons relative to what you want to achieve.

Custom layout

With this feature you save the page layout and styles of your web site in Spinitron, which uses them to generate public pages that look and behave like yours. This allows seamless navigation from your pages to spinitron.com, around the pages on spinitron.com, and back to your pages. Unless the visitor is paying very close attention to technical details, they are unlikely to notice that the Spinitron public page are not actually yours.

Check out this demo https://www.testradio.org/ and read the first paragraph.

iframes

<iframe> is the standard HTML Inline Frame element. You use it to carve out a block on your page inside of which you embed another web page. You can make the embedded page look like it’s part of your page to achieve a pleasing appearance by applying a custom stylesheet to the iframe.

The iframe provides a nested browsing context. When a user clicks a link in the iframe, the linked page loads in the iframe, not in the main browser page. This can be confusing if you don’t plan for it but it can also be put to good use.

Iframes are easy to use and you can put anything in them. For example, you can put your Spinitron landing page in an iframe (hiding the station heading block with style rules) and the visitor to your site can browse all your Spinitron public pages without leaving your web site. Or you can put the program schedule in an iframe and the visitor can interact with it, browsing forwards and back, viewing past playlists and show pages. KZSC provides a nice example.

Spinitron also offers three iframe widgets: now playing, current playlist, and upcoming shows. They are special web pages designed for use only in iframes. They provide the same content as the three JavaScript widgets (see below) but wrapped in HTML documents and simple page layouts.

The height of an iframe does not adjust to its content. Its height is controlled entirely by the containing page and its stylesheet and is independent how much space the embedded page consumes. Sometimes you can fit an iframe nicely to its contents but other times you may end up with blank space if the embedded page is short or overflow if it is long, relative to the iframe’s height.

You cannot control or interact with the page in the iframe from the containing page. Stylesheets and JavaScript in the containing page don’t affect the embedded page. So to control the appearance of the content you must edit a stylesheet that’s stored in Spinitron (Admin: Station settings: Custom stylesheet).

JavaScript widget

Spinitron provides JavaScript widgets that you can place in your web pages. When a visitor to your site loads a page from your web site, the visitor’s browser runs our JavaScript, which loads a chunk of HTML from Spinitron into the HTML of your web page. After the load is complete, the browser contains your web page, loaded from your web server, and part of that page there is the HTML loaded from the spinitron.com web server.

The content from Spinitron becomes a part of your web page. So you can control the embedded content with your stylesheets and JavaScripts. Moreover, the Spinitron content flows into your page, which means it takes up as much space as it needs, according to context and your stylesheets. These features can make JavaScript widgets easier to use than iframes.

Otoh, it’s not so easy to incorporate all Spinitron content using JavaScript widgets. Only three widgets are provided: now playing, current playlist, and upcoming shows. The program schedule is interactive and not available as a JavaScript widget.

Additionally, in contrast to iframes, navigation uses the browser’s main window. When a visitor clicks a link in the Spinitron content, the linked page replaces your web page, and the linked page won’t be one of yours since Spinitron cannot put links to your pages in automatically generated content. So navigation can be confusing if you don’t plan for it but it can also be put to good use.

API

The Spinitron API provides access to data in your database in Spinitron. When you use this service, Spinitron sends back data values that describe playlists, spins, DJs and shows. The responses from Spinitron are formatted in JSON, which is a data-exchange format, not as HTML as in iframes or JavaScript widgets. So while you only need to understand HTML and CSS to use iframes and widgets, you need to write a computer program to use the API.

So the API provides complete flexibility in how you structure and format content from Spinitron in your web pages, it requires a commitment to scripting dynamic pages using a programming language such as PHP, Python, JavaScript, ASP.NET and so on. Widgets and iframes are easy to use but you are stuck with the web pages and page fragments that Spinitron offers. With the API you can get the underlying data, a bit like querying the database, and do with it whatever you need.

Tutorial guides

Custom layout

Using iframes

Refer also to the example web pages that include the parameter reference guides for each widget.

You need to

  1. write an <iframe> HTML tag somewhere in your web page,
  2. position and size the iframe using your stylesheets, and
  3. style the iframe contents using a stylesheet stored in Spinitron (Admin: Station settings: Custom stylesheet).

The <iframe> tag takes this form

<iframe src="url"></iframe>

in which the url is that of one of your Spinitron public pages or one of the widgets. MDN has a good reference for iframes. You can specify the width and height of the iframe block in attributes of the tag or in your stylesheet. You can give the iframe tag class and/or id attributes. For the music player to work inside the iframe, you may need to use the allow attribute to specify a feature policy, e.g. allow="encrypted-media".

To embed your station landing page on spinitron.com, i.e. the page displaying current playlist or show, upcoming shows, and recent playlists, the URL has the form https://spinitron.com/STATIONID/. Find the URL by browsing to the page and copy-pasting the page’s URL. For example, WZBC Newton, Boston College Radio would use an iframe tag

<iframe src="https://spinitron.com/WZBC/"></iframe>

The calendar is embedded with (again using WZBC as example)

<iframe src="https://spinitron.com/WZBC/calendar"></iframe>

DJ and show pages, should you want to embed them, require the numerical ID of the DJ or show, which you can find by browsing to the page and copy-pasting the URL. For example

<iframe src="https://spinitron.com/WZBC/dj/3276/TJ-Connelly"></iframe>
<iframe src="https://spinitron.com/WZBC/show/4450/No-Promotional-Intent"></iframe>

The slug after the the ID part of the URL is not required, e.g. these load the same pages

<iframe src="https://spinitron.com/WZBC/dj/3276"></iframe>
<iframe src="https://spinitron.com/WZBC/show/4450"></iframe>

but including the slug reduces page load time since Spinitron redirects to the URL with the slug.

For the widgets, see the reference/example pages for their URLs

Stying the iframe and its content

First you need to locate the <iframe> tag in a suitable place in the page’s HTML. Next you can apply styles to the iframe (but not its content, see below) using the your website’s stylesheets (giving the <iframe> tag a class or id attribute may be useful) or you can use a style attribute in the <iframe> tag. To control the width and height of the iframe you can use style rules in the stylesheet, or in the style attribute or you can give the <iframe> tag width and/or height attributes.

<iframe class="my-iframe" src="https://spinitron.com/WZBC/"></iframe>
<iframe id="this-iframe" src="https://spinitron.com/WZBC/"></iframe>
<iframe style="border: none; width:100%; height: 10rem" src="https://spinitron.com/WZBC/"></iframe>
<iframe width="600" src="https://spinitron.com/WZBC/"></iframe>

To control the appearance of the iframe content, store style rules in Spinitron (Admin: Station settings: Custom stylesheet). This includes removing parts of the page using display: none. For example

/* Change the text and background colors */
body.public {
    color: chartreuse;
    background: chocolate;
}

/* Change the color of blocks in the calendar according to show category */
.spin-cal .category-music {
    background-color: #ff7400 !important;
}
.spin-cal .category-news {
    background-color: #269926 !important;
}

/* Hide the station heading block */
.view-page .head.station {
    display: none;
}

Using the css parameter

You can also apply styles to iframe content by adding a query parameter css to the iframe’s src URL. Set the value of css to either the URL of an external style sheet or to inline style rules. Query parameters must be URL-encoded. This jsfiddle shows examples of both Edit fiddle - JSFiddle - Code Playground

Put style rules that affect the appearance of the iframe itself (it’s size, position, border, etc.) in the containing page’s style sheets. But to modify the appearance of its content you must save style rules in Spinitron or provide them using the css parameter, either as a URL to a style sheet or encoded into the parameter’s value.

bodyclass and other query parameters

To style the iframe content you save style rules in Spinitron (Admin: Station settings: Custom style sheet). However, styles saved there appear in all public and member Spinitron pages for your station. To apply styles to only certain iframes, use the bodyclass query parameters in the URL to add a class attribute value to the <body> tag of the page. For example

<iframe src="https://spinitron.com/WZBC/?bodyclass=my-iframe"></iframe>

causes the page in the iframe to have a <body> tag like this

<body class="public my-iframe">

Now you can save styles in Spinitron that only apply to iframes that have ?bodyclass=my-iframe in the src URL. For example

body.my-iframe .view-page .head.station {
    display: none;
}

hides the station heading block.

Other query parameters enable and disable special features of playlist views. These can be 0 to disable the feature or 1 to enable it. The default for each is 1 so you only need to use these query parameters if you need to disable features.

To disable Use query parameter
Share to Twitter/FB links sharing=0
Merchandising links (Apple, Amazon, Spotify) merch=0
Cover art cover=0
The audio player player=0

For example

<iframe src="https://spinitron.com/WZBC/?sharing=0&player=1&cover=1&merch=0"></iframe>

See also now playing.

Using JavaScript widgets

To get started, copy-paste the example HTML from one of the three widget example pages

to (a development version of) your web site and modify it according to your needs.

Set the data-station attribute value to your station’s ID (name) in Spinitron. It’s the same ID that appears in the URLs of all your station’s public pages in Spinitron.

For example, WZBC Newton, Boston College Radio’s ID is WZBC, their Spinitron public pages all start with

https://spinitron.com/WZBC/

and in widgets they would use data-station="WZBC", e.g.

<div data-station="WZBC" data-action="now-playing-v2" class="spinitron-js-widget"></div>
<script async src="//spinitron.com/static/js/widget.js"></script>

Use the data-action attribute in the <iframe> tag to choose the widget you want

Widget Use attribute
Now playing data-action="now-playing-v2"
Current playlist data-action="current-playlist"
Upcoming shows data-action="upcoming-shows"

Widget options

The widgets have the following options that can be set using data- attributes. See the examples for more details.

Current playlist has no options.

Upcoming shows has one option to specify the number of upcoming shows to display, e.g. data-count="3".

Now-playing has an option to set the number of recent spins to display, e.g. data-num="3". It also has four options to disable/enable interactive widget features

To disable Use attribute
Twitter/FB sharing links data-sharing="0"
Merchandising links (Apple, Amazon, Spotify) data-merch="0"
Cover art data-cover="0"
The audio player data-player="0"

The default for all four is "1" meaning enabled so you don’t need to set that. Each of these features adds JavaScript to your web page to enable the interactivity of the features.

Styling widgets

The now-playing widget comes with a minimal set of style rules to lay out the elements. The other two widgets come with no style rules at all. You control widget appearance (including hiding the elements you don’t need) in your own website’s stylesheets. Style rules saved in the custom stylesheet in Spinitron don’t affect widget appearance (they affect iframes, public and member pages).

See the examples web site and its stylesheet for ideas on styling. Use your browser’s development tools to explore and experiment.

Using the Spinitron API

The Spinitron Application Programmers’ Interface (API) is a protocol for fetching data from Spinitron that you can incorporate into a web or mobile app. This allows you to get whatever live data from Spinitron you need and to use it however you want. So while the API provides more flexibility than iframes or widgets, using it means you are coding an app.

If you have some competence in coding web or mobile apps then incorporating the Spinitron API shouldn’t be especially difficult. It uses current REST/JSON conventions so if you have experience with that sort of thing then the Spinitron API should present no problems. Relative to many APIs, ours is simple, so if you have basic web app coding chops but no experience with REST/JSON then our API might be a useful learning opportunity.

API reference has the technical specs.

Client authentication

You need to authenticate using an API key. This is found in Spinitron in the automation & API control panel. An API key is 24 random characters. In the examples below we use YOURAPIKEY, for which you would substitute your API key.

Present the API key either in the access-token query parameter or using HTTP Bearer Authorization (preferred) with an HTTP header like this

Authorization: Bearer YOURAPIKEY

Examples

We have a demo web site that shows how the API can be used in PHP. It has zero dependencies and is very small. The demo web site’s front page explains how it works and the code is easy to follow.

You can see the API in action a web browser. For example, to fetch recent spins try

https://spinitron.com/api/spins?access-token=YOURAPIKEY

You can filter items by date/time range, by show and by DJ. See the API reference for all the options.

On the command line using cURL

curl 'https://spinitron.com/api/spins?access-token=YOURAPIKEY'

The same but using HTTP Bearer Authorization

curl -H 'Authorization: Bearer YOURAPIKEY' 'https://spinitron.com/api/spins'

In PHP try

<?php
print_r(json_decode(file_get_contents(
    'https://spinitron.com/api/spins?access-token=YOURAPIKEY')));

If you have a tutorial example to contribute, put it in a Gist and email me the link. Maybe I can use it here.

Terms of service for Spinitron API

Two rules that we hope you will follow in your use of the Spinitron API can impact design of your app.

First, as a client of Spinitron you have an API key that allows access to the API. You may not delegate your access to third parties except for development purposes. In particular, you may not delegate your access to clients of your web or mobile apps. For example, a web or mobile client of yours may fetch data from your servers but they may not use your API key to access the Spinitron API. In other words, don’t build Spinitron API clients into your client scripts or mobile apps.

Second, you should use a cache in the implementation of your web servers or mobile app back-end servers. For example, say you display part of the program schedule on a certain web page. It’s not ok if for every request of that page from visitors to your site, your server makes a request to the Spinitron API. The program schedule doesn’t change rapidly so you can assume that data you fetched a minute ago is still valid. So you should cache data you fetch from Spinitron for a while in case you need the same info again soon. Cacheing is good for your website visitors (faster page loads), reduces load on your and Spinitron’s servers, reduces Internet traffic (and therefore even reduces energy waste a little). How you implement the cache is up to you. Good cache implementations take into account the specific design of the app and how users are expected to behave.

1 Like