AppSession

AppSession (also known as TpaSession in older versions) manages an active WebSocket connection (session) between an app instance and MentraOS Cloud. It handles event subscriptions, layout display, and connection management for a single user session.

import { AppSession } from '@mentra/sdk';

Constructor

constructor(config: AppSessionConfig)

Parameters:

config: Configuration options for the app session

Properties

events

Provides access to the EventManager for subscribing to real-time events.

readonly events: EventManager

layouts

Provides access to the LayoutManager for controlling the AR display.

readonly layouts: LayoutManager

settings

Provides access to the SettingsManager for reading and monitoring app settings.

readonly settings: SettingsManager

dashboard

Provides access to the DashboardAPI for sending content to the user’s dashboard.

readonly dashboard: DashboardAPI

The dashboard is a persistent UI surface that appears when users look up, allowing your app to display status updates and information even when other apps are active. See the Dashboard Tutorial for a quick start guide and the Dashboard API Reference for complete documentation.

capabilities

Provides access to the device capabilities of the connected smart glasses.

readonly capabilities: Capabilities | null

The capabilities object contains information about what hardware features are available on the connected device, allowing your app to adapt its behavior accordingly. See the Device Capabilities Guide for usage examples and the Capabilities Reference for complete type documentation.

logger

Provides access to a pre-configured Pino logger instance for session-specific logging.

readonly logger: Logger

The logger is automatically configured with session context including:

userId: The current user’s identifier
packageName: Your app’s package name
sessionId: The current session identifier
service: Set to ‘app-session’

Example:

protected async onSession(session: AppSession, sessionId: string, userId: string): Promise<void> {
  // The logger automatically includes session context
  session.logger.info('Session started successfully');
  session.logger.debug('Detailed debug information', { additionalData: 'value' });

  session.events.onTranscription((data) => {
    session.logger.debug('Received transcription', { text: data.text, isFinal: data.isFinal });

    if (data.text.includes('error')) {
      session.logger.warn('Potential error detected in transcription', { text: data.text });
    }
  });

  try {
    // Some operation that might fail
    await someRiskyOperation();
  } catch (error) {
    session.logger.error(error, 'Failed to perform operation');
    // Handle error appropriately
  }
}

Log Levels:

session.logger.debug(): Detailed debugging information
session.logger.info(): General information about app operation
session.logger.warn(): Warning conditions that don’t stop execution
session.logger.error(): Error conditions that should be investigated

Structured Logging:

session.logger.info('User performed action', {
  action: 'button_press',
  buttonId: 'main',
  timestamp: new Date(),
  metadata: { /* additional context */ }
});

Event Handling Methods

onTranscription()

Registers a handler for real-time speech transcription events.

onTranscription(handler: (data: TranscriptionData) => void): () => void

Parameters:

handler: Callback function to process TranscriptionData

Returns: An unsubscribe function to remove the handler

onHeadPosition()

Registers a handler for head position change events (e.g., ‘up’, ‘down’).

onHeadPosition(handler: (data: HeadPosition) => void): () => void

Parameters:

handler: Callback function to process HeadPosition data

Returns: An unsubscribe function to remove the handler

onButtonPress()

Registers a handler for hardware button press events on the glasses.

onButtonPress(handler: (data: ButtonPress) => void): () => void

Parameters:

handler: Callback function to process ButtonPress data

Returns: An unsubscribe function to remove the handler

onPhoneNotifications()

Registers a handler for notifications received from the connected phone.

onPhoneNotifications(handler: (data: PhoneNotification) => void): () => void

Parameters:

handler: Callback function to process PhoneNotification data

Returns: An unsubscribe function to remove the handler

Subscription Methods

Informs the MentraOS Cloud that this app session wants to receive events of the specified type.

subscribe(type: StreamType): void

Parameters:

type: The StreamType to subscribe to

on()

Generic method to subscribe to any data stream type. Use specific on<EventType> methods where available.

on<T extends StreamType>(
  event: T,
  handler: (data: StreamDataTypes[T]) => void
): () => void

Parameters:

event: The StreamType to listen for
handler: Callback function to process the data associated with the stream type

Returns: An unsubscribe function to remove the handler

Connection Methods

connect()

Establishes the WebSocket connection to MentraOS Cloud for this session.

connect(sessionId: string): Promise<void>

Parameters:

sessionId: The unique identifier for this session (provided by the SESSION_REQUEST webhook)

Returns: A promise that resolves upon successful connection and authentication, or rejects on failure

disconnect()

Gracefully closes the WebSocket connection and cleans up resources for this session.

disconnect(): void

Settings Methods

getSettings()

Retrieves all current application settings for this user session.

getSettings(): AppSettings

Returns: A copy of the current AppSettings

getSetting()

Retrieves the value of a specific application setting by its key.

getSetting<T>(key: string): T | undefined

Parameters:

key: The key of the setting to retrieve

Returns: The value of the setting, or undefined if not found or not set

setSubscriptionSettings()

Configures the app session to automatically manage subscriptions based on changes to specific settings.

setSubscriptionSettings(options: {
  updateOnChange: string[];
  handler: (settings: AppSettings) => StreamType[];
}): void

Parameters:

options: Configuration object
- options.updateOnChange: An array of setting keys that should trigger a subscription update when their value changes
- options.handler: A function that takes the current AppSettings and returns an array of StreamType subscriptions that should be active

Configuration

interface AppSessionConfig {
  /** Your unique app identifier (e.g., 'org.company.appname'). */
  packageName: string;

  /** Your API key for authentication. */
  apiKey: string;

  /** The WebSocket URL provided by MentraOS Cloud. Defaults to 'ws://localhost:8002/app-ws'. */
  mentraOSWebsocketUrl?: string;

  /** Whether the session should automatically attempt to reconnect if the connection drops. Defaults to `false`. */
  autoReconnect?: boolean;

  /** Maximum number of reconnection attempts if `autoReconnect` is true. Default: 0 (no limit). */
  maxReconnectAttempts?: number;

  /** Initial delay (in ms) before the first reconnection attempt. Delay increases exponentially. Defaults to 1000. */
  reconnectDelay?: number;
}

Getting Started

Core Concepts

SDK Reference

AppSession

AppSession

Constructor

Properties

events

layouts

settings

dashboard

capabilities

logger

Event Handling Methods

onTranscription()

onHeadPosition()

onButtonPress()

onPhoneNotifications()

Subscription Methods

on()

Connection Methods

connect()

disconnect()

Settings Methods

getSettings()

getSetting()

setSubscriptionSettings()

Configuration

​AppSession

​Constructor

​Properties

​events

​layouts

​settings

​dashboard

​capabilities

​logger

​Event Handling Methods

​onTranscription()

​onHeadPosition()

​onButtonPress()

​onPhoneNotifications()

​Subscription Methods

​subscribe()

​on()

​Connection Methods

​connect()

​disconnect()

​Settings Methods

​getSettings()

​getSetting()

​setSubscriptionSettings()

​Configuration

AppSession

Constructor

Properties

events

layouts

settings

dashboard

capabilities

logger

Event Handling Methods

onTranscription()

onHeadPosition()

onButtonPress()

onPhoneNotifications()

Subscription Methods

subscribe()

on()

Connection Methods

connect()

disconnect()

Settings Methods

getSettings()

getSetting()

setSubscriptionSettings()

Configuration