# Session ## Methods ### on() Listens for an event of the given name ```typescript session.on(event, data => { console.log(data) }) ``` | Event | Data Type | Description | | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

action

| [RecordedAction](https://docs.appetize.io/javascript-sdk/api-reference/types/recordedaction) |

A user action has been recorded. This can be played back later with playAction.

Requires record to be set to true

| |

appLaunch

| `void` | App launch event occurred. | |

audio

|

{
buffer: Uint8Array, codec: 'aac',
duration: number
}

|

Audio frames of the current session.

Requires audio to be set to true

| |

error

| `{ message: string }` | An error has occurred on the session | |

firstFrameReceived

| `void` | First video frame received. | |

inactivityWarning

| `{ secondsRemaining: number }` |

Session is about to timeout due to inactivity.

Any user interaction or a heartbeat will reset the timeout.

| |

interaction

| [UserInteraction](https://docs.appetize.io/javascript-sdk/api-reference/types/userinteraction) | User has interacted with the device. | |

log

| `{ message: string }` |

Debug log from the device

Requires debug to be set to true

| |

network

| [NetworkRequest](https://docs.appetize.io/javascript-sdk/api-reference/types/networkrequest) \| [NetworkResponse](https://docs.appetize.io/javascript-sdk/api-reference/types/networkresponse) |

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 ```typescript await session.end() ``` ### rotate() Rotates the device 90 degrees ```typescript 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 ```typescript 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 ```typescript await session.heartbeat() ``` ### tap(target, options) Taps on the screen at the given position, coordinate or element ```typescript 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](https://docs.appetize.io/automation/touch-interactions#targeting-elements) | | 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 ```typescript 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](https://docs.appetize.io/automation/touch-interactions#targeting-elements) | | target.duration? | `number` | Duration of the swipe | | target.gesture | `string \| function` | The gesture of the swipe. See [swipe](https://docs.appetize.io/automation/touch-interactions#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 ```typescript await session.type("hello") ``` **Parameters** | Name | Type | Description | | ---- | -------- | ------------ | | text | `string` | Text to type | {% hint style="warning" %} 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. {% endhint %} {% hint style="info" icon="lightbulb-exclamation-on" %} **Tip:** Need to delete a character after typing? Use `keypress`: ```js await session.keypress('Backspace') ``` {% endhint %} ### keypress(character, options) Sends a single key press to the device ```typescript await session.keypress("a") ``` **Parameters** | Name | Type | Description | | -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | key | `string` |

Key to send to the device ('a', 'b', etc.)

Also accepts text-editing keys: Backspace

And hardware keys:
HOME
Android Only:
VOLUME\_UP
VOLUME\_DOWN
ANDROID\_KEYCODE\_MENU
LOCK\_SCREEN
UNLOCK\_SCREEN
iOS Only:
TOGGLE\_SCREEN\_LOCK

| | options.shift? | `boolean` | | ### setAppearance(appearance) (iOS 13+ and Android 10+) Sets dark or light mode UI. ```typescript await session.setAppearance("dark") ``` **Parameters**
NameType
appearance"dark" | "light"
### setLanguage(language) Changes the current language and restarts the app ```typescript await session.setLanguage("fr") ``` {% hint style="warning" %} If your app does not automatically handle language/locale changes, you would need to explicitly call [restartApp](#restartapp) for this to take effect.\ \ Some apps might also cache data in the previously used language. In these cases use [reinstallApp](#reinstallapp) to clear any previous cached data. {% endhint %} **Parameters** | Name | Type | Description | | -------- | -------- | ------------- | | language | `string` | Language code | ### setLocation(lat, long) Sets the simulated location of the device. ```typescript 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 ```typescript await session.openUrl("https://appetize.io") ``` **Parameters** | Name | Type | Description | | ----- | -------- | ----------- | | `url` | `string` | The URL | ### shake() Shakes device ```typescript await session.shake() ``` ### toggleSoftKeyboard() Toggles the soft keyboard (iOS only) ```typescript await session.toggleSoftKeyboard() ``` ### biometryEnrollment(isEnrolled) Sets the biometry enrollment status (*iOS Only*) ```typescript await session.biometryEnrollment(true/false) ``` ### biometry(match) Simulate a matching fingerprint (Android 8+ only) or Face ID (iOS) 
await session.biometry({
    match: true/false
})
### allowInteractions(enabled) Enables or disables all interactions on the device. Default is true. ```typescript await session.allowInteractions(true/false) ``` ### adbShellCommand(command) Executes an `adb shell` command on the device (Android only) ```typescript await session.adbShellCommand("am start -a android.intent.action.VIEW -d https://appetize.io/") ``` ### launchApp(appId) Launches the specified application using the provided `appId`. {% hint style="info" %} 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. {% endhint %} ```typescript 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 ```typescript await session.restartApp() ``` ### reinstallApp() Reinstalls the app ```typescript await session.reinstallApp() ``` ### getUI() Returns the UI as an XML string ```typescript await session.getUI() ``` {% hint style="warning" %} **Experimental**\ The data structure of the response is subject to change {% endhint %} {% tabs %} {% tab title="Old Engine" %} Returns an array of elements, with app and system content separated into two sections. ```json [ { "type": "app", "appId": {running app}, "children": [ ... ] // Your app content }, { "type": "app", "appId": "com.apple.springboard", "children": [ ... ] // Springboard (system UI) content } ] ``` {% endtab %} {% tab title="New Engine" %} A single combined hierarchy is returned, representing what’s actually visible to the user. ```json [ { "type": "app", "appId": {possible appId}, "children": [ ... ] // All visible content on screen (e.g. Springboard/Navigation etc. related content too) } ] ``` {% endtab %} {% endtabs %} ### addMedia(file) {% hint style="info" %} The maximum file size for uploading media is **50 MB**. {% endhint %} Upload media to the device. ```typescript await session.addMedia(file) ``` Platform specific format support applies. See the [Media - Supported File Types documentation](https://docs.appetize.io/features/media#supported-files) for supported file types on Android and iOS. ### findElement(selector) Returns an element that matches the selector. See [Targeting Elements](https://docs.appetize.io/automation/touch-interactions#targeting-elements). *This is useful for waiting until an element appears.* ```javascript const element = await session.findElement({ attributes: { text: "Home" } }) ``` If multiple elements are found it will return the first element. ### findElements(selector) Returns an array of all elements matching that selector. See [Targeting Elements](https://docs.appetize.io/automation/touch-interactions#targeting-elements). ```javascript const elements = await session.findElements({ attributes: { accessibilityLabel: 'Like post' } }) ``` ### playAction(action, options) Play an automation Action or array of Actions. ```typescript await session.playAction(action) ``` **Parameters** | Name | Type | Description | | ---------------- | --------------------- | -------------------------------------------------------------------- | | action | `Record` | Actions emitted from the [`session.on('action')`](#on-1) event | | options.timeout? | `number` | Amount of time in ms to wait for the action to succeed (default 10s) | ### playAction**s(actions, options)** Plays an array of actions. ```typescript await session.playActions(actions) ``` **Parameters** | Name | Type | Description | | ---------------- | ---------------------------- | ------------------------------------------------------------------- | | actions | `Array>` | Actions emitted from the [`session.on('action')`](#on-1) 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. ```typescript 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)

| ### waitForEvent(event, options) Waits for an event to occur ```typescript const networkEvent = await session.waitForEvent('network') const requestEvent = await session.waitForEvent('network', event => { // resolves only when this condition is met return event.type === 'request' }) ``` **Parameters** | Name | Type | Description | | ------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------- | | event | `string` | One of the session [events](#on-session-1). | | options.timeout? | `number \| null` | The maximum time (in milliseconds) to wait for the event to be emitted. | | options.predicate? | `(data: T) => boolean` | The predicate condition to be satisfied, otherwise the function will continue to wait for the event. | ### waitForTimeout(timeout) Waits for the given time to elapse (in ms) ```typescript await session.waitForTimeout(5000) ``` **Parameters** | Name | Type | Description | | ------- | -------- | ------------------------ | | timeout | `number` | Timeout in milliseconds. | ### waitUntilReady() Waits until the session is fully initialised and ready for use. ## Properties ### adbConnection Info for connecting to the Android devices via adb. Requires [enableAdb](https://docs.appetize.io/configuration#enableadb) to be true. See [AdbConnectionInfo](https://docs.appetize.io/javascript-sdk/api-reference/types/adbconnectioninfo). ### app The Appetize app for the session, if applicable. See [AppetizeApp](https://docs.appetize.io/javascript-sdk/api-reference/types/appetizeapp). ### config The [config](https://docs.appetize.io/javascript-sdk/configuration) applied to the current session. See [SessionConfig](https://docs.appetize.io/javascript-sdk/api-reference/types/sessionconfig). ### device The current device. See [DeviceInfo](https://docs.appetize.io/javascript-sdk/api-reference/types/deviceinfo). ### networkInspectorUrl The URL to chrome dev tools to inspect network logs. Requires [proxy](https://docs.appetize.io/configuration#proxy) to be set to `intercept`. ### path The URL to the Appetizer server. ### token The token of the Appetize session. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.appetize.io/javascript-sdk/api-reference/session.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.