revenuecat-identify-user

revenuecat-identify-user：将 RevenueCat 连接到你的身份验证系统

当用户希望调用 RevenueCat SDK 的 logIn / logOut，让应用用户与 RevenueCat 订阅者保持一致时，请使用此技能。此技能不涵盖 SDK 初始设置（请参阅 integrate-revenuecat）、购买（revenuecat-purchase-flow）或权限门控（revenuecat-entitlements-gate）。

1. 检测平台

检查工作目录，并按从上到下的顺序选择第一个匹配项：

1. React Native：package.json 中包含 react-native-purchases 条目，或将 react-native 列为依赖项 → 阅读 platforms/react-native.md。如果 expo 也是依赖项，请注明这是一个 Expo 项目。
2. Flutter：项目根目录中存在 pubspec.yaml → 阅读 platforms/flutter.md。
3. Kotlin Multiplatform：build.gradle.kts 中包含 kotlin { … } 多平台源集代码块，或依赖 com.revenuecat.purchases:purchases-kmp* → 阅读 platforms/kmp.md。
4. Android（原生）：build.gradle(.kts) 应用了 com.android.application（且不是 KMP）→ 阅读 platforms/android.md。
5. iOS（原生）：项目根目录中存在 Package.swift、*.xcodeproj、*.xcworkspace 或 Podfile → 阅读 platforms/ios.md。

如果匹配多个项目（例如 Flutter 项目中包含 ios/ 文件夹），请选择最外层的项目，也就是拥有构建配置的项目。如果仍无法确定，请询问用户要配置哪个平台。

2. 通用概念（适用于所有平台）

• 默认使用匿名身份。 调用 logIn 之前，RevenueCat 会分配一个以 $RCAnonymousID: 为前缀的稳定匿名 ID。匿名状态下进行的购买会在首次使用真实 appUserID 调用 logIn 时关联到该 ID，因此允许用户在登录前购买不会导致“购买丢失”。
• 切勿将电子邮件、电话号码或顺序数据库 ID 用作 appUserID。 请使用稳定的不透明值，例如后端的用户 UUID 或用户 ID 的哈希值。RevenueCat 会将该 ID 视为不透明字符串，且之后很难更改。
• 在身份验证系统确认会话后调用 logIn。 不要尝试提前调用 logIn。典型的触发时机是身份验证状态监听器检测到用户已登录。logIn 会同时返回用户当前的 CustomerInfo 和一个 created: Boolean，用于告知该用户是否是全新的 RevenueCat 客户。
• logOut 仅适用于已识别用户。 当 SDK 使用匿名 ID 时调用 logOut，所有 SDK 都会抛出错误（PurchasesErrorCode.LogOutWithAnonymousUserError 或 iOS 对应错误）。请通过自己的“已登录”标志进行判断。
• 恢复购买不等于登录。 restorePurchases() 会向商店请求当前收据，并将其关联到当前 RevenueCat 用户，但不会切换身份。如果用户在新设备上登录，请先调用 logIn(appUserID)；仅当用户还希望从当前商店账户获取收据时，才调用 restorePurchases()。
• 切换账户时，先调用 logOut，再调用 logIn。 如果应用允许用户退出后以其他身份重新登录，请先调用 logOut() 并等待其完成，然后再调用 logIn(newId)。不要直接通过再次调用 logIn 来切换身份，否则两个 ID 会被关联到一起。
• 先完成配置。 调用 logIn / logOut 前，必须先运行 Purchases.configure(…)。否则 SDK 会抛出错误。

3. 实现

阅读与检测结果匹配的平台文件：

• platforms/ios.md
• platforms/android.md
• platforms/kmp.md
• platforms/flutter.md
• platforms/react-native.md

每个平台文件都会展示如何在典型的身份验证状态观察器中接入 logIn 和 logOut 调用。

4. 验证

满足以下条件前，不要声称身份同步有效：

1. 在 RevenueCat 控制面板中，你的测试用户的 Customer 页面显示的 appUserID 与后端使用的相同，而不是 $RCAnonymousID: 占位符。
2. 退出登录会将 ID 重置为全新的匿名用户；以不同账号登录会切换到该账号的购买记录（如果是新账号，则显示无购买记录）。
3. 匿名状态下完成购买后再调用 logIn，购买记录仍关联到已登录用户（通过别名关联，而非丢失）。
4. 即使已处于匿名状态，调用 logOut 时也会得到妥善处理，不会导致崩溃或被静默视为成功。