Discovering Events Programmatically

You might want to only show or promote an Experience for a period of time, rather than have it always-on. This page explains integration options available to achieve that behaviour.

Events are one of the core concepts of the platform. Within a Project lives a schedule of Events. An Event is a container in which Elements are created and published at specific points in absolute or relative time. An Element might be a poll question, prediction or other piece of interactive content.

Many Events can be included in a Schedule, running concurrently or sequentially. You may wish to programmatically discover and trigger the display of specific Events as part of a custom integration with your product - for example if you want to surface a game that is due to start soon. Or if there is a trivia challenge scheduled for lunchtime.

The content creator will create a new Event within Studio and schedule it for a specific time. You may want your application to automatically find out from the Platform when those Events are scheduled, and open them up at the right time dynamically.

Discover Events by polling the feed

You can also discover events via a feed which is associated with your Project. First, you'll need to obtain the public listings feed URL from Studio, which is unique to your Project. The URL has the following structure:

https://<static host>/projects/<prefix>/<project GUID>/listings.json

Where <static host> is unique to your instance of the Platform (usually, <project GUID> uniquely identifies your Project and <prefix> is the first two characters of the <project GUID>.

This URL points to a JSON file hosted by our CDN and designed to be polled by front end applications at scale. However, we recommend your applications poll this file no more than once every 30 seconds. More frequent polls are discouraged as the CDN cache and cache-control headers in the response will prevent you from getting more frequent content updates.

The JSON object returned will contain an events node, which is an array of Event-specific objects. Each object has the following structure (some fields excluded for simplicity):

    id: "f5e155d6-8d6a-46b4-8e39-0dc016418ba9",
    name: "Event name",
    start_at: 1636974027,
    start_at_iso: "2021-11-15T11:00:27Z",
    end_at: 1664971227,
    end_at_iso: "2022-10-05T12:00:27Z",
    started: true,
    duration: 7200,
    digest: "1e5bb5edce7b4f1109fee057038992dcad393d2f"

Most of the fields are self-explanatory, digest contains a hash of all the other fields' values, which can be used to detect changes.

The above information is enough for your front-end code to understand when an Event becomes live and to load the web application dynamically.