• Authentication
• Available Endpoints
  • Device information endpoint
• Requests proxy / caching proxy
  • Caching:
• Widget storage
  • Saving data
  • Retrieving data
  • Listing available keys
  • Deleting Data
  • Deleting All Data (for the specific widget instance)

The player offers an HTTP API that custom HTML widgets can use. It provides information about the player and allows requests proxying, caching, and widget storage.

The HTTP server is available at the following URL:

Keep in mind that the server only serves local connections, and it doesn’t bind to any public interfaces of the player.

Authentication

When a widget is launched, it is provisioned with an access token that can be used when authenticating with the HTTP server. This can be retrieved from init_widget hook function:

function init_widget(config){
	auth_token = config.player_params['auth_token']
}

When making requests to the HTTP API, provide an Authorization header that has the value “widget <token> ” where <token> is the token received from the configuration passed to the init_widget hook as seen above.

For more information for the custom widget, hook functions check our HTML Widget API .

Available Endpoints

Device information endpoint

This endpoint provides basic information for the player.

Available Methods : GET

/device : Returns information for the specific player. A JSON object containing the ID, Name, and Location of the player. Example: {“id”: 12345, “location”: [40.4280106, -3.6990943], “name”: “test device”}

/device/name : Returns the player’s name as a JSON string. Example: “test device”

/device/id : Returns the player’s ID as a JSON integer. Example: 12345

/device/location : Returns the player’s locations as a JSON array containing two floats (the latitude and the longitude). Example response: [40.4280106, -3.6990943]

Requests proxy / caching proxy

This endpoint allows you to proxy requests via the local HTTP server when calling an external API from a custom widget. The endpoint offers a mechanism to cache the responses from the external server. This can be quite useful when you have custom widgets in playlists, as this can reduce the requests to your external server and also simplify your widget’s code. It also provides a way for widgets to keep working correctly (even with stale data) if the player is unable to access the Internet or your API.

Available Methods : POST

Path : /request

Request Body : A JSON object containing:

• url : The url to be requested
• method : The HTTP method that will be used when requesting the url
• headers : A JSON object with any headers to be used when requesting the url (can be omitted)
• body : The body to be provided to the request (can be omitted). Only UTF-8 data are allowed in this field.
• b64_body : If you need to pass arbitrary binary data as the body for your request, you can use b64_body . Just make sure your data is first encoded to Base64.
• cache : The number of seconds that the response should be cached. Any subsequent requests will be served the same data during this time-frame. If you don’t need your requests to be cached, you can just omit this option or set it to 0.

Caching:

When the cache option is provided, the proxy will cache any GET requests for the specified time. Any subsequent requests to the same url with the same headers , will be served from the cache and will not reach the final server. When a cached response is served, a response header “X-Cached-Date” provides the Date that the response was originally cached. If the cache time-frame passes, the proxy will try to reach the final server to get a fresh response. The proxy will serve the new data and cache it again if fresh data is received. If the final server cannot be reached or a non 2XX response is received, the old stale data is served. A response header “X-Stale” (with value “true”) is sent to denote the stale data.

Caching allows minimizing the requests to the final server when your widget is reloaded multiple times. The typical case is when the custom widget is in a playlist. The stale data feature allows your widget to continue working even when the player is offline or unable to reach the final server.

The cache is kept in memory and will be automatically released when it is not used anymore. If you need persistent storage that can survive across reboot, check the Widget storage endpoint below.

Widget storage

This endpoint provides simple key-value storage for your custom widget. It can support any Content-Type. The storage is persistent and will survive across reboots. Each widget instance is able to access its own data only.

Saving data

Method : POST

Path : /storage/<key>

Body : <your_data>

Response code : 201

Create or update the specific <key> . Make sure that you provide a Content-Type header to denote the type of <your_data> .

Retrieving data

Method : GET

Path : /storage/<key>

Response code : 200 or 404 if <key> is not found

Get the specified <key> from the widget storage. The Content-Type that was specified when previously creating the <key> will be available in the Content-Type header.

Listing available keys

Method : GET

Path : /storage/

Response code : 200 or 404 if there are no keys in storage.

Get a list of the available keys in the storage.

Deleting Data

Method : DELETE

Path : /storage/<key>

Response code : 200 or 404 if <key> is not found

Delete the specified <key> from the widget storage.

Deleting All Data (for the specific widget instance)

Method : DELETE

Path : /storage/

Response code : 200

Delete all keys from the widget storage.