Tiger Squad

Explore

Cross-platform Architecture

Mobile Interface

Event-based Messaging

This document will cover communicating to and from the “Host App” (the mobile app production frontend), and the Survey Engine’s UI, which we’ll refer to as, the “Survey Frame”.

Here we will answer the question, “How does the remote frame communicate with the mobile host layer?”

Continue reading to learn more...

Survey Frame, to Host App Communication

The Survey Frame only has one mechanism by which to communicate with the mobile host, and that is via the:

window.ReactNativeWebView.postMessage(message: string)

...which is a function that the React-Native platform automatically injects onto every webpage’s window object.

With this postMessage() function, the Survey Frame can send any serialized string message directly to the native mobile layer.

📤 Frame-Emitted Event Definitions

The following events must be supported in order to provide a flexible framed layer that can be easily consumed by mobile:

A selection, choice, or response was made by the user: onSelectionChange(?)

The “Next” question button was tapped/clicked: OnNext(?)

The “Previous” question button was tapped/clicked: OnPrevious(?)

The form is in a loading status: OnLoadingStatusChange(newStatus: boolean)

Any error has occurred within the frame: OnError(error: Error)

The form has been submitted and is pending completion: OnSubmit<T>(values: T<any>)

There was an error during form submission: OnSubmitError(error: Error)

The form has been successfully completion without error: OnSuccess<T>(values: T<any>)

The user clicked the primary call to action on the confirmation page: OnComplete(?)

Handling 2 or more call-to-actions

Examples:

The following code would live inside the frontend layer of the Survey Engine. This snippet assumes that TypeScript is being used throughout the Survey Engine’s UI layer.

// Scenario 1: User makes a selection on one of the form questions.

...

enum EventType {

OnSelectionChange = "OnSelectionChange",

OnNextQuestion = "OnNextQuestion",

...

}

type FormSelection = {

question_id: string;

selection_id: string;

}

type EventPayload = {

event_type: EventType;

data: FormSelection;

}

...

function handleFormSelection(selection: FormSelection) {

const payload: EventPayload = {

event_type: SurveyEngineEventType.OnSelectionChange,

data: selection,

};

// must check to see if the ReactNativeWebView was injected or not

if (!!window.ReactNativeWebView) {

window.ReactNativeWebView.postMessage(JSON.stringify(payload));

}

...

// rest of form selection event handling code goes here...

}

...

// rest of UI code goes here...

...

<MenuItem onClick={() => handleFormSelection({

question_id: "QUESTION-A1",

selection_id: "SELECTION-1"

})}>

SELECTION 1

</MenuItem>

Host App, to Survey Frame Communication

The React-Native platform also only has one mechanism to send messages to the frame, and that is with the:

webViewRef?.current?.postMessage(message: string)

...function that is provided by the WebView reference itself. It operates the same way that the injected postMessage function works and only supports sending string-based events and messages to the frame.

📥 Frame-Handled Event Definitions

The following events must be handled by the survey frame in order to provide a flexible user experience in mobile app contexts:

The user has tapped a hardware back button or a soft key back button, to initiate going back to the previous question: OnClose()

Event-based Messaging

Survey Frame, to Host App Communication

Host App, to Survey Frame Communication

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.