Identity (CDID)

How the SDK identifies a device, merges anonymous activity into a known profile, and what happens at logout.

Every device that initializes the SDK is assigned a Customer Device ID (swanIdentifier, abbreviated CDID) — a stable UUID generated by the Swan backend on first registration and persisted locally for the lifetime of the install.

The CDID is the join key for every event a device ever sends. It is generated by the backend (not the device) so that two SDK instances can never collide on the same identifier.

Lifecycle

   App install
        │
        ▼
   Swan.init()  ─────►  POST /device/register  ─────►  CDID assigned
        │                                                  │
        │                                                  ▼
        ▼                                              persisted locally
   anonymous events ──────────────────────────────►  ingested under CDID
        │
        ▼
   Swan.identify("user-123")  ──►  POST /identify ──►  backend merges
                                                         anonymous + known
                                                         under one profile

States

State	When	Identity
Anonymous	After `init()`, before any `identify()` call	Events ingest under CDID only
Identified	After `Swan.identify(customerId, ...)`	Events ingest under CDID + customerId; prior anonymous activity merges into the customer profile on the backend
Logged out	After `Swan.logout()`	Identifier is rotated to a fresh CDID; future events ingest anonymously again

What `identify` actually does

The SDK sends a single /identify request with { swanIdentifier, customerId, attributes? }. The backend handles profile merge, deduplication, and attribution. The SDK doesn't compute or maintain any of that — it just owns the wire call.

This is intentional: you can call identify from any code path, any number of times, and the SDK won't accidentally double-count or merge profiles incorrectly. The merge logic is server-authoritative.

Logging out

Swan.logout() rotates the device to a fresh CDID. Practically:

Issues POST /device/register to get a new CDID
Clears the local cache of the prior CDID
Resets any in-memory super-properties (country, currency, etc.)

Events tracked after logout ingest under the new CDID, anonymously, until a subsequent identify call.

Why not just clear the customer ID? Rotating the CDID makes a shared-device handover (one phone passed between two users) behave correctly: the second user's anonymous activity won't merge into the first user's profile.

API reference

See the per-platform getting-started pages for the exact method signatures: Android, iOS, React Native, Web.