Skip to main content

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:

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:

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:

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:

Returns: An unsubscribe function to remove the handler

Subscription Methods​

subscribe()​

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

subscribe(type: StreamType): void

Parameters:

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;
}