Identity & sessions

Nexus correlates everything through three identifiers. Getting them right is the single most important part of an integration.

IdentifyCopy Anchor Link

Call identify as soon as you know who the person is (after sign-in, or on app start when a session is restored). Before that, telemetry is anonymous but still tied to the device and session — and once you identify, the session is attached to the person.

await Nexus.instance.identify('user_123',
    email: 'ada@example.com', name: 'Ada', traits: {'plan': 'pro'});

Nexus.instance.distinctId; // 'user_123'
Nexus.instance.reset();    // on sign-out: forget the person, new session

Traits are stored on the person (the subject) and are available to targeting in in-app messages, surveys and push segments.

How a session is chosenCopy Anchor Link

• 30-minute idle timeout. A session with no activity for 30 minutes is ended (its end time is the last activity, not the sweep time).
• One running session per phone. The Flutter SDK mints a new sessionKey on every launch; when that new session starts, the device's previous session is ended. Browsers are exempt — tabs share a device but each has its own session.
• Realtime keeps sessions alive. An open realtime connection refreshes its session every 5 minutes.

Server-side identityCopy Anchor Link

Servers usually don't have a sessionKey — that's fine. Pass distinctId (directly, or through the SDK's ambient context / framework integration) and the backend attaches the server's telemetry to that person's most recent session. If your app forwards its session key to your API, pass it along as sessionKey for an exact match.