Megaphone TV Interactive Data API (MIND)

© Copyright Play Megaphone Inc. Not for public distribution.

The Megaphone TV Interactive Data API ("MIND") is Megaphone's official REST data feed for realtime polls. Using MIND, developers can create custom poll-visualizations for any software platform, including broadcast systems such as VizRT and Chyron, web sites, digital signage networks, mobile apps, and desktop apps.

Quick Start

To start using the MIND API, follow these steps:

  1. Login to Megaphone Studio.
  2. In Studio, select your show.
  3. Open Editor > Settings > API Access, and note the following information:
  1. Deployment ID
  2. Authentication Token
  1. Open Director, and advance to a question. Leave Director running in this browser tab while you work.
  2. Send an HTTP GET request to the following URL, with your Authentication token supplied in an HTTP Authentication header and deployment_id replaced with your actual Deployment ID:
    https://mind.megaphonetv.com/1.0/deployments/deployment_id/state?view=screen

    CURL example:
    curl -X GET 'http://mind.megaphonetv.com/1.0/deployments/754/state?view=screen' -H 'Authentication: Token rqoisakjahdri'
  3. MIND will return a JSON object describing your show's current state. If a realtime poll is active, the JSON object will include the poll question (in a scene object) and current votes (in a responses array). See Example MIND State Object, below.
  4. In the programming language of your choice, parse the MIND State Object and display its content as desired.

Example MIND State Object

Example 1 shows a typical JSON State object returned by MIND when a show is currently on a poll question (i.e., is in a scene state). Properties of special note include:

Question text:

state_data.content.scene.content.question.text

Question options ("answers"):

state_data.content.scene.content.answers

Current votes:

state_data.content.responses

Example 1. State Object During a Poll Question (A "Face Off" Scene)

{

  "deployment_id": 754,

  "deployment_key": "xyztv-main-trivia-live",

  "state_data": {

    "state_name": "scene",

    "user_counts": {

      "current": 15,

      "lifetime": 45

    },

    "timing": {

      "remaining": 999724,

      "is_paused": false

    },

    "content": {

      "correct_count": 18,

      "incorrect_count": 0,

      "points": 999,

      "responses": [

        12,

        6

      ],

      "scene": {

        "id": "accb91ba-5b6e-40b0-9990-5814acc435b0",

        "type": "survey",

        "presentation": {

          "screen_product": {

            "id": "55cbc50536623000030c0000",

            "name": "FaceOff"

          },

          "controller_product": {

            "id": "55cbc50536623000030c0000",

            "name": "FaceOff"

          }

        },

        "timing": {

          "main": 999999,

          "result": 999999

        },

        "content": {

          "question": {

            "text": "Do you agree with the President's tax plan?",

            "updatable": true

          },

          "answers": [

            {

              "text": "Yes",

              "media": {

                "screen": {

                  "created": {

                    "at": "2018-03-08T04:13:55.651+00:00",

                    "by": {

                      "id": 10,

                      "username": "colin"

                    }

                  },

                  "deployment_id": 754,

                  "deployment_key": "xyztv-main-trivia-live",

                  "editor_version": "2.9.5",

                  "media_content_type": "image/jpeg",

                  "media_file_name": "icon_yes.jpg",

                  "media_file_size": 17296,

                  "media_fingerprint": "54eaa42459e475ae76b6c3912ea3d327",

                  "media_updated_at": "2018-03-08T04:13:55.551+00:00",

                  "updated": {

                   

                  },

                  "id": "5aa0b883d084150004000057",

                  "uri": "https://mp-ced.s3.amazonaws.com/live/xyztv-main-trivia-live/original/5aa0b883d084150004000057-icon_yes.jpg",

                  "small_uri": "https://mp-ced.s3.amazonaws.com/live/xyztv-main-trivia-live/small/5aa0b883d084150004000057-icon_yes.jpg",

                  "medium_uri": "https://mp-ced.s3.amazonaws.com/live/xyztv-main-trivia-live/medium/5aa0b883d084150004000057-icon_yes.jpg"

                }

              },

              "id": "15641324-922a-4da6-97f2-3eeab3a3712e",

              "correct": false

            },

            {

              "text": "No",

              "media": {

                "screen": {

                  "created": {

                    "at": "2018-03-08T04:13:52.736+00:00",

                    "by": {

                      "id": 10,

                      "username": "colin"

                    }

                  },

                  "deployment_id": 754,

                  "deployment_key": "xyztv-main-trivia-live",

                  "editor_version": "2.9.5",

                  "media_content_type": "image/jpeg",

                  "media_file_name": "icon_no.jpg",

                  "media_file_size": 16008,

                  "media_fingerprint": "d9ded45fb83b8e5bd5340dab1394cb78",

                  "media_updated_at": "2018-03-08T04:13:52.626+00:00",

                  "updated": {

                   

                  },

                  "id": "5aa0b880d084150004000056",

                  "uri": "https://mp-ced.s3.amazonaws.com/dev/xyztv-main-trivia-live/original/5aa0b880d084150004000056-icon_no.jpg",

                  "small_uri": "https://mp-ced.s3.amazonaws.com/dev/xyztv-main-trivia-live/small/5aa0b880d084150004000056-icon_no.jpg",

                  "medium_uri": "https://mp-ced.s3.amazonaws.com/dev/xyztv-main-trivia-live/medium/5aa0b880d084150004000056-icon_no.jpg"

                }

              },

              "id": "8ea7a61b-601d-4457-96fb-f7006252f57a",

              "correct": false

            }

          ],

          "background": {

            "media": {

              "screen": {

                "uri": ""

              }

            }

          },

          "sponsor": {

            "media": {

              "screen": {

                "uri": ""

              },

              "controller": {

                "small": {

                  "uri": ""

                },

                "medium": {

                  "uri": ""

                }

              }

            }

          },

          "show": {

            "media": {

              "screen": {

                "uri": ""

              },

              "controller": {

                "small": {

                  "uri": ""

                },

                "medium": {

                  "uri": ""

                }

              }

            }

          },

          "cta": {

            "text": "",

            "media": {

              "screen": {

                "uri": ""

              }

            },

            "type": "general"

          },

          "foreground": {

            "media": {

              "screen": {

                "uri": ""

              }

            }

          }

        },

        "mixins": [

         

        ]

      }

    }

  },

  "updated_at": "2018-04-10T04:06:27.122+00:00"

}

Simple JavaScript MIND Example

Example 2 demonstrates how to load and parse a Megaphone TV poll in JavaScript. The code displays the following MIND data:

If your Megaphone deployment is not currently running when the example runs, MIND returns an HTTP 404 response, and the code displays nothing.

Example 2. Displaying MIND Data with JavaScript

<!doctype html>

<html>

  <head>

    <title>SimpleMIND - Megaphone TV MIND API Example</title>

    <meta name="viewport" content="width=device-width, initial-scale=1">

  </head>

  <body style="font-family: Helvetica, Arial, sans-serif;">

    <div id="scene-output"></div>

    <div id="json-output"></div>

    <script>

      // Change MIND_URL_GOES_HERE and MIND_TOKEN_GOES_HERE to URL and token provided by Megaphone TV

       var MINDurl = 'MIND_URL_GOES_HERE';

       var MINDtoken = 'MIND_TOKEN_GOES_HERE';

 

      var sceneOutputContainer = document.getElementById('scene-output');

      var JSONsceneOutputContainer = document.getElementById('json-output');

 

      // Retrieve data from the MIND API

      function get() {

        var request = new XMLHttpRequest();

        request.onreadystatechange = function () {

          var parsedJSON;

          if (request.readyState == 4 && request.status == 200) {

            parsedJSON = JSON.parse(request.responseText);

            displayJSON(parsedJSON);

            displaySceneData(parsedJSON);

          }

        };

        request.open("GET", MINDurl, true);

        request.setRequestHeader('Authentication', 'Token ' + MINDtoken);

        request.send(null);

      }

 

      // Output the current scene's content onto the page

      function displaySceneData(MINDData) {

        // If the current state is not a scene or a scene_result, quit

        if (MINDData.state_data.state_name !== "scene"

          && MINDData.state_data.state_name !== "scene_result") {

          return;

        }

 

        // NOTE: When content is not supplied (e.g., no question text),

        //       MIND intentionally omits the corresponding properties in

        //       the state object. The omitted properties will trigger an

        //       exception in the following lines of code. For readability's

        //       sake, this code does not check for missing properties.

 

        // Scene Screen Product

        var screenProductElement = document.createElement("h4");

        var screenProductValueElement = document.createElement("p");

        screenProductElement.innerHTML = 'Scene Screen Product';

        screenProductValueElement.innerHTML =

          MINDData.state_data.content.scene.presentation.screen_product.name;

        sceneOutputContainer.appendChild(screenProductElement);

        sceneOutputContainer.appendChild(screenProductValueElement);

 

        // Time Remaining

        var timeRemainingElement = document.createElement("h4");

        var timeRemainingValueElement = document.createElement("p");

        timeRemainingElement.innerHTML = 'Time Remaining';

        timeRemainingValueElement.innerHTML = MINDData.state_data.timing.remaining;

        sceneOutputContainer.appendChild(timeRemainingElement);

        sceneOutputContainer.appendChild(timeRemainingValueElement);

 

        // Users Online

        var usersOnlineElement = document.createElement("h4");

        var usersOnlineValueElement = document.createElement("p");

        usersOnlineElement.innerHTML = 'Users Now Online';

        usersOnlineValueElement.innerHTML = MINDData.state_data.user_counts.current;

        sceneOutputContainer.appendChild(usersOnlineElement);

        sceneOutputContainer.appendChild(usersOnlineValueElement);

 

        // Question Text

        var questionTextElement = document.createElement("h4");

        var questionTextValueElement = document.createElement("p");

        questionTextElement.innerHTML = 'Question Text';

        questionTextValueElement.innerHTML = MINDData.state_data.content.scene.content.question.text;

        sceneOutputContainer.appendChild(questionTextElement);

        sceneOutputContainer.appendChild(questionTextValueElement);

 

        // Question Image

        var questionImageElement = document.createElement("h4");

        if (MINDData.state_data.content.scene.content.question.media === undefined) {

          var questionImageValueElement = document.createElement("p");

          questionImageValueElement.innerHTML = 'NONE';

        } else {

          var questionImageValueElement = document.createElement("img");

          questionImageValueElement.src =

            MINDData.state_data.content.scene.content.question.media.screen.uri;

        }

        questionImageElement.innerHTML = 'Question Image';

        sceneOutputContainer.appendChild(questionImageElement);

        sceneOutputContainer.appendChild(questionImageValueElement);

 

        // Answers - Text, Image, and Votes

        for (var i = 0; i < MINDData.state_data.content.scene.content.answers.length; i++) {

          // Answer Text

          var answerTextElement = document.createElement("h4");

          var answerTextValueElement = document.createElement("p");

          answerTextElement.innerHTML = 'Answer ' + (i + 1) + ' Text';

          answerTextValueElement.innerHTML = MINDData.state_data.content.scene.content.answers[i].text;

          sceneOutputContainer.appendChild(answerTextElement);

          sceneOutputContainer.appendChild(answerTextValueElement);

 

          // Answer Image

          var answerImageElement = document.createElement("h4");

          if (MINDData.state_data.content.scene.content.answers[i].media === undefined) {

            var answerImageValueElement = document.createElement("p");

            answerImageValueElement.innerHTML = 'NONE';

          } else {

            var answerImageValueElement = document.createElement("img");

            answerImageValueElement.src =

              MINDData.state_data.content.scene.content.answers[i].media.screen.uri;

          }

          answerImageElement.innerHTML = 'Answer ' + (i + 1) + ' Image';

          sceneOutputContainer.appendChild(answerImageElement);

          sceneOutputContainer.appendChild(answerImageValueElement);

 

          // Answer Votes

          var answerVotesElement = document.createElement("h4");

          var answerVotesValueElement = document.createElement("p");

          answerVotesElement.innerHTML = 'Votes for Answer ' + (i + 1);

          answerVotesValueElement.innerHTML = MINDData.state_data.content.responses[i];

          sceneOutputContainer.appendChild(answerVotesElement);

          sceneOutputContainer.appendChild(answerVotesValueElement);

        }

 

        // Sponsor Image

        var sponsorImageElement = document.createElement("h4");

        if (MINDData.state_data.content.scene.content.sponsor.media.screen.uri === '') {

          var sponsorImageValueElement = document.createElement("p");

          sponsorImageValueElement.innerHTML = 'NONE';

        } else {

          var sponsorImageValueElement = document.createElement("img");

          sponsorImageValueElement.src =

            MINDData.state_data.content.scene.content.sponsor.media.screen.uri;

        }

        sponsorImageElement.innerHTML = 'Sponsor Image';

        sceneOutputContainer.appendChild(sponsorImageElement);

        sceneOutputContainer.appendChild(sponsorImageValueElement);

      }

 

      // Output raw JSON onto the page

      function displayJSON(data) {

        var stateDataElement = document.createElement("h4");

        var stateDataValueElement = document.createElement("pre");

        stateDataElement.innerHTML = 'Raw MIND Object';

        stateDataValueElement.innerHTML = JSON.stringify(data, undefined, 2);

        JSONsceneOutputContainer.appendChild(stateDataElement);

        JSONsceneOutputContainer.appendChild(stateDataValueElement);

      }

 

      // This code invokes the get() function when the page loads

      (function () {

        get();

      })();

    </script>

  </body>

</html>