Megaphone TV

MegaController Host API Specification

The MegaController Host API is a general communications bridge across which MegaController communicates with its host environment—typically a web page or a mobile app. The MegaController Host API is bi-directional, supporting both "MegaController to host" and "host to MegaController" messaging.

For example, a parent website might use the MegaController Host API to send third-party login-information to MegaController.

Or MegaController might use the MegaController Host API to send state information to a parent mobile app. The state information could, for example, indicate that a poll question has started.

This following sections describe the MegaController Host API's structure and supported messages.

General Message Format

Messages in the MegaController Host API have the following general format, which applies in both directions of communication.

message?key1=value1&key2=value2&keyn=valuen

The message specifies the type of message being sent, while key1=value1&key2=value2&keyn=valuen specifies the message arguments as a list of "key/value" pairs.

Example: An APPLICATION_STATE_CHANGE message

APPLICATION_STATE_CHANGE?state=SCENE_START&product=PicPick&sceneType=quiz

In the preceding example, the message type is APPLICATION_STATE_CHANGE, meaning the controller has entered a new application state during a Megaphone run. The APPLICATION_STATE_CHANGE message includes three arguments, as follows:

Bridge-Type Selection

In order to receive messages from MegaController, the host must select a MegaController-to-host bridge type. Likewise, in order to send messages to MegaController, the host must select a host-to-MegaController bridge type. The bridge type determines how messages are sent or received. The host selects a bridge type using URL query-string parameters when loading MegaController. The available parameters are:

For example, to select the "web" bridge type for messages sent to the host environment, the host loads MegaController with the tohost_bridgetype set to "web", as follows:

https://mpcontrollers.s3.amazonaws.com/example/index.html?tohost_bridgetype=web

To select a bridge type for both directions of communication (to MegaController and to host) the host includes two URL query-string parameters, as follows:

https://mpcontrollers.s3.amazonaws.com

/example/index.html?tohost_bridgetype=web&tocontroller_bridgetype=jsbridge

The available bridge types are as follows:

Note that MegaController does not enable Host API communications until a bridge type is selected by the host. If a host does not supply a value for tohost_bridgetype at load time, MegaController will not send any messages to the host. Likewise, if a host does not supply a value for tocontroller_bridgetype at load time, MegaController will not respond to any messages sent by the host.

Bridge types are not dependent on, nor limited to, a specific platform, operating system, or language. Any host environment can select any bridge type for communications.

MegaController-to-Host Communication

MegaController supports two formats for sending messages to a host environment: Web Messaging and Custom URL Messaging. In Web Messaging, MegaController sends messages to the host using JavaScript's Window.postMessage() method. In Custom URL Messaging, MegaController sends messages to the host using browser navigation that must be intercepted by the host. Custom URL Messaging provides MegaController with a means of sending messages to hosts that do not support postMessage() events. In hosts that support postMessage(), Web Messaging is preferred.

For a list of supported MegaController-to-Host messages, see MegaController-to-Host Message Reference.

The following sections describe Web Messaging and Custom URL Messaging in more detail.

Web Messaging

Description

MegaController sends messages to the host environment using JavaScript's Window.postMessage() method.

Recommended Use

Examples

The following examples show the sending and receiving sides of a STATE_CHANGE message transported using postMessage().

Example: MegaController dispatches the message using postMessage()

parent.postMessage(APPLICATION_STATE_CHANGE?state=SCENE_START&product=PicPick&sceneType=quiz',

                   'https://example.com/');

Example: Host handles the message with a postMessage() message-listener

document.addEventListener('message', function(event) {

  var origin = event.origin || event.originalEvent.origin;

  if (origin !== 'https://mpcontrollers.s3.amazonaws.com') {

    return;

  }

  // event.data contains the message, in the format described under General Message Format

  handleData(event.data);

);

Custom URL Messaging

Description

MegaController sends messages to the host environment by navigating to a custom-formatted URL with the following general format:

        megaphonetv://message?key1=value1&key2=value2&keyn=valuen

To receive the message, the host environment intercepts the navigation attempt, processes the message, and cancels the navigation. In the preceding URL, notice that the URL's scheme is megaphonetv://, indicating that the navigation attempt should be treated as a message by the host (rather than as navigation).

Recommended Use

Examples

Example: A custom URL message

        megaphonetv://APPLICATION_STATE_CHANGE?state=SCENE_START&product=PicPick&sceneType=trivia

Example: MegaController dispatches message by navigating to a Custom URL

// MegaController attempts navigation with custom URL scheme

window.location = 'megaphonetv://APPLICATION_STATE_CHANGE?state=SCENE_START&product=PicPick&sceneType=quiz';

Example: Host handles Custom URL message in Objective C on iOS

- (BOOL)webView:(UIWebView*)webView shouldStartLoadWithRequest:(NSURLRequest*)request navigationType:(UIWebViewNavigationType)navigationType {

    NSURL *URL = [request URL];

    if ([[URL scheme] isEqualToString:@"megaphonetv"]) {

        // Parse and handle incoming MegaController message (code not shown)...

        // ...then cancel navigation

        return NO;

    }

    // URL's scheme is not megaphonetv, so allow navigation

    return YES;

}

Example: Host handles Custom URL message in Java on Android

@Override

// override shouldOverrideUrlLoading method of WebViewClient in custom class

public class CustomWebViewClient extends WebViewClient {

boolean shouldOverrideUrlLoading (WebView view, WebResourceRequest request){

        // If the requested URL starts with 'megaphonetv://'

        if (request.getUrl().startsWith('megaphonetv://')) {

                // Parse and handle incoming MegaController message (code not shown)...

// ...then cancel navigation

                return true;

        }

        // URL's scheme is not megaphonetv, so allow navigation

return false;

}

}

MegaController-to-Host Message Reference

The MegaController Host API supports the following official "MegaController-to-host" messages.

INITED

Sent when MegaController has been initialized, and is ready to receive messages from the host. The INITED message is sent once, and only once, during MegaController's lifecycle. The host is required to wait for the INITED message before sending messages to MegaController. Any messages sent to MegaController by the host prior to the receipt of INITED are ignored, and could cause JavaScript errors in MegaController.

Example
// Note: no query-string parameters required

INITED

CONNECTION_STATE_CHANGE

Indicates that MegaController's connection to Megaphone Realtime Services has changed.

Example

The following code shows the general structure of the CONNECTION_STATE_CHANGE message:


CONNECTION_STATE_CHANGE?state=state_name

where state_name is the official name of the state being entered.

Parameters

state

  • String

Specifies the name of the state being entered.

NOT_READY

Sent when MegaController is not connected to an active Megaphone deployment. In this state, MegaController displays the default NOT_READY view. During the NOT_READY state, MegaController does not send APPLICATION_STATE_CHANGE messages to the host.

Example
CONNECTION_STATE_CHANGE?state=NOT_READY

READY

Sent when MegaController connects to an active deployment. Once READY, MegaController displays the default READY view until an APPLICATION_STATE_CHANGE message provides the current run state.

Example
CONNECTION_STATE_CHANGE?state=READY

APPLICATION_STATE_CHANGE

Indicates that MegaController has entered a new application state; for example, a new question has been asked or the current run is over. State changes in MegaController typically coincide with corresponding changes in MegaScreen, Megaphone's on-air broadcast graphics application.

Example

The following code shows the general structure of the APPLICATION_STATE_CHANGE message:


APPLICATION_STATE_CHANGE?state=state_name&param1=value1&param2=value2&...paramn=valuen

where state_name is the official name of the state being entered, and param1=value1&param2=value2&...paramn=valuen are optional parameters that describe the state.

Parameters

correct

  • Boolean

Indicates whether, in the scene that just ended, the user's answer was correct. The correct parameter is supplied when:

  • the state parameter is SCENE_END 
  • AND the sceneType parameter is quiz 

See also the SCENE_END value under the state parameter.

isWinner

  • Boolean

Indicates whether the user won the most recent run. The isWinner parameter is supplied when:

  • the state parameter is POST_RUN 
  • AND at least one scene with a sceneType of quiz occurred during the run

See also the POST_RUN value under the state parameter.

product

  • String

The name of the product being used in the current scene. Example values include PicPick, Blank, and HotOrNot. The product parameter is supplied when:

  • the state parameter is SCENE_START 

See also the SCENE_START value under the state parameter.

sceneType

  • String

The type of the current scene. The following table lists legal values, subject to expansion.

survey

An opinion poll.

quiz

A scored question with a correct answer.

comment

A scene with no visible content.

The sceneType parameter is supplied when:

  • the state parameter is SCENE_START

See also the SCENE_START value under the state parameter.

score

  • Integer

The number of points scored by the user in the most recent run. The score parameter is supplied when:

  • the state parameter is POST_RUN 
  • AND at least one scene with a sceneType of quiz occurred during the run

See also the POST_RUN value under the state parameter.

state

  • String

The name of the state being entered. The following table lists the legal values for state, in the order in which they are typically encountered during a Megaphone run lifecycle.

PRE_RUN

Sent when MegaController is in the PRE_RUN state (typically, a loading screen, instructions screen, or introduction screen). In this state, MegaController displays the default PRE_RUN view.

Example
APPLICATION_STATE_CHANGE?state=PRE_RUN

SCENE_START

Sent when MegaController enters a new scene. In this state, MegaController displays the user interface for the scene's accompanying product.

Example
APPLICATION_STATE_CHANGE?state=SCENE_START&product=PicPick&sceneType=quiz

SCENE_END

Sent when MegaController exits a scene. In the SCENE_END state, MegaController displays the results of the current scene and/or a scene-exit animation.

Example
APPLICATION_STATE_CHANGE?state=SCENE_END&voted=true&correct=true

RUN_OVER

Sent after the last scene in the current Megaphone run ends. During the RUN_OVER state, if the run included a quiz, Megaphone Realtime Services calculates rankings and final scores, and MegaController displays a waiting message.

Example

APPLICATION_STATE_CHANGE?state=RUN_OVER

POST_RUN

Sent when Megaphone has exited the most recent run. In the POST_RUN state, MegaController remains connected to Megaphone Realtime Services, waiting for the next run to start. In this state, MegaController typically displays the player's score and an invitation to leave feedback.

Example
APPLICATION_STATE_CHANGE?state=POST_RUN&score=1234&isWinner=true

voted

  • Boolean

Indicates whether, in the scene that just ended, the user voted or not. The voted parameter is supplied when:

  • the state parameter is SCENE_END

See also the SCENE_END value under the state parameter.

Host-to-MegaController Communication

MegaController supports two formats for receiving messages from a host environment: Web Messaging and JavaScript Bridge Messaging. In Web Messaging, the host sends messages to MegaController using JavaScript's Window.postMessage() method. In JavaScript Bridge Messaging,  the host sends messages to MegaController using direct JavaScript code execution. JavaScript Bridge Messaging provides MegaController with a means of receiving messages from hosts that do not support postMessage() events. In hosts that support postMessage(), Web Messaging is preferred.

Important: MegaController cannot receive messages from the host until after the host receives an INITED message from MegaController. See INITED.

The following sections describe Web Messaging and JavaScript Bridge Messaging in more detail.

Web Messaging

Description

Host sends messages to MegaController using JavaScript's Window.postMessage() method.

Recommended Uses

Examples

The following examples show the sending and receiving sides of a hypothetical LOGIN message transported using postMessage(). Notice that the message format for messages sent from the host to MegaController is exactly the same as the format for messages sent from MegaController to the host.

Example: Host postMessage() dispatch

megaController.postMessage('LOGIN?provider=2&token=eff8476db30a8cc245',

                           'https://mpcontrollers.s3.amazonaws.com');

Example: MegaController handling a postMessage() event

document.addEventListener('message', function(event) {

  var origin = event.origin || event.originalEvent.origin;

  if (origin !== 'https://example.com') {

    return;

  }

  handleData(event.data);

);

Note that the preceding code's example LOGIN message reflects the general structure of a typical login message, but LOGIN is not an official standardized message in MegaController's Host API. The actual message implementation for a LOGIN message would be customized to suit the needs of the host's individual requirements.

JavaScript Bridge Messaging

To allow host environments that do not support Web Messaging to send messages to MegaController, MegaController defines a top-level JavaScript object named megaphone.hostbridge. For the sake of format consistency and code reuse, messages sent to megaphone.hostbridge must use the standard MegaController Host API message format described earlier under General Message Format. To send a message to MegaController, an application invokes megaphone.hostbridge.sendMessage(). For example, to send MegaController a message of type LOGIN with parameters provider and token, the host would execute the following JavaScript code on the MegaController Window object:

megaphone.hostbridge.sendMessage('LOGIN?provider=2&token=eff8476db30a8cc245');

Note that the preceding code's LOGIN message is presented for illustrative purposes only. In an actual host implementation, the message name (LOGIN) and specific parameters (provider, token) would depend on the host environment, and would be mutually agreed upon by the host developer and Megaphone TV.

For host applications that choose to use JavaScript Bridge Messaging, the code required to execute JavaScript code can vary widely. The following table lists APIs typically used on popular mobile platforms to execute JavaScript code in an embedded web view:

iOS

  • iOS 8+
    WKWebView.evaluateJavaScript('megaphone.hostbridge.sendMessage('LOGIN?provider=2&token=eff8476db30a8cc245')')
  • Pre iOS 8
    UIWebView.stringByEvaluatingJavaScriptFromString('megaphone.hostbridge.sendMessage('LOGIN?provider=2&token=eff8476db30a8cc245')')

Android

  • Android 4.4+
    WebView.evaluateJavascript('megaphone.hostbridge.sendMessage('LOGIN?provider=2&token=eff8476db30a8cc245')')
  • All Android Versions
    someWebView.loadUrl("javascript:megaphone.hostbridge.sendMessage('LOGIN?provider=2&token=eff8476db30a8cc245')");