在 Capacitor SDK 中识别用户

用户购买记录的管理方式取决于你的应用采用的身份验证模型：

  • 如果你的应用不使用后端身份验证，也不存储用户数据，请参阅匿名用户章节。
  • 如果你的应用已有（或计划引入）后端身份验证，请参阅已识别用户章节。

核心概念：

  • 用户画像是 SDK 正常运行所必需的实体，由 Adapty 自动创建。它可以是匿名的（不含 customer user ID），也可以是已识别的（含 customer user ID）。
  • Customer user ID 是可选标识符，由你创建，用于将你的用户与其 Adapty 用户画像关联起来。

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

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

匿名用户

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

  1. 当 SDK 在应用首次启动时激活，Adapty 会为该用户创建一个新的用户画像。
  2. 当用户在应用内购买任何内容时，该购买记录会与其 Adapty 用户画像及商店账户关联。
  3. 当用户重新安装应用或在新设备上安装时，Adapty 会在激活时创建一个新的空用户画像。
  4. 如果用户之前已在你的应用中完成过购买，默认情况下，其购买记录会在 SDK 激活时自动从 App Store 同步。

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

已识别用户

  • 如果某个用户画像还没有 customer user ID（即用户尚未登录），当你发送 customer user ID 时，它会与该用户画像关联。
  • 如果是重新安装、登录，或从新设备安装，且你之前已经发送过该用户的 customer user ID，则不会创建新的用户画像，而是切换到与该 customer user ID 关联的已有用户画像。

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

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

  • 在 SDK 激活时： 如果应用启动时已有存储的 customer user ID，请在调用 activate() 时一并传入。

默认情况下，当 Adapty 收到一笔来自某个 Customer User ID 的购买时，若该 Customer User 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 时，请将其与用户数据一起保存，这样当用户在新设备上登录或重新安装应用时，你可以发送相同的 ID。

在调用其他 SDK 方法之前，请始终 await identify。并发调用会产生 #3006 profileWasChanged 错误，或者落到匿名用户画像上。详见 Capacitor SDK 的调用顺序。

try {
  await adapty.identify({ customerUserId: "YOUR_USER_ID" });
  // successfully identified
} catch (error) {
  // handle the error
}

在 SDK 激活期间

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

如果你知道用户 ID，但在激活之后才设置，那么 SDK 激活时 Adapty 会先创建一个新的空用户画像，等到你调用 identify 后才会切换到已有的用户画像。 您可以传入现有的 customer user ID（即您之前使用过的 ID），也可以传入一个新的。如果传入新 ID，激活时创建的新用户画像将自动与该 customer user ID 关联。

如需将创建的空用户画像排除在看板分析之外，请前往 App settings，配置 Installs definition for analytics。

await adapty.activate({
  apiKey: "YOUR_PUBLIC_SDK_KEY",
  params: {
    customerUserId: "YOUR_USER_ID"
  }
});

退出登录用户

如果您有供用户退出登录的按钮，请使用 logout 方法。这将为用户创建一个新的匿名用户画像 ID。

try {
  await adapty.logout();
  // successful logout
} catch (error) {
  // handle the error
}

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

允许未登录状态下购买

如果你的用户在登录前后均可进行购买，则无需额外配置： 工作原理如下：

  1. 当未登录用户完成购买时，Adapty 会将其绑定到该用户的匿名用户画像 ID。
  2. 当用户登录账户后，Adapty 会切换到使用其已识别的用户画像。
    • 如果是已有的 customer user ID（该 customer user ID 已关联到某个用户画像），Adapty 会自动同步其交易记录。
    • 如果是新的 customer user ID（例如，购买发生在注册之前），Adapty 会将该 customer user ID 分配给当前用户画像，从而保留完整的购买历史。