Comment on page

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', {
    publicKey: '{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"
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()
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
{
  publicKey: string;
  name?: string;
  appDisplayName?: 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()
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
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")
Some apps might cache data in the previously used language. 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 (iOS only)
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)
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: string;
  name?: string;
  appDisplayName?: 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
​

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

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.

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"
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

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

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

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.

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

Name	Type	Description
format?	`"buffer" \| "base64"`	The format of the screenshot data to return. Defaults to `buffer`

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

Name	Type	Description
text	`string`	Text to type

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`

Name	Type	Description
language	`string`	Language code

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.

Name	Type	Description
`url`	`string`	The URL

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)

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)

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)

Trace Viewer

Next - Sample Use Cases

Impersonation

Last modified 2mo ago

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