API reference

getClient()

Get an instance of the Appetize client.

const client = await window.appetize.getClient('#my_iframe')

Parameters

Name	Type	Description
selector	string	A query selector string pointing to the embedded iframe

Client

on()

Listens for an event of the given name

client.on(event, data => {
   console.log(data)
})

Event	Data Type	Description
queue	{ type: 'account' | 'session' , position: number }	Your position in queue for the device. If type is account you have reached the maximum amount of concurrent sessions for your account and are in queue for the next available slot. If type is session, you are in a queue to wait for the next available device.
error	string	An error has occurred
deviceInfo	Record<string, any>	Information about the current device, such as type, orientation, and screen dimensions. It also contains rendered dimensions of the device within the embed.
session	Session	A new session has started, either by client.startSession() or the user clicking "Tap to Play" on the device

startSession()

Starts a session with the requested app, device, operating system, and other launch options.

const session = await client.startSession()

Parameters

Name	Type	Description
config?	Record<string, any>	A JSON object describing the Configuration options for the device.

config()

Update the configured app, device, operating system, or other launch options.

Note: This will end any active sessions.

await client.config(config)

Parameters

Name	Type	Description
config	Record<string, any>	A JSON object describing the Configuration options for the device.

loadApp

Changes the loaded Appetize app of the iframe. This will restart your session, and you can also pass in config as well.

Session

on()

Listens for an event of the given name

session.on(event, data => {
   console.log(data)
})

Event	Data Type	Description
log	{ message: string }	Debug log from the device Requires debug to be set to true
network	Record<string, any>	Intercepted network request or responses. Requires proxy to be set to intercept
error	string	An error has occurred on the session
action	Record<string, any>	An action has been recorded
interaction	Record<string, any>	Session received interaction from the user
inactivityWarning	{ secondsRemaining: number }	Session is about to timeout due to inactivity. Any user interaction or a heartbeat will reset the timeout.
orientationChanged	'portrait' | 'landscape'	The device has changed orientation
video	{ buffer: Uint8Array, width: number, height: number, codec: string }	Video frames of the current session. When codec is h264, the buffer is a raw frame of the stream. These frames can be muxed (using something like jmuxer) to turn it into a video format. When codec is jpeg the buffers are jpeg images.
audio	{ buffer: Uint8Array, codec: 'aac' }	Audio frames of the current session. Like h264 with the video event, these can be muxed as well.

end()

Ends the session

await session.end()

rotate()

Rotates the device 90 degrees

await session.rotate('right')

Parameters

Name	Type	Description
direction	"left" | "right"	The direction to rotate

screenshot()

Takes a screenshot of the device and returns the data

const { data, mimeType } = await session.screenshot(format)

Parameters

Name	Type	Description
format	"buffer" | "base64"	The format of the screenshot data to return

heartbeat()

Sends a heartbeat to the server, resetting the inactivity timer

await session.heartbeat()

tap()

Taps on the screen at the given position

await session.tap({ x: 100, y: 100 })

Parameters

Name	Type	Description
coordinates	{ x: number, y: number}	The coordinates of the position to tap, relative to the screen.

type()

Types the given text on the device

await session.type("hello")

Parameters

Name	Type	Description
text	string	Text to type

keypress()

Sends a single key press to the device

await session.keypress("a")

Parameters

Name	Type	Description
key	string	Key to send to the device ('a', 'b', etc.) Also takes special values for hardware keys: HOME VOLUME_UP (android only) VOLUME_DOWN (android only) ANDROID_KEYCODE_MENU
options	{ shift?: boolean }

setLanguage()

Changes the current language and restarts the app

await session.setLanguage("fr")

Parameters

Name	Type	Description
language	string	Language code

setLocation()

Sets the simulated location of the device.

await setLocation(-33.924434, 18.418391)

Parameters

Name	Type	Description
latitude	number	Decimal number between -90 and 90, representing the degrees of north or south of the Equator. Negative numbers indicate south of the Equator, and positive numbers indicate north of the Equator.
longitude	number	Decimal number between -180 and 180, representing the degrees of east or west of the Prime Meridian. Negative numbers indicate west of the Prime Meridian, and positive numbers indicate east of the Prime Meridian.

openUrl()

Opens a deep-link or web URL

await session.openUrl("https://appetize.io")

Parameters

Name	Type	Description
url	string	The URL

shake()

Shakes device (iOS only)

await session.shake()

biometry()

Simulate a matching fingerprint (Android 8+ only)

await session.biometry({
    match: true/false
})

allowInteractions()

Enables or disables all interactions on the device. Default is true.

await session.allowInteractions(true/false)

restartApp()

Restarts the app

await session.restartApp()

getUI()

Returns the UI as an XML string

await session.getUI()

getAdbInfo()

Returns information about the adb connection (Android only)

const adb = await session.getAdbInfo()

getNetworkInspectorUrl()

Returns the URL to chrome dev tools to inspect network logs. Requires proxy to be set to intercept

const url = await session.getNetworkInspectorUrl()

playAction()

Play an automation Action or array of Actions.

await session.playAction(action)

Parameters

Name	Type	Description
action	Record<string, any>	Actions emitted from the session.on('action') event

playActions

Plays an array of actions.

await session.playActions(actions)

Parameters

Name	Type	Description
actions	Array<Record<string, any>>	Actions emitted from the session.on('action') event