Comment on page
API reference
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 |
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> |
Listens for an event of the given name
client.on(event, data => {
console.log(data)
})
Event | Data Type | Description |
---|---|---|
{
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. | |
string | An error has occurred | |
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 | A new session has started either by the client or user clicking "Tap to Play" | |
app | Record<string, any> | The currently loaded Appetize app |
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> |
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> |
Returns the current config
const config = client.getConfig()
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;
};
};
};
}
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[];
}
Listens for an event of the given name
session.on(event, data => {
console.log(data)
})
Event | Data Type | Description |
---|---|---|
Record<string, any> | A user action has been recorded. This can be played back later with playAction.
Requires record to be set to true | |
{
buffer: Uint8Array, codec: 'aac'
} | ||
string | An error has occurred on the session | |
{ secondsRemaining: number } | Session is about to timeout due to inactivity. | |
Record<string, any> | User has interacted with the device. | |
{ message: string } | ||
Record<string, any> | Intercepted network request or responses.
| |
'portrait' | 'landscape' | The device has changed orientation | |
{
buffer: Uint8Array,
width: number,
height: number,
codec: string
} |
Ends the session
await session.end()
Rotates the device 90 degrees
await session.rotate('right')
Parameters
Name | Type | Description |
---|---|---|
direction | "left" | "right" | The direction to rotate |
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 |
Sends a heartbeat to the server, resetting the inactivity timer
await session.heartbeat()
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 | |
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 |
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 | |
target.duration? | number | Duration of the swipe |
target.gesture | string | function | |
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 |
Types the given text on the device
await session.type("hello")
Parameters
Name | Type | Description |
---|---|---|
text | string | Text to type |
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 | |
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 |
Sets the simulated location of the device.
await setLocation(-33.924434, 18.418391)
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. |
Opens a deep-link or web URL
await session.openUrl("https://appetize.io")
Parameters
Name | Type | Description |
---|---|---|
url | string | The URL |
Shakes device (iOS only)
await session.shake()
Toggles the soft keyboard (iOS only)
await session.toggleSoftKeyboard()
Simulate a matching fingerprint (Android 8+ only)
await session.biometry({
match: true/false
})
Enables or disables all interactions on the device. Default is true.
await session.allowInteractions(true/false)
Restarts the app
await session.restartApp()
Reinstalls the app
await session.reinstallApp()
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: [...] }
]
*/
Play an automation Action or array of Actions.
await session.playAction(action)
Parameters
Name | Type | Description |
---|---|---|
action | Record<string, any> | |
options.timeout? | number | Amount of time in ms to wait for the action to succeed (default 10s) |
Plays an array of actions.
await session.playActions(actions)
Parameters
Name | Type | Description |
---|---|---|
actions | Array<Record<string, any>> | |
options.timeout? | number | Amount of time in ms to wait for an action to succeed (default 10s) |
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) |
{
command: string;
forwards: Array<{ destination: string; port: number }>;
hash: string;
hostname: string;
port: number;
user: string;
}
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;
};
};
};
}
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[];
}
The URL to the Appetizer server
The token of the Appetize session
Last modified 2mo ago