---
title: "虚拟货币余额"
description: "在用户画像中查看虚拟货币余额，并在事件历史记录中回顾每次余额变动。"
---

:::link
主要文章：[虚拟货币](virtual-currencies)
:::

[Profiles/CRM](profiles-crm) 中的每个用户画像都会显示该用户的虚拟货币余额，以及每次变动的历史记录。

## 在用户画像中查看余额 \{#view-balances-in-a-user-profile\}

打开用户的[用户画像](https://app.adapty.io/profiles/users)。**Virtual currency** 卡片列出了该用户持有的所有货币。

每行显示：

- 货币**代码**，例如 `COINS`。
- 当前**余额**，以整数表示。

余额会随着用户赚取、消费或获得积分而更新。余额不能低于 0：如果某笔交易试图消费超过用户持有量，则会以 `insufficient_balance` 失败，且不会产生任何变动。没有余额记录的用户画像将显示空白卡片。

如需在自己的代码中读取余额，请调用服务端 API 中的 [List virtual currency balances](api-adapty/operations/listVirtualCurrencyBalances)。

## 在事件历史中查看余额变更 \{#review-balance-changes-in-the-event-history\}

每次余额变更都会显示在用户画像的事件历史中，最新记录排在最前面。每条记录会注明变更内容及受影响的货币。

历史记录中包含三种虚拟货币事件：

- **Virtual currency credited**：通过购买、续订或试用开始获得的积分。
- **Virtual currency transaction**：通过服务端 API 调用对余额进行了充值或扣减。
- **Virtual currency expired**：在计费周期结束时或订阅终止时，到期积分被重置。

每条记录会列出所有发生变更的货币：

- **Virtual currency**：货币名称和代码，例如 `Gold Coins (COINS)`。
- **Amount**：带符号的变动金额——正数表示增加，负数表示扣减。
- **Balance after**：变动生效后的货币余额。

一个事件可以同时更改多种货币——例如，一笔[交易](api-adapty/operations/createVirtualCurrencyTransaction)可以同时扣减一种货币并增加另一种货币，从而实现两者之间的转换。

## 余额、用户画像与设备 \{#balances-profiles-and-devices\}

余额始终归属于某一个[用户画像](profiles-crm)，且不会转移到其他用户画像。Adapty 不会像[在用户账户之间共享访问等级](profiles-crm#sharing-paid-access-between-user-accounts)那样，在用户画像之间共享或转移余额。

实际上，这意味着：

- **已识别用户**：客户用户 ID 始终解析到同一个用户画像，因此用户在每台登录设备上看到的余额都相同。
- **匿名用户**：匿名用户画像可以获得和消费积分，但仅存在于单一设备上。当同一用户在另一台设备上打开应用且未登录时，Adapty 会创建一个余额为零的新匿名用户画像。

因此，若要跨设备运行虚拟货币系统，需要识别您的用户。您可以通过 SDK 在应用代码中识别用户（请参阅快速入门中的[识别用户](ios-quickstart-identify)），也可以通过[服务端 API](getting-started-with-server-side-api) 从后端进行识别。

晚期识别用户也有其自身的隐患：如果用户在匿名状态下积累了积分，随后使用已属于另一个用户画像的 customer user ID 登录，设备会切换到该用户画像及其余额，匿名状态下获得的积分将留在旧用户画像上，无法访问。如果 customer user ID 是新的，它会绑定到当前用户画像，用户可以保留其余额。为了安全起见，请在用户获得或购买积分之前完成身份识别。

在[服务端 API](getting-started-with-server-side-api) 调用中，使用 `adapty-profile-id` 或 `adapty-customer-user-id` 请求头来标识用户画像——两者都会解析到同一个用户画像。对于匿名用户画像，请使用 `adapty-profile-id`。