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