session-lifecycle

Session Lifecycle (iOS)

Guide for managing device session states in DAT SDK integrations.

Overview

The DAT SDK runs work inside sessions. Meta glasses expose two experience types:

• Device sessions — sustained access to device sensors and outputs
• Transactions — short, system-owned interactions (notifications, "Hey Meta")

Your app observes session state changes — the device decides when to transition.

Session states

State	Meaning	App action
idle	Session created but not started	Call start() when ready
starting	Session is connecting to the device	Show connecting state
started	Session active and ready for capabilities	Add or resume work
paused	Temporarily suspended by the device	Hold work, may resume
stopping	Session is cleaning up	Wait for terminal state
stopped	Session inactive and terminal	Free resources, create a new session to restart

Observing session state

let session = try Wearables.shared.createSession(deviceSelector: AutoDeviceSelector(wearables: Wearables.shared))
try session.start()

Task {
    for await state in session.stateStream() {
        switch state {
        case .started:
            // Confirm UI shows session is live
        case .paused:
            // Keep connection, wait for started or stopped
        case .stopped:
            // Release resources, allow user to restart
        default:
            break
        }
    }
}

DeviceSession exposes both shapes: stateStream() / errorStream() as AsyncStream, and statePublisher / errorPublisher as listener-token Announcers. Pick one per call site; subscribe before calling start() so no initial transition is missed.

Session errors

errorStream() and errorPublisher emit DeviceSessionError. Handle .noEligibleDevice (no matching device yet), .sessionAlreadyExists, .capabilityAlreadyActive, the thermal/battery cases (.thermalCritical, .thermalEmergency, .peakPowerShutdown, .batteryCritical), and .datAppOnTheGlassesUpdateRequired, which is delivered as a one-shot event and should open Wearables.shared.openDATGlassesAppUpdate().

start() uses typed throws, so you can catch the specific case:

do throws(DeviceSessionError) {
    try session.start()
} catch .datAppOnTheGlassesUpdateRequired {
    showGlassesAppUpdatePrompt()
} catch {
    showError(error.localizedDescription)
}

Stream state transitions

A Stream is a capability attached to a started DeviceSession:

stopped → waitingForDevice → starting → streaming → paused → stopped

guard let camera = try session.addCamera(config: StreamConfiguration()) else { return }
let stream = camera.stream

let token = stream.statePublisher.listen { state in
    Task { @MainActor in
        // React to state changes
    }
}

Common transitions

The device changes session state when:

• User performs a system gesture that opens another experience
• Another app starts a device session
• User removes or folds the glasses (Bluetooth disconnects)
• User removes the app from Meta AI companion app
• Connectivity between companion app and glasses drops

Pause and resume

When a session is paused:

• The device keeps the connection alive
• Streams stop delivering data
• The device may resume by returning to started

Your app should not attempt to restart while paused — wait for started or stopped.

Device availability

Monitor device availability to know when sessions can start:

Task {
    for await deviceIds in Wearables.shared.devicesStream() {
        // deviceIds is [DeviceIdentifier]; resolve details with deviceForIdentifier(_:)
    }
}

A DeviceSelector also reports availability directly. AutoDeviceSelector and SpecificDeviceSelector both expose activeDevice and activeDeviceStream(), which yields nil when no eligible device is available:

let selector = AutoDeviceSelector(wearables: Wearables.shared)
Task {
    for await deviceId in selector.activeDeviceStream() {
        hasActiveDevice = deviceId != nil
    }
}

Key behaviors:

• Closing hinges disconnects Bluetooth → forces stopped
• Opening hinges restores Bluetooth but does not restart sessions
• Start a new session after the device becomes available again

Implementation checklist

• Handle all relevant session states (started, paused, stopped)
• Monitor device availability before starting work
• Release resources only after stopped
• Don't infer transition causes — rely only on observable state
• Don't restart during paused — wait for system to resume or stop

Links

• Session lifecycle documentation