Graphics Feed

A graphics feed is a data stream that provides real-time information which can be used to create on-screen graphics in various applications such as live broadcasts. This feed is designed to integrate fan engagement Experiences into screen graphics to automatically update and display relevant content based on the provided Element data.

The simplified graphics feed offers a streamlined and user-friendly approach to accessing Element data that aligns with the model of major graphics systems.

To explore use cases, go to TV & Streaming Graphics.

Easy graphics integration

• Sequences data by element

• Places all element data within one node per elements

• Additional data is located in one place under the parent node

Features

• Returns element data including a question, options, custom fields configured by the App Spec, and basic parameters.

• Filtering by the question field value (questionField[KEY]=VALUE query parameter)

• Filtering by the element field value (elementField[KEY]=VALUE query parameter)

• Filtering by element type (type=ELEMENT_TYPE)

• Filtering by element states (elementStates=current,future,past query parameter)

• Selecting elements by position (elementPosition=first or elementPosition=last query parameter)

• Filtering by event ID (eventID=ID query parameter)

• Filtering by event field value (eventField[KEY]=VALUE query parameter)

• Combining filters

How the feed selects an event

When using the Graphics Feed URL, the system determines which event to pull data from based on the parameters you provide. Here is the order of logic:

1. Direct Specification:

   • By ID: Using the eventID=ID parameter is the most direct way to target a specific event.

   • By Field: You can also target a specific event by using the eventField[KEY]=VALUE parameter (e.g., eventField[slug]=live-event-slug).

2. Default Behavior (No Specification):

   • If neither an eventID nor an eventField filter is provided in the URL, the feed will default to the first active event it finds within the project.

Filtering by element states

The elementStates parameter allows you to filter elements based on their lifecycle state:

• current - Elements that are currently active

• future - Elements scheduled to start in the future

• past - Elements that have already ended

You can specify multiple states separated by commas (e.g., elementStates=current,future).

Example:

?elementStates=current

Selecting elements by position

The elementPosition parameter allows you to choose which element to return when multiple elements match your filters:

• first (default) - Returns the first matching element

• last - Returns the last matching element

Example:

?elementStates=current,future&elementPosition=last

Combining filters

All filter parameters can be combined to create precise queries. Make sure that all query parameters are URL-encoded.

Example: Complex filter combining multiple parameters

?elementField[themes]=light
&elementField[pointsThreshold]=100
&type=poll-element
&elementStates=current

Additional Notes

• All query parameter keys and values should be properly URL-encoded

• Multiple state values can be combined: elementStates=current,future,past

• The default elementPosition is first if not specified

• When no filters are applied, the feed returns the first element from the first active event in the project

Example 1

Feed format for a standard Trivia Element

{
  "label": "Question: Who is the all-time leading scorer in NBA history?",
  "type": "trivia-element",
  "question": {
    "label": "Who is the all-time leading scorer in NBA history?",
    "fields": {
      "text": "Who is the all-time leading scorer in NBA history?",
      "imageUrl": "//cdn.example.com/quickfire-quiz-header.png"
    }
  },
  "options": [
    {
      "label": "Lebron James",
      "votes": 0,
      "fields": {
        "text": "Lebron James"
      }
    },
    {
      "label": "Kobe Bryant",
      "votes": 0,
      "fields": {
        "text": "Kobe Bryant"
      }
    },
    {
      "label": "Karl Malone",
      "votes": 0,
      "fields": {
        "text": "Karl Malone"
      }
    }
  ],
  "elementFields": {
    "accessLevel": "public",
    "layout": "stacked",
    "pin": false
  },
  "extra": {
    "start_at": "2023-07-20T12:47:46.000Z",
    "end_at": "2023-07-20T16:47:46.000Z",
    "voters": 0
  }
}

Example 2

Feed format for a Poll Element containing custom fields

  "label": "Have you heard of the new energy drink 'Voltz' that is sponsoring this event?",
  "type": "poll-element",
  "question": {
    "label": "Have you heard of the new energy drink 'Voltz' that is sponsoring this event?",
    "fields": {
      "text": "Have you heard of the new energy drink 'Voltz' that is sponsoring this event?"
    }
  },
  "options": [
    {
      "label": "Yes, I have tried it and love it!",
      "votes": 0,
      "fields": {
        "text": "Yes, I have tried it and love it!"
      }
    },
    {
      "label": "Yes, I have heard of it but haven't tried it yet.",
      "votes": 1,
      "fields": {
        "text": "Yes, I have heard of it but haven't tried it yet."
      }
    },
    {
      "label": "No, I haven't heard of it before.",
      "votes": 0,
      "fields": {
        "text": "No, I haven't heard of it before."
      }
    },
    {
      "label": "No, I don't drink energy drinks.",
      "votes": 0,
      "fields": {
        "text": "No, I don't drink energy drinks."
      }
    }
  ],
  "elementFields": {
    "layout": "stacked",
    "aspectRatio": "16 / 9",
    "gamification_points_correctAnswer": null,
    "themes": "light",
    "enableReactions": false,
    "pin": false,
    "showCountdown": false,
    "selectSound": null,
    "containerId": null,
    "accessLevel": "public",
    "pointsThreshold": 100,
    "enableSponsor": true
  },
  "extra": {
    "start_at": "2023-06-07T09:34:48.000Z",
    "end_at": "2023-07-07T08:35:45.000Z",
    "voters": 1
  }
}

How to access the graphics feed

The feed is available in two places in Studio:

1. Under Project Settings

1. In the embed modal of every Event timeline

Click on the embed icon

Graphics feed URL in the embed modal