Clarify uuid requirement for app account token

[dcrawbuck]

Clarify that the userId must be a valid UUID on iOS for appAccountToken to ensure consistency with Apple's requirements and prevent identifier mismatches in purchase notifications.

The appAccountToken in App Store Server Notifications will differ from the userId passed to identify if the userId is not a valid UUID, as StoreKit silently rejects non-UUIDs and the SDK falls back to the anonymous alias UUID. This update explicitly warns users about this behavior and provides guidance.

---

Linear Issue: SW-3485

 

---

Note

Clarifies that userId must be a UUID on iOS for appAccountToken, documents fallback to alias UUID if not, and adds guidance and example.

• iOS Docs:
  • Warning added in content/docs/ios/sdk-reference/identify.mdx: userId must be a UUID for appAccountToken; non-UUIDs are rejected and SDK falls back to the alias UUID; recommend v4 UUID.
• Identity Management (content/shared/user-management/identity-management.mdx):
  • Table update: Adds non-UUID userId scenario (StoreKit rejection → alias UUID fallback).
  • Warning block: Explains UUID requirement and potential identifier mismatch in App Store Server Notifications.
  • Swift example: Shows generating and using a UUID for identify.

^{Written by Cursor Bugbot for commit d4d89bd. This will update automatically on new commits. Configure here.}

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[linear]

SW-3485 [docs] clarify that user id needs to be valid UUID for appAccountToken

page(s): https://superwall.com/docs/ios/quickstart/user-management

Changes Needed

• https://discord.com/channels/1342529924027645962/1342529924702933069/1380330686548017173

  Duncan @ Superwall When calling superwall.identify; if we pass in an id that's not a valid UUID, then it can't be used as the appAccountToken (https://developer.apple.com/documentation/appstoreserverapi/appaccounttoken) -- i'm not sure what happens in this case, but I think Superwall silently drops the id, which can cause lots of confusion, since the IAP callbacks will have an appAccountToken that's different from what was passed into identify. I think it might be better to throw an error if the ID is not a valid uuid; or at least have a warning / some option

  The docs do touch on it a bit; https://superwall.com/docs/identity-management; but it basically seems like the id must be a UUID for Apple (if you want to get useful data from the appstoreconnect IAP webhook)

repo=superwall/docs