User Identity

By default, Grantiva identifies devices anonymously. You can optionally associate a user identity for:

Feature flags targeted by user properties
Feedback that persists across devices for the same user
Analytics grouped by user rather than device

Identify a user

await grantiva.identify(UserContext(
    userId: "user_123",
    properties: [
        "plan": "premium",
        "country": "US",
        "beta_tester": "true"
    ]
))

Or with just a user ID:

await grantiva.identify("user_123")

Both overloads are async — identify clears the feedback and flag caches so the next read re-fetches under the new identity. All services (feedback, flags) automatically use this context after identification. Caches are cleared on identity change so services re-fetch with the new context.

UserContext

UserContext(
    userId: String,
    properties: [String: String] = [:]
)

Field	Type	Description
`userId`	`String`	Stable unique identifier for the user
`properties`	`[String: String]`	Custom key-value pairs for targeting

Properties are used for feature flag targeting and segmentation. Common examples:

"plan": "free", "pro", "business"
"country": "US", "DE", "JP"
"beta_tester": "true"
"company_size": "50"

Separate from user identity, setSubjectId links the device to a sharing unit (family/household) for subscription entitlement claims (SDK 2.1.0+, Enterprise):

// A stable UUID string your app mints per household
grantiva.setSubjectId(familyId.uuidString)

// When the device leaves the household
grantiva.clearSubjectId()

// Read back
let current = grantiva.subjectId

Unlike identify, these three are synchronous and do not clear any caches. Set the subject id before calling validateAttestation(). The id rides the next attestation or token refresh; the backend then projects custom_claims.subscription into the JWT for every device sharing the same id. Use the identical value as the StoreKit appAccountToken and Stripe client_reference_id. Don’t confuse the two:

	`identify(_:)`	`setSubjectId(_:)`
Scopes	The individual user	The paying household
Drives	Flag targeting, feedback, analytics	The `subscription` JWT claim
Cardinality	One per person	One per sharing unit — same value on every member’s device

Device context (automatic)

The SDK automatically collects device context — you don’t need to set this:

let device = grantiva.currentUserContext?.device

device?.appBundleId    // "com.example.MyApp"
device?.appVersion     // "1.4.0"  — your app's CFBundleShortVersionString
device?.appBuildNumber // "412"    — your app's CFBundleVersion
device?.deviceModel    // "iPhone15,2"
device?.osName         // "iOS" or "macOS"
device?.osVersion      // "18.0"
device?.locale         // "en_US"
device?.timezone       // "America/Chicago"
device?.sdkVersion     // "2.1.0"  — the Grantiva SDK version
device?.environment    // "device" or "simulator"

DeviceContext is captured when you construct the UserContext, so it reflects the app and OS at that moment. You can’t set these fields yourself; your own properties take precedence if you use the same key.

Clear identity

Call on user logout:

await grantiva.clearIdentity()

Services fall back to device-based identity. Feedback submitted before logout remains associated with the user.

Read current identity

grantiva.currentUserId       // String? — current user ID
grantiva.currentUserContext   // UserContext? — full context

Getting Started

SDKs

CLI

Concepts

Push

Dashboard

Identify a user

UserContext

Device context (automatic)

Clear identity

Read current identity

​Identify a user

​UserContext

​Subject ID (subscription sharing unit)

​Device context (automatic)

​Clear identity

​Read current identity

Identify a user

UserContext

Subject ID (subscription sharing unit)

Device context (automatic)

Clear identity

Read current identity