在 Kotlin Multiplatform SDK 中识别用户

Adapty 会为每位用户创建一个内部用户画像 ID。但如果您有自己的认证系统，应该设置您自己的 Customer User ID。您可以在用户画像部分通过 Customer User ID 查找用户，也可以在服务端 API 中使用它，该 ID 还会被发送到所有集成渠道。

在配置时设置 Customer User ID

如果在配置时已有用户 ID，只需将其作为 customerUserId 参数传递给 .activate() 方法：


Adapty.activate(
    AdaptyConfig.Builder("PUBLIC_SDK_KEY")
        .withCustomerUserId("YOUR_USER_ID")
        .build()
).onSuccess {
    // successful activation
}.onError { error ->
    // handle the error
    }
}

想了解 Adapty SDK 如何集成到移动应用中的真实示例？请查看我们的示例应用，其中展示了完整的配置过程，包括显示付费墙、完成购买以及其他基本功能。

在初始化后设置用户 ID

如果在 SDK 初始化时没有用户 ID，可以随时通过 .identify() 方法进行设置。最常见的使用场景是在用户注册或登录之后，即用户从匿名状态切换为已认证状态时。


Adapty.identify("YOUR_USER_ID").onSuccess {
    // successful identify
}.onError { error ->
    // handle the error
}

请求参数：

  • Customer User ID（必填）：字符串类型的用户标识符。

重新提交重要用户数据

在某些情况下，例如用户再次登录其账户时，Adapty 服务器可能已经存储了该用户的信息。在这种情况下，Adapty SDK 会自动切换到新用户。如果你之前向匿名用户传递了任何数据（例如自定义属性或来自第三方网络的归因数据），需要为已识别的用户重新提交这些数据。

同样需要注意的是，识别用户后应重新请求所有付费墙和产品，因为新用户的数据可能有所不同。

登出与登录

您可以随时调用 .logout() 方法将用户登出：


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

之后可以使用 .identify() 方法让用户重新登录。

分配 appAccountToken（iOS）

iosAppAccountToken 是一个 UUID，用于将 App Store 交易与你的内部用户身份关联起来。 StoreKit 会将此 token 附加到每笔交易中，这样你的后端就能将 App Store 数据与用户进行匹配。

建议为每个用户生成一个稳定的 UUID，并在同一账号的不同设备上复用它。 这样可以确保购买记录和 App Store 通知始终与正确的用户绑定。 您可以通过两种方式设置 token——在 SDK 激活时或在识别用户时。

您必须始终将 iosAppAccountToken 与 customerUserId 一起传递。 如果只传递 token，它将不会包含在交易中。


// 配置时：
Adapty.activate(
    AdaptyConfig.Builder("PUBLIC_SDK_KEY")
        .withCustomerUserId(
            id = "YOUR_USER_ID",
            iosAppAccountToken = "YOUR_IOS_APP_ACCOUNT_TOKEN"
        )
        .build()
).onSuccess {
    // 激活成功
}.onError { error ->
    // 处理错误
}

// 或在识别用户时
Adapty.identify(
    customerUserId = "YOUR_USER_ID",
    iosAppAccountToken = "YOUR_IOS_APP_ACCOUNT_TOKEN"
).onSuccess {
    // 识别成功
}.onError { error ->
    // 处理错误
}

设置混淆账户 ID（Android）

Google Play 在某些场景下要求提供混淆账户 ID，以保护用户隐私和安全。这些 ID 可帮助 Google Play 在不暴露用户信息的情况下识别购买记录，对防范欺诈和数据分析尤为重要。

如果你的应用涉及敏感用户数据，或需要遵守特定隐私法规，就可能需要设置这些 ID。混淆 ID 让 Google Play 能够追踪购买行为，同时不会泄露真实的用户标识符。

您必须始终将 androidObfuscatedAccountId 与 customerUserId 一起传递。 如果仅传递混淆账号 ID，它将不会包含在交易中。


// 配置时：
Adapty.activate(
    AdaptyConfig.Builder("PUBLIC_SDK_KEY")
        .withCustomerUserId(
            id = "YOUR_USER_ID",
            androidObfuscatedAccountId = "YOUR_OBFUSCATED_ACCOUNT_ID"
        )
        .build()
).onSuccess {
    // 激活成功
}.onError { error ->
    // 处理错误
}

// 或在识别用户时
Adapty.identify(
    customerUserId = "YOUR_USER_ID",
    androidObfuscatedAccountId = "YOUR_OBFUSCATED_ACCOUNT_ID"
).onSuccess {
    // 识别成功
}.onError { error ->
    // 处理错误
}

跨设备用户识别

当 SDK 激活时，它会自动从 StoreKit (iOS) 或 Google Play Billing (Android) 读取用户现有的权益，并将其同步到 Adapty 后端。活跃订阅无需应用调用 restorePurchases，即可出现在 Adapty 用户画像中。

不会自动发生的是：识别新设备上的用户画像与原设备上的用户画像属于同一用户。Adapty 通过 Customer User ID 匹配用户画像，因此身份连续性取决于您使用什么作为 CUID。

Adapty 跨设备可检测的内容

您的配置Adapty 检测到的内容您需要做什么
Customer User ID = device_id（无应用登录）新设备获得不同的 CUID，因此拥有不同的用户画像。订阅通过 Access level updated 事件同步到新用户画像，但 subscription_started 不会触发——新用户画像被视为原始购买的继承者。基于 subscription_started 的分析将少计回归用户。使用稳定的账户 ID 作为 Customer User ID，以便回归用户能跨设备匹配到现有用户画像。
Customer User ID = 稳定账户 ID（每台设备均需登录）SDK 在 activate() 时自动同步订阅，identify() 通过 CUID 匹配现有用户画像。无需额外配置——身份和订阅均可自动解析。
Apple Family Sharing 继承者家庭成员仅通过 Access level updated 事件接收订阅——subscription_started 不会触发。监听 Access level updated。完整的事件矩阵请参见 Apple Family Sharing。
同一 Apple/Google 账户，不同应用内用户最先记录购买的用户画像成为父级。后续用户画像通过继承链查看订阅，并触发一次 Access level updated 事件。要求用户登录，然后选择适合您业务模型的共享模式。

在新设备上恢复购买

在付费墙上提供一个用户可主动触发的”恢复购买”按钮。Apple App Review（指南 3.1.1）要求提供此按钮，且当自动同步遗漏边缘情况时，它也可作为备用方案。该按钮应调用 SDK 中的 restorePurchases。

正常使用时，首次启动时无需通过代码调用 restorePurchases——SDK 已在 activate() 时执行了等效操作。仅在需要强制刷新收据检查时才使用代码调用，例如在 activate() 完成后调试访问等级缺失问题时。