Triggering content externally

This functionality is only available in Pro subscriptions.

Apart from triggering content to start at a specific time, you can also configure playlists in a channel to start playing when an HTTP request is received from another system. This opens up all kinds of new and creative ways to dynamically adapt the shown content to current actions and/or circumstances. For instance, you can have a physical device, like a button or motion sensor, set off the playback of specific content. Or you can hook up a service like IFTTT to take input from a plethora of sensors or triggers from external systems and use that to trigger start playing a specific playlist.

Events

It all starts by creating one or more events in your Playr settings with a descriptive name and a unique key. It's these events that you can trigger with an HTTP POST request, using that unique key, like so:

https://www.playr.biz/trigger/my-event-key

Of course we don't want just anybody to be able to trigger this event, so you need to supply your unique API key as an authorization header. You'll find your API key on your Events overview page.

Authorization: Bearer <YOUR API KEY>

Lastly, since you can have multiple screens playing the same content, you need to specify for what screens specifically you like to trigger the event. You do this by supplying the Code of the relevant playback devices in the body of the HTTP request as a JSON structure. Each code is enclosed in quotes and these are separated by commas. The list itself is enclosed in square brackets. So it looks like this:

{ "playback_devices": 
  [ "<CODE OF TARGET PLAYBACK DEVICE>",
    "<CODE OF ANOTHER TARGET PLAYBACK DEVICE>"
  ]
}

Those quotes are important, but the < and > characters should be left out!

The code of the playback device can be found by going to the list of playback devices and clicking on the name of the playback device to see the details.

By the way, you can also leave the entire body of the HTTP request empty. In that case, the event triggers all playback devices that play a channel that responds to that particular event.

Linking playlists to events

The last step is to indicate what content needs to be played when a specific event is triggered. This is done in a channel. Instead of scheduling a playlist in a channel to play continuously or incidentally, you set it to play upon event and then select the relevant event.

Once this is set, as soon as the event is triggered for playback device X, and playback device X is playing this channel, then regular playback is interrupted virtually immediately and the playlist associated with the event will start to play. The playlist will play once and then normal playback will be resumed.

Testing and troubleshooting

Here are some tips for when you want to test and/or troubleshoot this:

• You can easily test an HTTP request with a tool like Postman.
• You will get a 200 response when all of the listed playback devices were triggered successfully.
• You will also get a 200 response when at least one of the listed playback devices were triggered successfully, but this will be accompanied by a response body with an error structure that lists the codes of the playback devices that could not successfully be triggered.
• When you get a 404 response to your HTTP request, either the trigger name is incorrect or none of the playback device codes are correct or have any current content to show.