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

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