Table of Contents
Intro
The player offers an HTTP API that custom HTML Apps can use. It provides information about the player and allows requests for proxying, caching, and app storage.
The HTTP server is available at the following URL:
Remember that the server only serves local connections and doesn’t bind to any public interfaces of the player.
Authentication
When an app is launched, it is provisioned with an access token to authenticate with the HTTP server. This can be retrieved from the 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 on the custom app hook functions, check our HTML App 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 player’s ID, Name, and Location. 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 app. The endpoint offers a mechanism to cache the responses from the external server. This can be quite useful when you have custom apps in playlists, as this can reduce the requests to your external server and simplify your app’s code. It also allows apps to keep working correctly (even with stale data) if the player cannot 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 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 app is reloaded multiple times. The typical case is when the custom app is in a playlist. The stale data feature allows your app 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 unused. If you need persistent storage that can survive across reboots, check the App storage endpoint below.
App storage
This endpoint provides simple key-value storage for your custom app. It can support any Content-Type. The storage is persistent and will survive across reboots. Each app instance can access its own data only.
Saving data
Method: POST
Path : /storage/<key>
Body : <your_data>
Response code : 201
Create or update the specific <key> . Ensure 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 app 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 app storage.
Deleting All Data (for the specific app instance)
Method : DELETE
Path : /storage/
Response code : 200
Delete all keys from the app storage.