User Tools

Site Tools


push_api

Push API Documentation

License

The use of this 'application programming interface - API' is subject to the creative commons license Attribution-NonCommercial-NoDerivatives 4.0 International License.

About

This API pushes data to your client application. We use it at the moment to push the news off signal and DLS information through the third-party service PubNub. PubNub has more than 50 SDKs for mobile, browser, desktop and server. Please learn more about PubNub directly on the PubNub website.


Developer Authentication

To receive push signals you must have a valid API key. If you don't have one yet:

  1. Request a developer API key by email, please let us know your DIY.fm user name. Important: Please let us explicitly know that you need access to the Push API.

Don't lose your API key, without it you won't be able to crab PubNub pushes. Please see below how it works.


How it works

To receive push data you must have a PubNub subscribe key and you must listen to a certain PubNub channel. The subscribe key is the same for every developer, please use this one: sub-2f430857-f376-11e1-bd7c-41ff068715f9.

News Off

To get access to a certain news off channel, you must construct a string with a structure like this: yourApiKey_pushType_MediumId.

Here's a news off example: 2qg4u0tB1GE103p25G86233H0r0Qvt84_news_off_7

In the example above you get the news off signal for SRF 3 (which has the ID 7).

Supported news media IDs are these:

  • 7 = Radio SRF 3
  • 8 = Radio Svizra Rumantscha
  • 34 = Radio SRF 1
  • 38 = La Première
  • 41 = Rete Uno

Now that you have a valid subscribe key and a valid channel string you can use any PubNub SDK to implement news off functionality into your app. Here is a basic example using the PubNub JavaScript SDK. Feel free to adapt it to any other PubNub SDK.

<script src=http://cdn.pubnub.com/pubnub-3.5.43.min.js ></script>
<script>(function(){
 
    // Init
    var pubnub = PUBNUB.init({
        subscribe_key : 'sub-2f430857-f376-11e1-bd7c-41ff068715f9'
    })
 
    // LISTEN
    pubnub.subscribe({
        channel : "yourApiKey_news_off_7", //listen for the SRF 3 news off push
        message : function(m){ alert(m) }
    })
})();</script>

Push message

There is a simple true in the push message if news are off.


News On

To get access to a certain news on channel you must construct a string with a structure like this: yourApiKey_news_on_MediumId.

Here's a news on example: 2qg4u0tB1GE103p25G86233H0r0Qvt84_news_on_7

In the example above you get the news on signal for SRF 3 (which has the ID 7).

Supported news media IDs are these:

  • 7 = Radio SRF 3
  • 8 = Radio Svizra Rumantscha
  • 34 = Radio SRF 1
  • 38 = La Première
  • 41 = Rete Uno

With a valid subscribe key and a valid channel string you can use any PubNub SDK to implement push functionality into your app. Here is a basic example using the PubNub JavaScript SDK. Feel free to adapt it to any other PubNub SDK.

<script src=http://cdn.pubnub.com/pubnub-3.5.43.min.js ></script>
<script>(function(){
 
    // Init
    var pubnub = PUBNUB.init({
        subscribe_key : 'sub-2f430857-f376-11e1-bd7c-41ff068715f9'
    })
 
    // LISTEN
    pubnub.subscribe({
        channel : "yourApiKey_news_on_7", //listen for the SRF 3 news on push
        message : function(m){ alert(m) }
    })
})();</script>

Push message

There is a simple true in the push message if news are on.


Traffic Announcement

To get access to a certain traffic announcement channel you must construct a string with a structure like this: yourApiKey_traffic_MediumId.

Here's an example: 2qg4u0tB1GE103p25G86233H0r0Qvt84_traffic_7

In the example above you get the traffic announcement signal for SRF 3 (which has the ID 7).

Supported traffic media IDs are these:

  • 7 = Radio SRF 3
  • 34 = Radio SRF 1

With a valid subscribe key and a valid channel string you can use any PubNub SDK to implement push functionality into your app. Here is a basic example using the PubNub JavaScript SDK. Feel free to adapt it to any other PubNub SDK.

<script src=http://cdn.pubnub.com/pubnub-3.5.43.min.js ></script>
<script>(function(){
 
    // Init
    var pubnub = PUBNUB.init({
        subscribe_key : 'sub-2f430857-f376-11e1-bd7c-41ff068715f9'
    })
 
    // LISTEN
    pubnub.subscribe({
        channel : "yourApiKey_traffic_7", //listen for SRF 3 traffic announcment signal (on or off)
        message : function(m){
            alert(m) // true = traffic on, false = traffic off
       }
    })
})();</script>

DLS

To get access to a certain DLS channel you must construct a string with a structure like this: yourApiKey_dls_MediumId.

Here's a DLS example: 2qg4u0tB1GE103p25G86233H0r0Qvt84_dls_7

In the example above you get DLS information for SRF 3 (which has the ID 7).

With a valid subscribe key and a valid channel string you can use any PubNub SDK to implement push functionality into your app. Here is a basic example using the PubNub JavaScript SDK. Feel free to adapt it to any other PubNub SDK.

<script src=http://cdn.pubnub.com/pubnub-3.5.43.min.js ></script>
<script>(function(){
 
    // Init
    var pubnub = PUBNUB.init({
        subscribe_key : 'sub-2f430857-f376-11e1-bd7c-41ff068715f9'
    })
 
    // LISTEN
    pubnub.subscribe({
        channel : "yourApiKey_dls_7", //listen for SRF 3 DLS info
        message : function(m){ alert(m) }
    })
})();</script>

Push message

In the push message there will be a string like this: ARTIST - TITLE.


Setting Change

Use this to get a push notification if the user changes anything on his/her settings. Subscribe to the channel like this: yourApiKey_setting_change_userId.

Example: 2qg4u0tB1GE103p25G86233H0r0Qvt84_setting_change_3

Response:

  • The program schedule XML like GET player/schedule
  • If the response exceeds the PubNub limit of 1100 characters, a simple “true” will be returned. Please call GET player/schedule in this case to get the schedule update.

Best Practice: Unsubscribe

News Off

The news will always start on every full hour (e.g. 1 o'clock, 2 o'clock, 3 o'clock etc.). Please only listen to the news off signal if the news are on. Use unsubscribe after the news have ended:

PUBNUB.unsubscribe({
    channel : "yourApiKey_news_off_7"
});

And subscribe again when the news start again on the full hour:

pubnub.subscribe({
   channel : "yourApiKey_news_off_7"
})

Like this you help us reduce PubNub traffic (= reduce costs). Thank you!


DLS

Obviously, only live streams will recieve DLS information. If you switch to a podcast or if you switch to another live stream unsubscribe:

PUBNUB.unsubscribe({
    channel : "yourApiKey_dls_7"
});

And subscribe again when the live stream starts playing again:

pubnub.subscribe({
   channel : "yourApiKey_dls_7"
})

Like this you help us reduce PubNub traffic (= reduce costs). Thank you!

push_api.txt · Last modified: 2017/02/24 16:11 (external edit)