Confidential Internal Engineering Documentation. Not for Public Distribution. Copyright Play MegaPhone Inc.

Megaphone TV

Introduction to the MegaScreen API

An introduction to the APIs and protocols behind MegaScreen, Megaphone's on-air graphics application.

Megaphone TV Platform Overview

Megaphone TV's realtime participation platform includes three main software components:

This introduction describes how MegaScreen communicates with Megaphone Realtime Service and maintains application state.

What is MegaScreen?

MegaScreen is a custom-built Adobe Flash application that displays a variety of interactive and broadcast content, including live polls, quizzes, competitions, games, title graphics, and advertising. MegaScreen's content is remotely controlled by Megaphone Realtime Service over a persistent network connection. Megaphone Realtime Service communicates with MegaScreen using a set of client/server protocols referred to collectively as the MegaScreen API. Although MegaScreen is written in ActionScript and runs in Adobe Flash Player, the MegaScreen API itself is language agnostic, allowing new screen clients to be built for other target platforms.

Connecting to Megaphone Realtime Service

MegaScreen's lifecycle starts with a connection to Megaphone Realtime Service. Megaphone Realtime Service's low-level networking layer is provided by an application-development framework named Union Platform. Hence, to connect to Megaphone Realtime Service, MegaScreen first opens a persistent TCP/IP socket connection to Union Server, and performs the Union Client/Server handshake.

The following sections contain MegaScreen client-log excerpts showing the basic steps in the Union Client/Server handshake. For complete details on Union's client setup and Union Platform's messaging protocol, see the following resources:

Send Client Hello

MegaScreen introduces itself to the server in a CLIENT_HELLO (u65) message that includes the client name, description, and supported UPC ("Union Procedure Call") version.

11/20/15 16:04:16.300 UTC-5 DEBUG: [CONNECTION] Sending CLIENT_HELLO: <U><M>u65</M><L><A>Reactor</A><A>Flash Player MAC 11,2,202,228 StandAlone (debug, localTrusted); 3.2.2</A><A>1.10.3</A></L></U>

Note that every transmission sent to Union Server must be terminated by a null character (ASCII 0). Each transmission can contain multiple messages.

Receive Server Hello

If the CLIENT_HELLO succeeds, the server responds with a SERVER_HELLO (u66) message that includes the server version, the client's assigned session ID, the server's supported UPC version, a flag indicating whether the client and server's protocol versions are compatible, the server's affinity address (in this case, none), and the server-affinity duration (in this case, 0).

11/20/15 16:04:16.960 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u66</M><L><A><![CDATA[Union Server 2.1.1 (build 610)]]></A><A>-1318705471ccf95d0a-a071-49c0-81d5-8a024d8d5219</A><A>1.10.3</A><A>true</A><A/><A>0</A></L></U>

Receive Client ID

Once the server has initialized MegaScreen as a connected client, it sends MegaScreen a Union client ID in a CLIENT_METADATA (u29) message.

11/20/15 16:04:16.118 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u29</M><L><A>5583</A></L></U>

Receive Connection-Configuration Information

After the server sends MegaScreen its Union client ID, it then sends a series of CLIENT_ATTR_UPDATE (u8) messages specifying the client's initial global attributes. These attributes are properties of the client maintained by the server, and are used to share information about the client with other clients and clustered server nodes in the network. MegaScreen is expected to store its client attributes locally, and keep them up to date should the server send attribute-change notifications in the future. The initial set of client attributes for MegaScreen includes:

11/20/15 16:04:16.121 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_CT]]></A><A><![CDATA[1448053456170]]></A><A>36</A></L></U>

11/20/15 16:04:16.123 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_IP]]></A><A><![CDATA[174.113.225.247]]></A><A>32</A></L></U>

11/20/15 16:04:16.124 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_GATEWAY_ID]]></A><A><![CDATA[PrimaryNIOGateway]]></A><A>96</A></L></U>

11/20/15 16:04:16.125 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_GATEWAY_TYPE]]></A><A><![CDATA[TCP]]></A><A>96</A></L></U>

11/20/15 16:04:16.126 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_CONNECTION_TYPE]]></A><A><![CDATA[XML/Socket]]></A><A>96</A></L></U>

11/20/15 16:04:16.127 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_CLIENT_TYPE]]></A><A><![CDATA[Reactor]]></A><A>96</A></L></U>

11/20/15 16:04:16.128 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_USERAGENT]]></A><A><![CDATA[Flash Player MAC 11,2,202,228 StandAlone (debug, localTrusted); -1.-1.-1]]></A><A>96</A></L></U>

11/20/15 16:04:16.129 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_UPC_VERSION]]></A><A><![CDATA[1.10.3]]></A><A>96</A></L></U>

11/20/15 16:04:16.130 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_ROLES]]></A><A><![CDATA[0]]></A><A>68</A></L></U>

Receive Client Ready

After MegaScreen has been initialized and sent its global client attributes, it is sent a CLIENT_READY (u63) message, indicating that the server is ready to conduct standard communications.

11/20/15 16:04:16.131 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u63</M><L/></U>

11/20/15 16:04:16.137 UTC-5 INFO:  [REACTOR] Reactor now connected and ready.

Joining the Megaphone TV Deployment

Send Connect Screen

Once MegaScreen has reached the "client ready" state, it can then request a connection to a specific Megaphone TV deployment by sending a CONNECT_SCREEN module message to the MegaphoneServices module. In the CONNECT_SCREEN message payload, MegaScreen sends a serialized "Megaphone Instance" object as a message argument. The Megaphone Instance object must specify:

The Megaphone Instance object may also specify a set of optional details about the venue. Here is an example CONNECT_SCREEN message:

11/20/15 16:04:16.142 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC sent: <U><M>u71</M>

<L>

<A>MegaphoneServices</A>

<A>CONNECT_SCREEN</A>

<A>instance[venue_attributes][country]|</A>

<A>instance[id]|</A>

<A>instance[venue_attributes][partner_id]|</A>

<A>instance[venue_attributes][postal_code]|</A>

<A>instance[venue_key]|2ea4ce505b0a0133ef5c22000ae4063e</A>

<A>instance[venue_attributes][region]|</A>

<A>instance[venue_attributes][locality]|</A>

<A>instance[venue_attributes][lng]|</A>

<A>instance[installation_key]|live</A>

<A>instance[venue_attributes][lat]|</A>

<A>instance[password]|aslkjdfwoeir</A>

<A>instance[venue_attributes][street]|</A>

<A>instance[venue_attributes][metadata]|</A>

<A>instance[deployment_key]|megaphone-news-demo-trivia-news-demo</A>

<A>instance[venue_attributes][name]|Moock Dev Laptop</A>

</L></U>

Receive MegaScreen Attributes

If MegaScreen's CONNECT_SCREEN request succeeds, MegaScreen is officially considered an active "screen instance" in the system, and Megaphone Realtime Service sends MegaScreen the following three client attributes:

11/20/15 16:04:16.636 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[clientType]]></A><A><![CDATA[screen]]></A><A>64</A></L></U>

11/20/15 16:04:16.639 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[INSTANCE_ID]]></A><A><![CDATA[520057]]></A><A>64</A></L></U>

11/20/15 16:04:16.639 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[_UL]]></A><A><![CDATA[1]]></A><A>2</A></L></U>

Note that in MegaScreen documentation, "screen instance" is often abbreviated to just "instance".

Receive Application-Room Data

Megaphone Realtime Service then adds MegaScreen to the list of observers of the application room, and sends MegaScreen two messages about that room: ROOM_SNAPSHOT (u54) and OBSERVED_ROOM (u59). The ROOM_SNAPSHOT message is always empty in MegaScreen's case because MegaScreen's update levels restrict MegaScreen's knowledge of the application room to messages only. The OBSERVED_ROOM message indicates that the application room has been successfully observed.

11/20/15 16:04:16.640 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u54</M><L><A/><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A><A/><A/><A/></L></U>

11/20/15 16:04:16.646 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received:

<U><M>u59</M><L><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A></L></U>

Set Update Levels to Attribute Changes Only

MegaScreen then asks Megaphone Realtime Service to restrict the amount of updates it receives about the application room. This step applies to special client-side-logic applications, which do not occur in Megaphone's massively multiuser participation platform. For the purposes of the MegaScreen API, this step can normally be ignored.

11/20/15 16:04:16.649 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC sent: <U><M>u64</M><L><A>megaphone-news-demo-trivia-news-demo</A><A>1</A></L></U>

Receive Screen Instance Data

MegaScreen then receives an attribute update containing the INSTANCE_DATA for this MegaScreen instance. In practice, MegaScreen ignores most of the content in INSTANCE_DATA, but is expected to store the venue key for use by any subsequent CONNECT_SCREEN calls.

11/20/15 16:04:16.668 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u8</M><L><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A><A>5583</A><A><![CDATA[]]></A><A><![CDATA[INSTANCE_DATA]]></A><A><![CDATA[<?xml version="1.0" encoding="UTF-8"?><instance>  <archived-at type="datetime" nil="true"></archived-at>  <created-at type="datetime">2015-11-20T21:04:16Z</created-at>  <deleted-at type="datetime" nil="true"></deleted-at>  <deployment-id type="integer">522</deployment-id>  <deployment-key>megaphone-news-demo-trivia-news-demo</deployment-key>  <id type="integer">520057</id>  <installation-key>live</installation-key>  <instance-duration type="integer" nil="true"></instance-duration>  <instance-shortcode>95935</instance-shortcode>  <ip>174.113.225.247</ip>  <room>megaphone-news-demo-trivia-news-demo</room>  <screen-duration type="integer" nil="true"></screen-duration>  <state>active</state>  <total-objects type="integer" nil="true"></total-objects>  <updated-at type="datetime">2015-11-20T21:04:16Z</updated-at>  <venue-id type="integer">12466</venue-id>  <deployment>    <active type="boolean">true</active>    <age-gate type="boolean">false</age-gate>    <allow-sms type="boolean">true</allow-sms>    <app-id type="integer">241</app-id>    <archived-at type="datetime" nil="true"></archived-at>    <caller-label-mask type="boolean">true</caller-label-mask>    <caller-number-mask type="boolean">false</caller-number-mask>    <caller-number-mask-string>[Viewer]#[NUMBER]</caller-number-mask-string>    <created-at type="datetime">2015-06-02T20:25:49Z</created-at>    <deleted-at type="datetime" nil="true"></deleted-at>    <description>News Demo</description>    <environment>live</environment>    <expected-callers type="integer" nil="true"></expected-callers>    <force-sms-single-delivery type="boolean">false</force-sms-single-delivery>    <id type="integer">522</id>    <initial-editor-configuration>Default</initial-editor-configuration>    <key>megaphone-news-demo-trivia-news-demo</key>    <max-call-time type="integer">3600</max-call-time>    <max-callers type="integer">20</max-callers>    <max-controllers type="integer">8000</max-controllers>    <max-instances type="integer">30</max-instances>    <meta-data>{"operatorURL": "http://showcase.megaphonecloud.com/news/director"}</meta-data>    <multiscreen type="boolean">true</multiscreen>    <name>News Demo</name>    <password>glwpetlkexjk</password>    <prefix nil="true"></prefix>    <room-timeout type="integer">5</room-timeout>    <screen-timeout type="integer">5</screen-timeout>    <skip-phone-number type="boolean">false</skip-phone-number>    <sms-provider-id type="integer" nil="true"></sms-provider-id>    <sms-provider-params nil="true"></sms-provider-params>    <state>active</state>    <static type="boolean">true</static>    <timeout type="integer">-1</timeout>    <updated-at type="datetime">2015-11-05T19:06:00Z</updated-at>    <validation-gate type="boolean">false</validation-gate>    <validation-gate-button-echo type="boolean">false</validation-gate-button-echo>    <validation-gate-params>21</validation-gate-params>    <validation-pound-submit type="boolean">false</validation-pound-submit>    <installation-key nil="true"></installation-key>    <app>      <allow-blocked-caller-ids type="boolean">true</allow-blocked-caller-ids>      <archived-at type="datetime" nil="true"></archived-at>      <audio-efficient type="boolean">true</audio-efficient>      <audio-framerate type="integer">15</audio-framerate>      <audio-levels type="boolean">false</audio-levels>      <audio-thresh type="integer">0</audio-thresh>      <audio-timeout type="integer">10000</audio-timeout>      <blocked-caller-id-message nil="true"></blocked-caller-id-message>      <button-press type="boolean">true</button-press>      <client-id type="integer">177</client-id>      <created-at type="datetime">2015-06-02T20:22:26Z</created-at>      <deleted-at type="datetime" nil="true"></deleted-at>      <description nil="true"></description>      <game-full-message nil="true"></game-full-message>      <id type="integer">241</id>      <key>megaphone-news-demo-trivia</key>      <max-possible-callers type="integer">20</max-possible-callers>      <name>Trivia</name>      <server-modules>com.playmegaphone.games.trivia.TriviaRoomModule</server-modules>      <state>active</state>      <timeout type="integer">-1</timeout>      <transfer type="boolean">false</transfer>      <unlock-audio type="boolean">true</unlock-audio>      <updated-at type="datetime">2015-06-02T20:25:08Z</updated-at>      <use-blocked-caller-id-message type="boolean">true</use-blocked-caller-id-message>      <use-game-full-message type="boolean">true</use-game-full-message>    </app>  </deployment>  <venue>    <id type="integer">12466</id>    <key>2ea4ce505b0a0133ef5c22000ae4063e</key>  </venue>  <instance-phone-numbers type="array">    <instance-phone-number>      <installation-key>live</installation-key>      <number>19933221070</number>    </instance-phone-number>  </instance-phone-numbers></instance>]]></A><A>64</A></L></U>

Receive Screen Ready

MegaScreen then receives a SCREEN_READY message indicating that it is now initialized and ready to begin sending and receiving screen-related commands.

11/20/15 16:04:16.670 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>SCREEN_READY</A><A>2</A><A/><A/></L></U>

Receive Playlist

After Megaphone Realtime Service sends MegaScreen SCREEN_READY, it then sends MegaScreen the entire playlist for the upcoming (or in-progress) run. The playlist is formatted in XML as a set of <question> elements inside a root <questions> element. Each <question> element describes a scene in the playlist.

11/20/15 16:04:16.837 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>s4</A><A>2</A><A/><A/><A><![CDATA[<questions id="564129600209e30003000007" default_question_duration="10" default_answer_duration="5" editor_version="1.1">  <defaults>    <content>      <background>        <media>          <screen/>        </media>      </background>      <show>        <media>          <screen/>          <controller>            <small/>            <medium/>          </controller>        </media>      </show>      <sponsor>        <media>          <screen>https://mp-ced.s3.amazonaws.com/live/megaphone-news-demo-trivia-news-demo/original/563d16f12ba61f000300001d-ford_sponsor_ip.png</screen>          <controller>            <small/>            <medium/>          </controller>        </media>      </sponsor>      <cta>        <media>          <screen/>        </media>      </cta>    </content>  </defaults>  <question id="62696003-3d28-43b0-a1b1-2ebb90f42597" type="survey" roundScreenClass="MainTitle" roundControllerClass="Bulletin">    <content duration="30">Welcome!</content>    <answers duration="0">      <answer>MPTVNEWS.COM</answer>    </answers>    <v2>      <content>        <foreground>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </foreground>        <background>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </background>        <show>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </show>        <sponsor>          <media>            <screen>https://s3.amazonaws.com/mp-ced/live/megaphone-news-demo-trivia-news-demo/original/10180.png</screen>            <controller>              <small/>              <medium/>            </controller>          </media>        </sponsor>        <cta>          <media>            <screen/>          </media>        </cta>      </content>    </v2>    <metaData>{"metadata":""}</metaData>  </question>  <question id="3816f90f-005a-4325-9199-e61cf28dae51" type="survey" roundScreenClass="Title" roundControllerClass="Bulletin">    <content duration="10">Megaphone TV and Tribune</content>    <answers duration="0">      <answer/>    </answers>    <v2>      <content>        <foreground>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </foreground>        <background>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </background>        <show>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </show>        <sponsor>          <media>            <screen>https://s3.amazonaws.com/mp-ced/live/megaphone-news-demo-trivia-news-demo/original/10180.png</screen>            <controller>              <small/>              <medium/>            </controller>          </media>        </sponsor>        <cta>          <media>            <screen/>          </media>        </cta>      </content>    </v2>    <metaData>{"metadata":""}</metaData>  </question>  <question id="faa44cb1-0f49-4eeb-b96a-4bb6dd117a7f" type="survey" roundScreenClass="HotOrNot" roundControllerClass="HotOrNot" media="https://mp-ced.s3.amazonaws.com/live/megaphone-news-demo-trivia-news-demo/original/563d17052ba61f0003000028-isis.jpg">    <content duration="30">Is cyberterrorism a real threat to our safety?</content>    <answers duration="5" updatable="true">      <answer>YES</answer>      <answer>NO</answer>    </answers>    <v2>      <content>        <foreground>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </foreground>        <background>          <media>            <screen>https://mp-ced.s3.amazonaws.com/live/megaphone-news-demo-trivia-news-demo/original/563d1a412ba61f000300006d-cyberterrorism.mp4</screen>            <controller>              <small/>              <medium/>            </controller>          </media>        </background>        <show>          <media>            <screen>https://mp-ced.s3.amazonaws.com/live/megaphone-news-demo-trivia-news-demo/original/563d17286bb948000300002f-news_show_logo_2.png</screen>            <controller>              <small/>              <medium/>            </controller>          </media>        </show>        <sponsor>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </sponsor>        <cta>          <media>            <screen>https://mp-ced.s3.amazonaws.com/live/megaphone-news-demo-trivia-news-demo/original/563d17176bb9480003000029-mpnews_cta_url.png</screen>          </media>        </cta>      </content>    </v2>    <metaData>{"metadata":""}</metaData>  </question>  

</questions>]]></A></L></U>

Receive DATA_MEDIA_URIS

After Megaphone Realtime Service sends MegaScreen the run's playlist, it then sends a list of media used in the playlist. MegaScreen uses the list to pre-load all media for the run.

11/20/15 16:04:16.869 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>DATA_MEDIA_URIS</A><A>1</A><A/><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A><A><![CDATA[<media><m>https://mp-ced.s3.amazonaws.com/live/megaphone-news-demo-trivia-news-demo/original/563d17282ba61f000300003e-nyse_old1.jpg</m><m>https://mp-ced.s3.amazonaws.com/live/megaphone-news-demo-trivia-news-demo/original/563d172f2ba61f0003000041-nyse.jpg</m></media>]]></A></L></U>

Receive Metadata for the Run

In addition to the playlist, after SCREEN_READY, Megaphone Realtime Service also sends MegaScreen DATA_RUN (s13), which includes metadata about the upcoming or in-progress run. The arguments for DATA_RUN are:

11/20/15 16:04:16.865 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>s13</A><A>2</A><A/><A/><A><![CDATA[1448053456715]]></A><A><![CDATA[null]]></A><A><![CDATA[0]]></A></L></U>

Begin Using Megaphone Protocol

Once MegaScreen has received SCREEN_READY, it can use the Megaphone Protocol's command set to control and respond to the playback of a Megaphone playlist. The following sections provide examples of the Megaphone Protocol's commands. For a list of all server-to-MegaScreen messages in the Megaphone Protocol, see "Server-to-MegaScreen Messages," later in this document. For complete access to Megaphone Protocol's documentation, please contact your account representative.

Start a Playlist

To start a playlist, the first MegaScreen instance that connects to a run must send a START_GAME message, as follows:

11/20/15 16:04:16.676 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC sent: <U><M>u70</M><L><A>megaphone-news-demo-trivia-news-demo</A><A>START_GAME</A></L></U>

During the run, subsequent START_GAME messages, if any are sent, are be ignored.

Receive Scene Content

Prior to each scene that occurs in the playback of a Megaphone playlist, MegaScreen receives a DATA_QUESTION message that describes the scene in an XML <question> element.

11/20/15 16:04:16.876 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>DATA_QUESTION</A><A>1</A><A/><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A><A><![CDATA[<question id="62696003-3d28-43b0-a1b1-2ebb90f42597" type="survey" roundScreenClass="MainTitle" roundControllerClass="Bulletin">    <content duration="30">Welcome!</content>    <answers duration="0">      <answer>MPTVNEWS.COM</answer>    </answers>    <v2>      <content>        <foreground>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </foreground>        <background>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </background>        <show>          <media>            <screen/>            <controller>              <small/>              <medium/>            </controller>          </media>        </show>        <sponsor>          <media>            <screen>https://s3.amazonaws.com/mp-ced/live/megaphone-news-demo-trivia-news-demo/original/10180.png</screen>            <controller>              <small/>              <medium/>            </controller>          </media>        </sponsor>        <cta>          <media>            <screen/>          </media>        </cta>      </content>    </v2>    <metaData>{"metadata":""}</metaData>  </question>]]></A></L></U>

During the scene, on a regular interval, MegaScreen is also sent a DATA_ROUND_RANKINGS message and an UPDATE_STATE_ROUND message.

11/20/15 16:04:16.877 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>DATA_ROUND_RANKINGS</A><A>1</A><A/><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A><A><![CDATA[]]></A></L></U>

11/20/15 16:04:16.878 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>UPDATE_STATE_ROUND</A><A>1</A><A/><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A><A><![CDATA[1]]></A><A><![CDATA[35]]></A><A><![CDATA[ROUND]]></A><A><![CDATA[0]]></A><A><![CDATA[0]]></A><A><![CDATA[0]]></A><A><![CDATA[]]></A><A><![CDATA[]]></A><A><![CDATA[0]]></A><A><![CDATA[0]]></A></L></U>

The UPDATE_STATE_ROUND message's arguments are as follows:

Advanced to New Scene

When the application advances to a new scene, MegaScreen receives a SET_STATE_ROUND message. MegaScreen is then expected to render the content received in the most recent DATA_QUESTION message.

11/20/15 16:04:16.884 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>SET_STATE_ROUND</A><A>1</A><A/><A><![CDATA[megaphone-news-demo-trivia-news-demo]]></A></L></U>

Advance to Next Scene

To advance to the next scene in the playlist, MegaScreen sends a NEXT message to Megaphone Realtime Service.

11/20/15 16:04:18.878  UTC-5 DEBUG: [MESSAGE_MANAGER] UPC sent: <U><M>u70</M><L><A>megaphone-news-demo-trivia-news-demo</A><A>NEXT</A></L></U>

MegaScreen's Client Heartbeat

To maintain a valid, active connection to Megaphone Realtime Service, MegaScreen must send the server a message at least once every 30 seconds. To avoid disconnection, Megaphone recommends sending a heartbeat ("ping") message from all MegaScreen clients to Megaphone Realtime Service every 10 seconds, as shown in the following example:

12/2/15 19:19:42.161 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC sent: <U><M>u2</M><L><A>CLIENT_HEARTBEAT</A><A>5583</A><A></A><A>1</A></L></U>

12/2/15 19:19:42.195 UTC-5 DEBUG: [MESSAGE_MANAGER] UPC received: <U><M>u7</M><L><A>CLIENT_HEARTBEAT</A><A>2</A><A>5583</A><A/><A>1</A></L></U>

Server-to-MegaScreen Messages

Table 1 lists all server-to-screen messages in the Megaphone Protocol.

Table 1. Server to MegaScreen Messages

Message ID

Message Description

DATA_QUESTION

A scene definition.

DATA_ROUND_RANKINGS

Player rankings for the current scene.

DATA_MEDIA_URIS

List of media used in the current run.

DATA_RECENT_CALLERS

List of users that joined the run recently.

DATA_RECENT_RESPONSES

A sampling of user inputs for the current run.

s4 (DATA_CONTENT_MANIFEST)

The playlist for the current run.

UPDATE_STATE_INSTRUCTIONS

Data relating to the Instructions state.

UPDATE_STATE_MAIN_COUNTDOWN

Data relating to the Main Countdown state.

UPDATE_STATE_ROUND

Data relating to the Scene state.

UPDATE_STATE_ROUND_ENDPAUSE

Data relating to the Scene Outro state.

UPDATE_STATE_ROUND_SCOREBOARD

Data relating to the Scene Scoreboard state.

UPDATE_STATE_GAMEOVER

Data relating to the Run End state.

UPDATE_STATE_GAME_WINNER

Data relating to the Game Winner state.

UPDATE_STATE_MAIN_SCOREBOARD

Data relating to the Main Scoreboard state.

SET_STATE_INTRODUCTION

Informs the screen that the application has moved to the Introduction state.

SET_STATE_INSTRUCTIONS

Informs the screen that the application has moved to the Instructions state.

SET_STATE_MAIN_COUNTDOWN

Informs the screen that the application has moved to the Main Countdown state.

SET_STATE_MAIN_COUNTDOWN_ENDPAUSE

Informs the screen that the application has moved to the Main Countdown Outro state.

SET_STATE_ROUND

Informs the screen that the application has moved to the Scene state.

SET_STATE_ROUND_ENDPAUSE

Informs the screen that the application has moved to the Scene Outro state.

SET_STATE_ROUND_SCOREBOARD

Informs the screen that the application has moved to the Scene Scoreboard state.

SET_STATE_GAMEOVER

Informs the screen that the application has moved to the Run End state.

SET_STATE_GAME_WINNER

Informs the screen that the application has moved to the Game Winner state.

SET_STATE_MAIN_SCOREBOARD

Informs the screen that the application has moved to the Main Scoreboard state.

SET_STATE_INTERMISSION

Informs the screen that the application has moved to the Intermission state.

s6 (HIDE_ALL)

Instructs MegaScreen to hide all visual content.

s8 (SHOW_ALL)

Instructs MegaScreen to show all visual content.

s13 (DATA_RUN)

Metadata for the current run.

Confidential Internal Engineering Documentation. Not for Public Distribution. Copyright Play MegaPhone Inc.