Identify users

Xee keeps a profile for every user of your app. If your app has accounts, give Xee your own user ID and an app account token, so the user's access follows them to any device they sign in on.

Profiles and customer user IDs

• The SDK creates a profile on activation. You never create one yourself.
• A profile is anonymous until it has a customer user ID: your own ID for the user, from your login system.
• One customer user ID belongs to one profile in an app. Xee never moves an ID from one profile to another, and a profile's ID cannot be changed once set.
• A customer user ID is 1 to 255 characters. Spaces at either end are removed.

How Xee links purchases to a profile

Xee does not take the app's word for a purchase. It learns about a subscription from Apple, either by asking Apple when the SDK reports a purchase or a restore, or from the signed App Store Server Notifications Apple sends. Either way, it then has to decide which profile owns the subscription. It picks the first of these that applies:

1. The profile whose app account token the transaction carries. The token is a UUID the SDK passes to StoreKit with the purchase, and Apple repeats it in everything it says about the transaction.
2. The profile the subscription already belongs to. A later notification for a subscription Xee has recorded keeps it where it is, even though it carries no token or another one.
3. The profile that reported it. This applies to the SDK's purchase and restore reports, when the app has an In-App Purchase key.

A subscription never moves away from a profile that owns it.

• Every profile has a token, anonymous ones too. The server creates it with the profile and returns it with the profile, as storeAccountToken on XeeProfile.
• The SDK attaches the profile's token to every purchase. Only when it has no profile from the server yet does it fall back to the token you passed, and then to the customer user ID if that ID is a UUID.
• So an anonymous user's purchase belongs to their anonymous profile, and unlocks access there once Xee has checked it with Apple or received Apple's notification.
• A purchase with no token, such as one made without Xee or through another purchase SDK before Xee, has nobody to match by token. It attaches to the profile that restores it with Xee.restorePurchases(), and later notifications for it keep it there. See Migrate from Adapty or another SDK.
• If you pass a token to identify or in the configuration, Xee stores it as the profile's token. The one exception is a profile that has already bought something: it keeps the token its purchases carry, and still takes the customer user ID.
• A token belongs to one profile. Passing a token that another profile already uses is refused.

Use a UUID that stays the same for the user. Generate it once when the account is created and keep it with the account on your backend. If your customer user IDs are UUIDs, you can pass the ID itself as the token: UUID(uuidString: user.id).

Identify at activation

If the user is signed in when the app starts, pass their ID to Xee.activate. The SDK then creates the profile with that ID, without an anonymous profile first. To send the app account token too, call Xee.identify(_:withAppAccountToken:) right after, as in Identify after login below.

try await Xee.activate(withAPIKey: "xee_YOUR_SDK_KEY", customerUserId: user.id)

user.id stands for the value from your own account system. Never hardcode the customer user ID: every install would share one profile.

This only works this way on a device where the SDK has no profile yet, such as the first launch after install. If the device already has a profile from an earlier launch, the SDK keeps that profile and the rules in Identify after login below apply.

Identify after login

When the user signs in or signs up after the app has started, call Xee.identify(_:withAppAccountToken:).

do {
    try await Xee.identify(user.id, withAppAccountToken: user.appAccountToken)
} catch {
    // error is a XeeError
}

What happens depends on the ID:

• An ID Xee has not seen: it is attached to the current anonymous profile, which becomes the customer's profile. The token you pass is stored as the profile's token, unless the profile has already bought something: then it keeps its token, so those purchases stay matched, and still takes the ID.
• An ID that already belongs to another profile: the SDK switches to that profile, the one the customer had on their other devices. Anything the anonymous profile on this device bought stays on that anonymous profile. It is not merged into the customer's profile.
• A token that another profile already uses: the server refuses it and identify throws an error. The app keeps the profile it had. See Troubleshooting & errors.

Wait for identify to finish before you call other Xee methods. Calls made while the profile is changing can fail, or land on the old profile. Afterwards, read the user's access again with Xee.getProfile(); see Check subscription status.

Log users out

When the user signs out, call Xee.logout(). The SDK then starts a new anonymous profile on this device.

do {
    try await Xee.logout()
} catch {
    // error is a XeeError
}

Calling logout while the profile is still anonymous is an error.

Users on several devices

A user is recognised across devices only by their customer user ID, so use an ID that belongs to the account, not to the device.

Keep a Restore purchases button on your paywall anyway: App Review expects one. See Make purchases.