Skip to main content

Event Engine State API

Brainsonic Live is relying on an in-house application called Event Engine. For each digital event, an Event Engine instance is created.

This API allows third party applications to get information about an Event Engine instance configuration and state.

The access to this API may incur additional charges
To obtain an API key and secret get in touch with your Brainsonic Live representative

We assume that this third party application is split into a frontend application that is executed on client environment and a backend application that runs on a server.

This information is provided thanks to two requests :

  • getStateURL intends to be requested from a backend application. This returns the endpoint URL that frontend application will need to request. 
  • getState allows the frontend application to request Event Engine instance state every 5s.
  1. The frontend application get the State URL from the backend application
  2. The backend application get the Event Engine instance state URL
    • Carries a bearer token. JWT HS256 format,
    • The token is signed with a secret (API key)
    • Payload contains a service ID (aud), a  client ID (iss) and an expiration date (exp)
    • TTL range = 30s - 60s
    • To be cached on backend for 15 minutes
  3. Every 5 seconds, the frontend application pull the Event Engine instance state
    • Response is cached for 5 seconds

Exemple use case

  1. Frontend application request the State URL to backend application (request 1)
  2. If the backend application obtained the State URL more than 15 minutes ago then it needs to be requested again (request 2).
    There is no need to maintain a state on the backend server. A 15 minutes cache on request 1 is enough.
  3. Frontend application uses the State URL to pull Event Engine instance state every 5 seconds (request 3)
  4. Frontend application requests a new State URL to the backend application every 15 minutes.


get State URL

Success response
  • stateUrl string URL that need to be requested by frontend application
requete Method GET
requete Header bearer:<JWT>
reponse Cache: no-cache
response Statuses
  • Success 200
  • Unauthorized Status 401
  • Error Status 400
Properties

The token carried by the request is a Json Web Token (JWT) encrypted with a shared secret. Secret is shared between Event Engine and the third party backend application

  • alg: HS256
  • iss: <your site/application ID>
  • aud: <service ID>
  • exp: 30s or 60s


get Sate

Success response
  • playerState string : prelive | live | postlive | interruption | off
  • playerManifest string HLS URL
  • countdown object Countdown properties
    • visible boolean : true | false 
    • end unix timestamp : countdown end time
    • serverTime unix timestamp server current time
requete Method GET
response Cache 5s
response Status
Response statuses
  • Success 200
  • Unauthorized Status 401
  • Error Status 400


Limitations

get State URL 
  • Hit/s = 1
  • Maximum Hit/minute = 4
Back to top