API reference

getClient(selector)

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

getClient(selector, config)

Get an instance of the Appetize client as well as set the initial config when loading the client.

Useful when the embed link might not be known up front and the configuration has to be applied at runtime.

const client = await window.appetize.getClient('#my_iframe', {
    buildId: '{buildId|publicKey}',
    device: 'iphone11pro',
    osVersion: '15.0'
    ...
})

Parameters

Name	Type	Description
selector	string	A query selector string pointing to the embedded iframe
config	Record<string, any>	A JSON object describing the Configuration options for the device.

Client

on()

Listens for an event of the given name

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

Event	Data Type	Description
queue	{ type: 'session' | 'concurrent', position: number, name?: string }	Your position in queue for the device. If type is session, you are in a queue to wait for the next available device for your configuration. If type is concurrent you have reached the maximum amount of concurrent sessions for your account and are in queue for the next available slot.
error	string	An error has occurred
deviceInfo	Record<string, any>	Information about the current device, such as type, osVersion, and screen dimensions.
sessionRequested	void	A new session has been requested either by the client or user clicking "Tap to Play"
sessionEnded	void	An active session has ended.
session	Session	A new session has started either by the client or user clicking "Tap to Play"
app	Record<string, any>	The currently loaded Appetize app

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.

setConfig()

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

Note: This will end any active sessions.

await client.setConfig(config)

Parameters

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

getConfig()

Returns the current config

const config = client.getConfig()

endSession()

Ends the active session or cancels any pending session requests.

await client.endSession()

device

The currently loaded device

{
    type: string;
    name: string;
    osVersion: string;
    orientation: 'portrait' | 'landscape';
    screen: {
        width: number;
        height: number;
        devicePixelRatio?: number;
    };
    embed: {
        width: number;
        height: number;
        screen: {
            width: number;
            height: number;
            offset: {
                x: number;
                y: number;
            };
        };
    };    
}

app

The currently loaded app

{
  buildId: string;
  name?: string;
  appDisplayName?: string;
  appVersionName?: string;
  appVersionCode?: string;
  bundle?: string;
  platform?: string;
  versionCode?: string;
  architectures?: string;
  iconUrl?: string;
  created?: string;
  apps?: AppetizeApp[];
}

Session

on()

Listens for an event of the given name

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

Event	Data Type	Description
action	Record<string, any>	A user action has been recorded. This can be played back later with playAction. Requires record to be set to true
audio	{ buffer: Uint8Array, codec: 'aac' }	Audio frames of the current session. Requires audio to be set to true
error	string	An error has occurred on the session
inactivityWarning	{ secondsRemaining: number }	Session is about to timeout due to inactivity. Any user interaction or a heartbeat will reset the timeout.
interaction	Record<string, any>	User has interacted with the device.
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
orientationChanged	'portrait' | 'landscape'	The device has changed orientation
video	{ buffer: Uint8Array, width: number, height: number, codec: string }	Video frames of the current session. These frames can be muxed (e.g. using jmuxer) to turn it into a video format. When codec is jpeg the buffers are of jpeg images.
end	void	The session has ended

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(format)

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. Defaults to buffer

heartbeat()

Sends a heartbeat to the server, resetting the inactivity timer

await session.heartbeat()

tap(target, options)

Taps on the screen at the given position, coordinate or element

await session.tap({ position: { x: '50%', y: '50%' } })
await session.tap({ coordinates: { x: 100, y: 100 } })
await session.tap({ element: { attributes: { text: 'OK' } } })

Parameters

Name	Type	Description
target.coordinates?	{ x: number y: number }	The coordinates in dip units
target.position?	{ x: string y: string }	The position on screen in %
target.element?	ElementSelector	An element selector
target.duration?	number	Duration of the tap
options.timeout?	number	If an element is provided, the amount of time to wait for it to appear in ms (defaults 10s)
options.matchIndex?	number	If multiple elements match the element selector, select the nth one

swipe(target, options)

Swipes on the screen at the given position, coordinate or element

await session.swipe({ position: { x: '50%', y: '50%' }, gesture: 'up' })
await session.swipe({ coordinates: { x: 100, y: 100 }, gesture: 'up' })
await session.swipe({ element: { attributes: { text: 'OK' } }, gesture: 'up' })

target.coordinates?	{ x: number y: number }	The coordinates in dip units to start the swipe
target.position?	{ x: string y: string }	The position on screen in %
target.element?	ElementSelector	An element selector
target.duration?	number	Duration of the swipe
target.gesture	string | function	The gesture of the swipe. See swipe for more details
options.timeout?	number	If an element is provided, the amount of time to wait for it to appear in ms (defaults 10s)
options.matchIndex?	number	If multiple elements match the element selector, select the nth one

type(text)

Types the given text on the device

await session.type("hello")

Parameters

Name	Type	Description
text	string	Text to type

Typing is limited to 1000 characters at a time to ensure optimal performance and prevent potential disruptions. For larger payloads, you can use multiple 'type' operations.

keypress(character, options)

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(language)

Changes the current language and restarts the app

await session.setLanguage("fr")

If your app does not automatically handle language/locale changes, you would need to explicitly call restartApp for this to take effect. Some apps might also cache data in the previously used language. In these cases use reinstallApp to clear any previous cached data.

Parameters

Name	Type	Description
language	string	Language code

setLocation(lat, long)

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(url)

Opens a deep-link or web URL

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

Parameters

Name	Type	Description
url	string	The URL

shake()

Shakes device

await session.shake()

toggleSoftKeyboard()

Toggles the soft keyboard (iOS only)

await session.toggleSoftKeyboard()

biometry(match)

Simulate a matching fingerprint (Android 8+ only)

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

allowInteractions(enabled)

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

await session.allowInteractions(true/false)

launchApp(appId)

Launches the specified application using the provided appId.

If the app is already running, it will be brought to the foreground instead of being relaunched. If the app was originally launched with params or a launchUrl, these will also be passed with this method.

await session.launchApp(appId)

Parameters

Name	Type	Description
appId	string	Android: The app's package name / appId (e.g., com.example.app) or packageName/activityName. If no activity name is specified, it defaults to the main launch activity. iOS: The app's bundle identifier (e.g., com.example.app).

restartApp()

Restarts the app

await session.restartApp()

reinstallApp()

Reinstalls the app

await session.reinstallApp()

getUI()

Returns the UI as an XML string

await session.getUI()

Experimental The data structure of the response is subject to change

Returns an array of elements describing the current UI on the device.

const ui = await session.getUI()

/*
[
  { type: 'app', appId: 'com.my.app', children: [...] },
  { type: 'app', appId: 'com.apple.springboard', children: [...] }
]
*/

playAction(action, options)

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
options.timeout?	number	Amount of time in ms to wait for the action to succeed (default 10s)

playActions(actions, options)

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
options.timeout?	number	Amount of time in ms to wait for an action to succeed (default 10s)

waitForAnimations(options)

Waits until the there are no ongoing animations on the screen by waiting for the image to stabilize for at least 1 second.

await session.waitForAnimations(options)

Parameters

Name	Type	Description
options.imageThreshold?	number	The threshold for the amount of pixels (in %) that can change between frames before the image is considered to be stable. (default 0.001)
options.timeout?	number	The maximum amount of time (in ms) to wait for the image to stabilize. (default 10s)

adbConnection

Info for connecting to the Android devices via adb. Requires enableAdb to be true

{
    command: string;
    forwards: Array<{ destination: string; port: number }>;
    hash: string;
    hostname: string;
    port: number;
    user: string;
}

networkInspectorUrl

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

device

The current device

{
    type: string;
    name: string;
    osVersion: string;
    orientation: 'portrait' | 'landscape';
    screen: {
        width: number;
        height: number;
        devicePixelRatio?: number;
    };
    embed: {
        width: number;
        height: number;
        screen: {
            width: number;
            height: number;
            offset: {
                x: number;
                y: number;
            };
        };
    };    
}

app

The Appetize app for the session

{
  publicKey|buildId: string;
  name?: string;
  appDisplayName?: string;
  appVersionName?: string;
  appVersionCode?: string;
  bundle?: string;
  platform?: string;
  versionCode?: string;
  architectures?: string;
  iconUrl?: string;
  created?: string;
  apps?: AppetizeApp[];
}

path

The URL to the Appetizer server

token

The token of the Appetize session