iFrame PostMessage API

Listening for Events

The Ask Video Player posts several events which the parent page of the iframe can listen to and act on using window.postMessage().

Plain JavaScript

<script type="text/javascript">
    // Example listening for dispatched events from iframe
    function handleEvent(e) {
        console.log('iframe event data: ', e.data)
    }

    window.addEventListener('message', handleEvent, false)
    window.onunload = function() {
        console.log("clear event listener prior to leaving page")
        window.removeEventListener('message', handleEvent)
    }
</script>

Within a React.js component

useEffect(() => {
    const handleEvent = e => {
        console.log('iframe event data: ', e.data)
    }
    window.addEventListener('message', handleEvent, false)
    return () => window.removeEventListener('message', handleEvent, false)
}, [])

Dispatched event messages and their payload format:

'webapp_loaded' - The video screen and waiting pose have been loaded.
{type: 'storyfile-iframe-height', value: number} - In order to avoid double scroll bars, some app screens will post the height of the content. The parent page can dynamically adjust the iframe height.
'mic_visible' - Hold to talk button is visible.
'mic_hidden' - Hold to talk button is hidden.
'video_ended' - Indicates that a question answer has ended playing.
{type: 'is_listening', value: boolean} - Indicates when AskApp starts/stops listening.
{type: 'video_end_event', eventName: string, params: string[]} - After a video response has played, there could be one or more video end events. These events trigger certain functionalities within the app, but custom video end events can be created through Conversa and acted on by pages embedding the Ask app.
{type: 'sessionId', value: string} - The id for the current session. Allows continuing previous sessions on consecutive iframe loads by providing a valid session id through URL param sid.
{type: 'changed_language', value: {tag: string, name: string, appLocale: string}} - Indicates the input language has changed, along with the language code for the new input language.
{type: 'asked_question', transcription: string, sessionId: string} - Indicates when a question has been asked.
{type: 'spawn_receiver_window'} - Enabled with URL param rcReceiverWindowEvent.

Dispatching Events to iFrame

The Ask app also listens for events from the parent page. This allows for triggering functionality from outside the app.

<script type="text/javascript">
    // Example dispatching an event to the iframe
    const iframe = document.getElementById('askApp')
    iframe.contentWindow.postMessage(payload, '*')
</script>

Supported event messages and their payload format:

{type: 'question', value: string, showTranscription: boolean} - Initiate asking a question with a question text value obtained from outside the app, e.g., through speech recognition, menu option, or user input. Use showTranscription (optional, defaults to true) to control if you want the question to be shown on the screen.
{type: 'startListening', listenDuration: number} - Initiate listening for voice input by the user. The app will auto-stop listening after the listenDuration number of seconds has passed without user input.
{type: 'stopListening'} - Can be used to interrupt listening (e.g., if using auto listen param).
{type: 'interruptAnswer'} - Can be used to interrupt the current video answer and go to the resting pose.
{type: 'language', value: string} - Initiate change of both voice input language and language of the app’s UI. For accepted values, refer to the speech recognition section.

Authentication

If you are authenticating through our API, you can bypass the Ask app’s login screen when loading private StoryFiles. Use the URL parameter &private=1 to load the iframe in private mode. Listen for a dispatched event 'token_request', which indicates that the Ask app is awaiting a valid access token and IAM through postMessage.

Upon receiving the token request, use postMessage to send a payload {type: 'token', value: string, iam: string}, where value is a valid access token and iam is the authenticated account’s IAM.

Sample Applications

Linking to other pages with post-events
Using JavaScript to set language
Using JavaScript to trigger videos
Using JavaScript to track sessions
Using JavaScript to count the number of interactions (i.e., for a paywall) CodePen Example
Using the FAB to follow you through a page StoryFile Example

Listening for Events​

Dispatching Events to iFrame​

Authentication​

Sample Applications​

Listening for Events

Dispatching Events to iFrame

Authentication

Sample Applications