Background session killed

Fix a Meta Ray-Ban session that dies when your app backgrounds — a missing Android foreground service, missing iOS background modes, or an OS low-memory kill.

Your app works in the foreground, but the glasses session dies the moment the app is backgrounded — transcripts stop, the assistant goes quiet, capture fails. On a phone, a glasses session is a long-running Bluetooth + capture workload, and both Android and iOS aggressively suspend backgrounded apps. Keeping a session alive in the background is opt-in and platform-specific.

Symptoms

Voice / transcription / the assistant stops the instant you switch apps or the screen locks
A backgrounded capture returns NotConnected or silently produces nothing
Android logcat shows a SecurityException at startForeground(...)
The session comes back when you foreground the app, then dies again on background

Android — you need a foreground service

A backgrounded Android app can't hold the mic open without a foreground service. Extentos ships one (GlassesForegroundService, foregroundServiceType="microphone"), but you have to wire three things:

Declare the permissions (app-owned): FOREGROUND_SERVICE and, on Android 14+, FOREGROUND_SERVICE_MICROPHONE. getPermissions derives these from your continuous-capture capabilities. A missing FOREGROUND_SERVICE_MICROPHONE on 14+ is the most common cause of the SecurityException.
Grant RECORD_AUDIO at runtime before starting the service. Starting a microphone-type FGS without the grant crashes at service-create time on Android 14+.
Start it from an Activity, not Application.onCreate — GlassesForegroundService.start(context) from your permission-grant callback; stop it with .stop(context) when done.

Camera-in-the-background needs a camera-type service you declare yourself (subclass GlassesForegroundService + a <service android:foregroundServiceType="camera" />) — see Background sessions.

iOS — you need the right background modes

iOS keeps a backgrounded app alive only within declared UIBackgroundModes. The glasses connection needs bluetooth-central, bluetooth-peripheral, and external-accessory; add audio when you stream the mic. generateConnectionModule(platform: "ios") emits these and validateIntegration checks them. iOS background execution is more constrained than an Android foreground service — validate on a real device before relying on it.

OS-level kills (the honest limit)

Even wired correctly, the OS can reclaim a backgrounded app under memory pressure or aggressive battery optimization (some Android OEMs are especially aggressive). This isn't an Extentos bug — it's the platform. Design for it:

Treat a background disconnect as expected: branch on connection.state → Disconnected and re-establish on foreground (see Handle disconnects).
Keep the foreground-service notification meaningful so the user — and the OS — can see the session is active.
Don't assume indefinite background life; persist anything important as you go.

Confirm the fix

validateIntegration flags a missing iOS UIBackgroundModes entry or Android FGS permission before runtime.
In a simulator session, getEventLog({ sessionId, filter: "lifecycle" }) shows the Disconnected cause when the session drops.

Background sessions — the full setup guide
Handle disconnects — reconnect cleanly when a session drops

Error reference

Every typed error the Extentos SDK can return — ConnectError, CaptureError, AudioError, TransportError, the ExtentosError umbrella, and the Meta-DAT DeviceSessionError — with their payload fields and meaning. Lifecycle operations return ExtentosResult<T, E> with these concrete failure variants rather than throwing; pattern-match them. Generated from the Rust core.

Background sessions

Keep a Meta Ray-Ban session alive when your app backgrounds — the Android foreground service for mic, iOS background modes, and which capabilities survive.

Glasses won't connect

Fix common first-connection failures on Meta Ray-Ban — no pairing dialog, session won't start, the DAT auth callback never fires, or an immediate disconnect.