LogoLogo
DocsUse CasesCreator GuideIntegration Guide
  • Introduction
  • Why Monterosa?
  • Platform Buyer FAQ
  • Engagement Use Cases
    • Event Centres
    • Prediction Games
    • Voting
    • Trivia Challenges
    • Competitions & Sweepstakes
    • Sports Data Visualisation
    • Native Apps
    • Global Replication
  • Core Platform Concepts
    • Platform Components
    • App Settings
    • Schedule & Events
    • Timeline
    • Elements
    • Extensions
    • EnMasse Mesh
  • 🎨Creator Guide
    • Welcome
      • Getting an Account
    • Spaces
      • Projects
        • Events
          • Event Templates
          • Event Settings
          • Timeline
            • Elements
            • OpenAI Integration
            • Live Stats
            • Preview
            • Embedding
              • Embedding an Element
          • Analytics
        • Project Settings
          • Localisation
          • Experience URL
          • Content Creation Limits
        • App Settings
        • Activity Log
      • Content
        • Asset Library
        • Automation
          • 🔃Bulk Content Uploader
          • ⚡Live Data Connector
      • Setup
        • Space Settings
        • Apps
        • Integrations
          • Opta Graphics
          • Tagboard
        • Extensions
          • Identify
          • Gamify
          • Forms
          • Geo-Verify
          • Content Bridge
          • Vote Verification
    • Experiences
      • Experience Creator
        • Customising your UI
        • Retrieving Event URLs
    • Team
      • Two-Factor Authentication
      • Setting Up SSO to log in the Monterosa platform
      • User Roles
    • Scaling & Capacity
    • Creator FAQs
  • 🚀Integration Guide
    • Overview
    • Standalone Pages
    • Web Page Embedding
      • Hosting an Experience on your domain
      • Auto-resizing embedded Experiences
    • Native App Embedding
    • Embed using the SDK
    • Discovering Events Programmatically
    • Audience Profiles
      • Audience Profiles Dataset Reference
        • Users dataset
        • Projects dataset
        • Events dataset
        • Elements dataset
        • Interactions dataset
        • Leaderboard (Event) dataset
        • Leagues dataset
        • Form entries dataset
      • Monterosa Identifiers
    • Integrating IAM & SSO
      • Simple integration with SDK & JWT
        • Advanced SDK integration
      • JWT based SSO integration
      • Ad-hoc SSO integration
      • SSO Integration guidelines
    • Consent Management integration
      • Client-Side Data Storage Explained
    • Analytics integration
    • Integration FAQs
  • 📱FanKit
    • Overview
    • How it works
    • Elements
      • Polls & Voting
        • Brand Survey
        • Poll
        • Reaction Rater
        • Ladder Poll
        • Swing Poll
        • Smash Rater
        • Category Wrapper
        • Category Vote
        • Standalone Vote
        • Team Selector
      • Predictors
        • Predictor
        • Sweepstake
        • Number Predictor
        • Podium Predictor
        • Score Predictor
        • Score Predictor (High)
        • Player Predictor
      • Trivia
        • Trivia
        • Free Type Trivia
        • Ladder Trivia
        • Sorting Trivia
        • Word Trivia
        • Video Trivia
        • Number Trivia
      • Editorial & Media
        • Article
        • External Article
        • Commentary
        • Gallery
        • Image
        • Video
        • Video Carousel
        • Shareable URL
        • Social Embed
        • Form
        • Element Carousel
        • Match Event
        • Substitution
        • Goal
        • Time Event
      • Quiz
        • Quiz Wrapper
        • Quiz Question
      • Series Prediction
        • Series Wrapper
        • Series Score Predictor
        • Series Predictor
        • Series Number Predictor
        • Series Player Predictor
      • Multi Rater
        • Ratings Wrapper
        • Ratings Slider
      • Sports Statistics
        • Opta Widget
        • Stat Callout
        • Stat Comparison
      • Gamification
        • Scoreboard (Event)
        • Scoreboard (Round)
        • Leaderboard (Project)
        • Leaderboard (Event)
        • Leaderboard (Round)
        • Leaderboard (Group)
    • Tips, tricks, tutorials & guides
      • Advanced CSS Overrides
      • Using points and leaderboards
      • Content containers
    • Display Modes
    • Converters
      • Access Gate
      • Form
      • Cards
      • Share Image
      • Featured Links
      • Sponsors
      • Promo Banner
      • Google Ads
    • Localisation
    • Supported Browsers
    • Release Notes
  • 👣DEVELOPER GUIDE
    • Overview
    • Platform Terminology
    • Interaction SDK
      • Download & Initialise the SDK
      • Supported Devices & Operating Systems
      • Roadmap
      • Release Notes
        • React Native
          • v0.2.2
        • JavaScript
          • v0.16.16
          • v0.16.15
          • v0.16.14
          • v0.16.13
          • v0.16.12
          • v0.16.11
        • iOS
          • v0.16.12
          • v0.16.11
        • Android
          • v0.16.13
      • SDK FAQs
    • Embedding Apps
      • Static Embedding
      • Dynamic Embedding
        • Web Behaviours
        • iOS Behaviours
        • Android Behaviours
        • Preloading
        • Caching Content
        • Shared Storage
      • Configure your app
      • Communicate with embedded apps
      • Video Stream Sync
      • React Native
        • Events in React Native SDK
      • Integrate with Flutter
    • Building Apps
      • Quick Start Guide
      • How to build your first app
        • Getting started
        • Get your app running locally
        • Install the Interaction SDK
        • Define your App
        • Set up Studio
        • Develop your App
        • Enable Dynamic Configuration
      • Core SDK Functions
        • Getting and displaying Events
        • Managing Elements
        • Reacting to live updates
        • Dynamic runtime configuration
        • Time
        • Localisation
    • Content Automation
      • Discovering Events
      • Connecting to Google Sheets
      • Connecting to Zapier
      • Connecting to Sports Feeds
    • App Specs
      • App Spec Reference
        • Root Spec
        • Elements Spec
        • Project Settings Spec
        • Event Settings Spec
        • Expressions (beta)
        • Data Sources (beta)
        • External data source
        • Field Types
          • Boolean
          • Collection
          • Colour
          • Datetime
          • External
          • File
          • Freetext
          • Image
          • List
          • Number
          • WYSIWYG
        • Field, Field set, Field section
      • Customising App Specs
    • Available APIs
    • Integrating TV Graphics
    • Advanced Topics
      • Listings
      • Accesssing user concurrency values from your app
      • Custom analytics Extension
      • Front-end app communication protocols
      • Multi Vote
      • Reveal answer on vote
  • ⚙️CONTROL API
    • Overview
    • Objects Definitions
    • Element Reference
    • Organisations
      • Get Organisations
      • Get Organisation
      • Create Organisation
      • Update Organisation
      • Delete Organisation
    • Spaces
      • Get Spaces
      • Get Space
      • Create Space
      • Update Space
      • Delete Space
    • Apps
      • Get Apps
      • Get App
      • Create App
      • Reload App
    • App Settings
    • Projects
      • Get Projects
      • Get Project
      • Create Project
      • Update Project
      • Delete Project
    • Events
      • Get Events
      • Get Event
      • Get Event Service Feeds
      • Create Event
      • Create Event From Template
      • Update Event
      • Delete Event
    • Event Templates
      • Get Event Templates
      • Get Event Template
      • Create Event Template
      • Update Event Template
      • Delete Event Template
    • Elements
      • Get Elements
      • Get Element
      • Get Event Template Elements
      • Create Element
      • Update Element
      • Delete Element
    • Assets
      • Get Assets
      • Upload Assets
      • Update Asset
      • Delete Asset
      • Get Asset Media Types
      • Get Asset Uploaders
      • Asset Tags
        • Add Tag to Asset
        • Remove Tag from Asset
    • Tags
      • Get Tags
      • Get Tag
      • Create Tag
      • Update Tag
      • Delete Tag
  • ⚙️REFERENCE
    • Public Feeds
      • Graphics Feed
    • Listings
    • Elements
    • Event History
    • Demographics
    • Identify
    • Gamify
      • Gamification Mechanics
      • Public API
      • Private API
    • Geo-Verify
    • Browser Support
    • Audience API (Preview)
      • Authentication
        • Monterosa Access Token
        • Public client authentication
      • Batched operations
      • Loyalty API
      • Connections API
    • Image Resizing API
  • ⛓️Extensions
    • Overview
    • Instance handshake
    • Project handshake
    • Project delete
    • Tabs
    • Event Tabs
    • Setup
    • Listings notification
    • Elements notification
    • Analytics
    • Assets
    • Event-level feed
    • Webhooks
  • ⚖️COMPLIANCE
    • Data Requests
    • Data Sub-processors
    • Hosting Locations
    • Third party software
    • ISO27001
  • 🗒️RELEASE NOTES
    • Studio
      • v29.0
      • v28.0
      • v27.0
      • v26.0
      • v25.0
    • FanKit
      • v24.41.0
      • 24.42.0 Preview
    • Archive
      • v24 releases 2022-23
Powered by GitBook
On this page
  • Prerequisites
  • Bearer token
  • Project ID and Event ID
  • Voting data feeds in the Control API
  • Mapping data obtained from Monterosa / Interaction Cloud to external voting data
  • Stopping the requests when the Element has closed
  • Rate limits
  • Further information

Was this helpful?

  1. DEVELOPER GUIDE

Integrating TV Graphics

How to feed live data into TV graphics systems

Was this helpful?

An introduction to the topic is available atTV & Streaming Graphics

The platform provides dynamic data which can be fed into TV Graphics to populate real-time visualisations.

This data is available via two core methods:

  1. - this is the recommended method for security, speed and flexibility

  2. - these feeds are served via a CDN and data can be exposed for convenience. However this is a slower and less secure method.

You may also choose to create custom feeds that you make using either of these two methods to generate your own formats. For example, using a Lambda to generate your own endpoint.

This document covers the Control API method.

Note that we often refer to "votes", where this data can relate to any form of user selection such as a prediction, rating or other.

Prerequisites

In order to use to access voting data you will need the following information:

  1. Project ID

  2. Event ID

  3. Bearer token

These instructions assume that you have a Studio user account with at least “Viewer” level access. Log in to Studio and navigate to the Project and Event that you plan to use for voting. Please contact Monterosa at if you need an account creating for this purpose.

Bearer token

See details of how to generate a bearer token for your account here:

Project ID and Event ID

To obtain the Project and Event ID, navigate to the relevant Event in your project, and navigate to Event Settings > Event > Event ID and copy these values.

Voting data feeds in the Control API

The request can be performed using a CURL command like the following:

EVENT_ID=<EVENT_ID> 
TOKEN=<TOKEN>

curl --request GET
--url "https://studio.monterosa.cloud/api/v2/events/$EVENT_ID/elements?include=stats"
--header "Authorization: Bearer $TOKEN"

The result of that GET request will be a JSON object containing all elements metadata and the aggregated vote results. The most relevant fields of which are:

  • data - Includes all the elements data, on each element, we’ll find:

    • attributes.content_type will specify the type of element you retrieved. Make sure it’s value equals vote.

    • attributes.question will contain the JSON data for the question we are asking our users

      • options[X].fields["key"].values.all specifies the textual representation of the option a user votes for. Note that X will be the index used to aggregate its stats in the stats section of the JSON.

  • included - Will contain an array with the stats for each of the elements with matching indexes to that of the data array. This data is only included if you provide the ?include=stats URL query parameter.

    • attributes.aggregated.voters will include the total count of voters

    • attributes.aggregated.votes will include the total count of votes

    • attributes.results[X].votes will include the total count of votes a specific answer option received. E.g. how many votes a candidate on a reality tv show got.

    • attributes.results_are_final will indicate if the voting has concluded

Mapping data obtained from Monterosa / Interaction Cloud to external voting data

Once you have obtained the data you need, and parsed through it to obtain the relevant data, you may need to match the vote statistics to other vote sources to produce a final tally of votes.

Our suggested approach is to match the text used in the question options to the alternatives a vote can have.

The JSON structure can be navigated using a code similar to the following Javascript snippet:

const elements = ...; // The response from the API call

// Map the elements to return for each of them their vote results
elements.data.map((element, index) => {
    // Filter out the elements that are not a vote
    if (element.attributes.content_type !== "vote") return null;

    // Obtain the element id and the key for the question
    const elementId = element.id;
    const questionKey = element.attributes.question.fields.find((field) => field.key === "text").values.all;

    // Fetch options in the element
    const options = element.attributes.question.options;

    // Fetch the keys from the element by selecting the field with key "text"
    // and retrieving the value in "values.all"
    const keys = options.map((option) => {
      return option.fields
        .find((field) => field.key === "text")
        .values
        .all;
    });

    // Fetch vote counts from stats by locating in `included` the stats item with the matching index
    const stats = elements.included[index];
    const votes = stats.attributes.aggregated.results.map(result => result.votes);

    return {
      elementId: elementId,
      key: questionKey,
      results: keys.map((key, index) => {
        return {
          key: key,
          votes: votes[index]
        }
      })
    }
  })
  // Filter out the elements that are not a vote
  .filter(result => result != null);

As a result of the snippet above, you’ll receive a JSON response similar to the following (some data is trimmed down for brevity):

[ 
  { 
    "elementId": "8cbbca06-3f47-4569-b149-634a22ea66ee", 
    "key": "vote 1 key", 
    "results": [ 
    { 
      "key": "vote 1 option 1 key", 
      "votes": 123
    }, 
    { 
      "key": "vote 1 option 2 key", 
      "votes": 456 
    } ] 
  }, 
  { 
    "elementId": "913081dd-3b4b-4696-98f2-202558e8ceac", 
    "key": "vote 2 key", 
    "results": [ 
    { 
      "key": "vote 1 option 1 key", 
      "votes": 789 
    }, 
    { 
      "key": "vote 2 option 2 key", 
      "votes": 963 
    } ] 
   } 
]

Stopping the requests when the Element has closed

We recommend to use the boolean in attributes.results_are_final in the included stats of the JSON obtained to identify if the Element has been closed. If its value is true, then you should stop performing requests to the API so as to avoid wasting resources. If the value is false, continue requesting data by respecting the rate limits as described in the next section.

Rate limits

Although we allow for multiple requests per second, we recommend a latency that matches your expectations on data freshness which will usually be multiple seconds between requests (e.g. every minute).

Further information

Within the Control API, a vote is an Element with content_type: vote. The list of all elements within the vote Event can be obtained by using the REST API call described here -

state will specify the state the element is in. The following page documents which values it can take and their meaning:

Please note that the Control API V2 has rate limits that are

Please contact Monterosa’s support team if you require any further information regarding the implementation of voting integration by sending an email to

👣
Control API
Public feeds
Control API
support@monterosa.co.uk
Control API - Generating a bearer token
Get Elements
Element Resource
described here
support@monterosa.co.uk
Example host and project ID