---
name: session-lifecycle
description: Session state, stream state, pause and resume behavior, and device availability monitoring
---

# Session Lifecycle (Android)

Manage session and stream state in DAT SDK integrations.

Create a `Session` with `Wearables.createSession(...)`, start it, then attach capabilities such as camera streaming. Session lifecycle and stream lifecycle are related but distinct.

## Session states

| State | Meaning | App action |
|-------|---------|------------|
| `IDLE` | Session created, not started yet | Call `session.start()` |
| `STARTING` | Connecting to the device | Show loading UI |
| `STARTED` | Session active and ready for capabilities | Add or use capabilities |
| `PAUSED` | Session temporarily suspended | Keep state, wait for resume or stop |
| `STOPPING` | Session is shutting down | Stop user work and wait |
| `STOPPED` | Session ended | Release resources and create a new session if needed |

## Observe session state

```kotlin
val session = Wearables.createSession(AutoDeviceSelector()).getOrElse { error ->
    throw IllegalStateException(error.description)
}
session.start()

lifecycleScope.launch {
    session.state.collect { state ->
        when (state) {
            DeviceSessionState.STARTED -> onStarted()
            DeviceSessionState.PAUSED -> onPaused()
            DeviceSessionState.STOPPED -> onStopped()
            else -> Unit
        }
    }
}
```

## Stream state

Camera streaming has its own state flow after you attach a stream:

```text
STOPPED -> STARTING -> STARTED -> STREAMING -> STOPPING -> STOPPED -> CLOSED
```

```kotlin
lifecycleScope.launch {
    stream.state.collect { state ->
        // React to camera capability state changes
    }
}
```

## Common transitions

The SDK may pause or stop a session when:

- Another experience takes over the device
- The user removes or folds the glasses
- Bluetooth connectivity drops
- The user unregisters the app or revokes needed access

## Pause and resume

When a session is paused:

- The device connection may remain active
- Attached capabilities stop doing useful work
- Your app should wait for the next observed session state instead of trying to force a restart

## Device availability

```kotlin
lifecycleScope.launch {
    Wearables.devices.collect { devices ->
        // Update the list of available devices
    }
}
```

Use `Wearables.devices` and device metadata to decide when it is sensible to create a new session after a stop.

## Checklist

- [ ] Handle all `DeviceSessionState` values you care about
- [ ] Observe stream state separately from session state
- [ ] Release resources only after stop or close
- [ ] Recreate sessions after terminal stops instead of reusing dead ones
- [ ] Surface typed `SessionError` and `StreamError` failures

## Links

- [Session lifecycle documentation](https://wearables.developer.meta.com/docs/lifecycle-events)
- [Android API reference](https://wearables.developer.meta.com/docs/reference/android/dat/0.7)