Skip to Content
Passage PlatformConceptsSessions

Sessions

A session is the real-time connection between a developer’s worker and the user’s device.

What is a session?

Sessions are stateful actors that relay browser commands between two WebSocket connections: the worker (your backend or a hosted automation) and the client (the mobile SDK’s webview).

Session lifecycle

Sessions follow a state machine:

  • created — Session initialized, tokens generated
  • pending — First connection established (either client or worker)
  • active — Both client and worker connected
  • complete — Session finished successfully
  • failed — Session terminated with an error
  • expired — Session timed out

Tokens

Each session generates separate tokens for the client and worker roles. Tokens are validated on WebSocket upgrade.

Injection scripts

The session actor generates JavaScript injection scripts and delivers them to the client SDK in the server.hello message. The SDK injects these into the webview at document start. Built-in scripts include:

  • telemetry — Navigation and page lifecycle events
  • network — XHR/fetch interception for network telemetry
  • console — Console method interception
  • interaction — User interaction events (click, input, scroll) — enabled only for debug/recording sessions

This decouples telemetry logic from SDK release cycles — scripts are versioned server-side.

Persistence

All session state is persisted in a database. There is no in-memory state to lose — the session actor can be evicted and resumed transparently.

Next steps

Last updated on
QuickstartCommands