在 Kotlin Multiplatform SDK 中识别用户

本指南适用于拥有自定义身份验证系统的开发者。在这里，您将了解如何在 Adapty 中管理用户画像，以确保其与您现有的身份验证系统保持一致。

如何管理用户购买记录取决于您的应用的身份验证模式：

  • 如果您的应用不使用后端身份验证且不存储用户数据，请参阅匿名用户相关章节。
  • 如果您的应用已有（或将有）后端身份验证，请参阅已识别用户相关章节。 核心概念：
  • 用户画像 是 SDK 运行所必需的实体，由 Adapty 自动创建。
  • 用户画像可以是匿名的**（不含 customer user ID），也可以是已识别的（含 customer user ID）**。
  • 您提供 customer user ID 是为了将 Adapty 中的用户画像与您内部的身份认证系统进行关联。

以下是匿名用户与已识别用户的区别：

匿名用户已识别用户
购买管理通过商店级别恢复购买通过客户用户 ID 跨设备维护购买历史记录
用户画像管理每次重新安装生成新的用户画像跨会话和设备使用同一用户画像
数据持久性匿名用户的数据与应用安装绑定已识别用户的数据在应用安装间持久保存

匿名用户

如果你没有后端身份验证，无需在应用代码中处理身份验证：

  1. 当 SDK 在应用首次启动时被激活，Adapty 会为该用户创建一个新的用户画像。
  2. 当用户在应用内购买任何内容时，该购买记录会与其 Adapty 用户画像及其商店账户关联。
  3. 当用户重新安装应用或在新设备上安装时，Adapty 会在激活时创建一个新的匿名用户画像。
  4. 如果用户此前已在您的应用中进行过购买，默认情况下，SDK 激活时会自动从 App Store 同步其购买记录。 因此，对于匿名用户，每次安装都会创建新的用户画像，但这并不是问题，因为在 Adapty 分析中，你可以配置将什么视为新安装。

对于匿名用户，你需要按设备 ID 统计安装次数。在这种情况下，设备上的每次应用安装（包括重新安装）都会被计为一次安装。

备份恢复与重新安装的行为不同。默认情况下，当用户从备份恢复时，SDK 会保留缓存数据，不会创建新的用户画像。你可以通过 withAppleClearDataOnBackup 设置来配置此行为。了解更多。

已识别用户

在应用中识别用户有两种方式：

  • 登录/注册时： 如果用户在应用启动后才登录，请在用户完成身份验证时调用 identify()，并传入 customer user ID。

  • SDK 初始化时： 如果应用启动时已有存储的 customer user ID，可在调用 activate() 时直接传入。

默认情况下，当 Adapty 收到来自某个 Customer User ID 的购买记录，而该 ID 当前已与另一个 Customer User ID 关联时，访问等级将被共享，即两个用户画像均拥有付费访问权限。你可以将此设置配置为将付费访问权限从一个用户画像转移到另一个，或完全禁用共享。详情请参阅相关文档。

identify-diagram.webp

登录/注册时

如果你需要在应用启动后识别用户（例如，在用户登录或注册之后），可以使用 identify 方法来设置其 customer user ID。

  • 如果你之前从未使用过该 customer user ID，Adapty 会自动将其关联到当前用户画像。
  • 如果你之前已使用该 customer user ID 识别过用户，Adapty 将切换到与该 customer user ID 关联的用户画像。

每位用户的 Customer user ID 必须唯一。如果将该参数硬编码为固定值，所有用户将被视为同一人。

请等待 identify 完成（在其 onSuccess 回调中）后再调用其他 SDK 方法。并发调用可能会落在匿名用户画像上。详见 Kotlin Multiplatform SDK 的调用顺序。

Adapty.identify("YOUR_USER_ID") // 每位用户唯一
    .onSuccess {
        // 成功识别
    }
    .onError { error ->
        // 处理错误
    }

在 SDK 激活期间

如果在激活 SDK 时已知 customer user ID，可以直接在 activate 方法中传入，无需单独调用 identify。

如果已知 customer user ID，但在激活之后才设置，则意味着 Adapty 会在激活时先创建一个匿名用户画像，等你调用 identify 后才会切换到已有的用户画像。 您可以传入已有的客户用户 ID（之前使用过的），也可以传入新的。如果传入新的，激活时创建的新用户画像将自动关联到该客户用户 ID。

默认情况下，创建匿名用户画像不会影响分析看板，因为安装量是基于设备 ID 统计的。 设备 ID 代表应用在设备上的一次安装实例，仅在重新安装应用后才会重新生成。 它与此次安装是首次还是重复安装无关，也与是否使用了已有的客户用户 ID 无关。

创建用户画像（在 SDK 激活或登出时）、登录，或在不重新安装应用的情况下升级应用，均不会产生额外的安装事件。 如果您希望按唯一用户而非设备来统计安装量，请前往 App settings 并配置 Installs definition for analytics。

AdaptyConfig.Builder("PUBLIC_SDK_KEY")
    .withCustomerUserId("user123") // Customer user IDs must be unique for each user. If you hardcode the parameter value, all users will be considered as one.
    .build()

用户退出登录

如果您的应用有用户退出登录的按钮，请使用 logout 方法。

用户退出登录会为该用户创建一个新的匿名用户画像。

Adapty.logout()
    .onSuccess {
        // successful logout
    }
    .onError { error ->
        // handle the error
    }

要让用户重新登录应用，请使用 identify 方法。

允许未登录时购买

如果你的用户在登录之前和登录之后都可以进行购买，你需要确保他们登录后仍能保留访问权限：

  1. 当未登录用户完成购买时，Adapty 会将该购买绑定到其匿名用户画像 ID。
  2. 当用户登录账号后，Adapty 会切换到使用其已识别的用户画像。
    • 如果是新的 customer user ID（例如，购买发生在注册之前），Adapty 会将该 customer user ID 分配给当前用户画像，从而保留所有购买历史记录。
    • 如果是已存在的 customer user ID（该 customer user ID 已关联到某个用户画像），则需要在切换用户画像后获取实际的访问等级。你可以在完成身份识别后立即调用 getProfile，也可以监听用户画像更新，让数据自动同步。

后续步骤

恭喜！您已经在应用中成功实现了应用内购买逻辑！祝您的应用变现之路一切顺利！ 要充分发挥 Adapty 的价值，可以深入了解以下内容：

  • 测试：确保一切按预期运行
  • 集成：只需一行代码，即可与营销归因和分析服务完成集成
  • 设置自定义用户画像属性：为用户画像添加自定义属性并创建市场细分，从而针对不同用户发起 A/B 测试或展示不同的付费墙