> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mentraglass.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AppSession

> AppSession manages a WebSocket session between your app and MentraOS Cloud, providing events, layouts, settings, dashboard access, capabilities, and logging.

# 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.

```typescript theme={null}
import { AppSession } from '@mentra/sdk';
```

## Constructor

```typescript theme={null}
constructor(config: AppSessionConfig)
```

**Parameters:**

* `config`: [Configuration](#configuration) options for the app session

## Properties

### events

Provides access to the [`EventManager`](/app-devs/reference/managers/event-manager) for subscribing to real-time events.

```typescript theme={null}
readonly events: EventManager
```

### layouts

Provides access to the [`LayoutManager`](/app-devs/reference/managers/layout-manager) for controlling the AR display.

```typescript theme={null}
readonly layouts: LayoutManager
```

### settings

Provides access to the [`SettingsManager`](/app-devs/reference/managers/settings-manager) for reading and monitoring app settings.

```typescript theme={null}
readonly settings: SettingsManager
```

### dashboard

Provides access to the [`DashboardAPI`](/app-devs/reference/dashboard-api#interface-dashboardapi) for sending content to the user's dashboard.

```typescript theme={null}
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](/dashboard) for a quick start guide and the [Dashboard API Reference](/app-devs/reference/dashboard-api) for complete documentation.

### capabilities

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

```typescript theme={null}
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](/capabilities) for usage examples and the [Capabilities Reference](/app-devs/reference/interfaces/capabilities) for complete type documentation.

### logger

Provides access to a pre-configured [Pino](https://getpino.io) logger instance for session-specific logging.

```typescript theme={null}
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:**

```typescript theme={null}
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:**

```typescript theme={null}
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.

```typescript theme={null}
onTranscription(handler: (data: TranscriptionData) => void): () => void
```

**Parameters:**

* `handler`: Callback function to process [`TranscriptionData`](/app-devs/reference/interfaces/event-types#transcriptiondata)

**Returns:** An unsubscribe function to remove the handler

### onHeadPosition()

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

```typescript theme={null}
onHeadPosition(handler: (data: HeadPosition) => void): () => void
```

**Parameters:**

* `handler`: Callback function to process [`HeadPosition`](/app-devs/reference/interfaces/event-types#headposition) data

**Returns:** An unsubscribe function to remove the handler

### onButtonPress()

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

```typescript theme={null}
onButtonPress(handler: (data: ButtonPress) => void): () => void
```

**Parameters:**

* `handler`: Callback function to process [`ButtonPress`](/app-devs/reference/interfaces/event-types#buttonpress) data

**Returns:** An unsubscribe function to remove the handler

### onPhoneNotifications()

Registers a handler for notifications received from the connected phone.

```typescript theme={null}
onPhoneNotifications(handler: (data: PhoneNotification) => void): () => void
```

**Parameters:**

* `handler`: Callback function to process [`PhoneNotification`](/app-devs/reference/interfaces/event-types#phonenotification) data

**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.

```typescript theme={null}
subscribe(type: StreamType): void
```

**Parameters:**

* `type`: The [`StreamType`](/app-devs/reference/enums#streamtype) to subscribe to

### on()

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

```typescript theme={null}
on<T extends StreamType>(
  event: T,
  handler: (data: StreamDataTypes[T]) => void
): () => void
```

**Parameters:**

* `event`: The [`StreamType`](/app-devs/reference/enums#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.

```typescript theme={null}
connect(sessionId: string): Promise<void>
```

**Parameters:**

* `sessionId`: The unique identifier for this session (provided by the [`SESSION_REQUEST`](/app-devs/reference/interfaces/webhook-types#sessionwebhookrequest) 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.

```typescript theme={null}
disconnect(): void
```

## Settings Methods

### getSettings()

Retrieves all current application settings for this user session.

```typescript theme={null}
getSettings(): AppSettings
```

**Returns:** A copy of the current [`AppSettings`](/app-devs/reference/interfaces/config-types#appsettings)

### getSetting()

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

```typescript theme={null}
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.

```typescript theme={null}
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`](/app-devs/reference/interfaces/config-types#appsettings) and returns an array of [`StreamType`](/app-devs/reference/enums#streamtype) subscriptions that should be active

## Configuration

```typescript theme={null}
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;
}
```