Cross-document messages

Cross-document messaging, when enabled via the &xdocMsg=true query parameter, allows you to issue commands to the embedded iFrame via Javascript via postMessage(message, targetOrigin).

Messages without any parameters can be passed directly as strings, e.g. postMessage('requestSession', '*').

Messages with parameters should be passed as objects with the message name in the type field. E.g. postMessage({type: 'mouseclick', x: 100, y:100}, '*')

• requestSession - equivalent to clicking play

• emitHomeButton - taps the home button for iOS apps when available

• rotateLeft - rotates counter-clockwise

• rotateRight - rotates clockwise

• setScale(value) - sets device scale, values between 10 and 100

• saveScreenshot - prompts user to download screenshot

• getScreenshot - sends screenshot data directly to parent window. See the screenshot event the iFrame posts to the parent.

• heartbeat - sends heartbeat to prevent inactivity timeout

• mouseclick(x, y) - sends click event at point (x, y)

• pasteText(value) - pastes text. value should be a string.

• keypress(key, shiftKey) - sends keypress. key should be a string that identifies the key pressed, e.g. 'a'. Acceptable values on Android also include 'volumeUp' and 'volumeDown'.

• language(value) - sets language, restarts app

• location(value) - sets location. value should be 2-length array that contains [latitude, longitude]

• openUrl(value) - opens deep-link or regular URL

• shakeDevice - send shake gesture to iOS apps

• androidKeycodeMenu - sends Android KEYCODE_MENU command

• biometryMatch - (Android 8+ only) simulate a matching fingerprint

• biometryNonMatch - (Android 8+ only) simulate a non-matching fingerprint

• disableInteractions - disables all user interactions

• enableInteractions - re-enables all user interactions

• restartApp - kills and restarts app in same session

• endSession - ends the session

The iFrame also posts messages to the parent window.

• userInteractionReceived - interaction received

• heartbeatReceived - heartbeat received

• orientationChanged - portrait or landscape

• sessionRequested - session requested

• userError - error starting session

• sessionQueued - system-level queue (awaiting device availability)

• sessionQueuedPosition - queue position

• accountQueued - account-level queue (concurrent users)

• accountQueuedPosition - queue position

• appLaunch - app launch command sent

• firstFrameReceived - first frame received

• timeoutWarning - timeout in 10 seconds

• sessionEnded - session ended

• screenshot - screenshot data received

• chromeDevToolsUrl - only if network intercept enabled

• sessionConnecting - passes the identifying token for the session

​Check out our JSFiddle.net example to see these messages in action!​