Начисление начального баланса

Каждый профиль начинается с нулевого баланса по каждой валюте, а привязанные продукты начисляют кредиты только при покупке или продлении подписки. Таким образом, пользователь, который ничего не купил, никогда не получает кредиты автоматически.

Вы всё равно можете давать новым пользователям начальный баланс: приветственный бонус, пробный период или набор жизней. Начисляйте его через серверный API с бэкенда — после того как идентифицируете пользователя.

Предоставьте баланс новому пользователю

1. Сначала идентифицируйте пользователя: баланс привязан к одному профилю и не переносится на другой, поэтому начисляйте кредиты только после того, как профилю присвоен customer user ID. Идентифицируйте пользователя в приложении через SDK (см. Идентификация пользователей) или через серверный API.

Предоставление кредитов анонимному профилю — самая распространённая ошибка. Анонимные профили привязаны к одной установке приложения, поэтому пользователь теряет кредиты при переустановке или на другом устройстве. Подробнее — в разделе Балансы, профили и устройства.

2. Начислите кредиты: вызовите Create virtual currency transaction с положительным значением amount. В этом примере начисляется 500 токенов:

   curl -X POST https://api.adapty.io/api/v2/server-side-api/vc/transactions/ \
     -H "Authorization: Api-Key {your secret key}" \
     -H "adapty-customer-user-id: user-42" \
     -H "Idempotency-Key: 6f2c0b34-9c3a-4f5e-8a1d-2b7e5c9d0a11" \
     -H "Content-Type: application/json" \
     -d '{
           "items": [{"currency_code": "TOKENS", "amount": 500}],
           "metadata": {"reason": "initial_balance"}
         }'

Ответ возвращает новый баланс:

{
  "transaction_id": "3a9f8e21-5d4c-4b7a-9e01-8c6d2f4b1a37",
  "balances": [
    { "code": "TOKENS", "name": "Tokens", "balance": 500, "held": 0, "available": 500 }
  ]
}

Кредиты, выданные таким образом, никогда не истекают — в отличие от периодических кредитов, привязанных к подписке.

Поле metadata необязательно. Тег вроде reason: initial_balance позволяет легко найти выдачу в истории транзакций и отделить её от кредитов, начисленных за покупку, в собственных отчётах.

3. Зафиксируйте выдачу в своей базе данных: сохраните информацию о том, что этот пользователь уже получил начальный баланс, чтобы повторный вход или повторная попытка задания не выдали его дважды. В следующем разделе объясняется, почему эта запись необходима.

Дайте его ровно один раз

Ваша база данных — это единственный источник истины о том, получил ли пользователь начальный баланс. Два подхода, которые кажутся достаточными, на самом деле таковыми не являются:

• Idempotency-Key защищает один вызов, а не одного пользователя: Повторный запрос с тем же ключом вернёт исходный результат, а не начислит снова — поэтому один и тот же вызов можно безопасно повторить после таймаута. Adapty хранит каждый ключ до одного часа в рамках профиля. После этого тот же ключ снова начислит кредиты, так что заголовок не поможет узнать спустя месяцы, получал ли пользователь начальный баланс. Генерируйте новый ключ для каждого нового начисления.
• Чтение баланса ничего не доказывает: Баланс 0 означает либо то, что пользователю никогда не начислялись кредиты, либо то, что они были начислены и потрачены. Список балансов виртуальной валюты не позволяет отличить один случай от другого.

Поэтому проверяйте собственную запись перед вызовом API и записывайте результат после успешного ответа.

Пополнение баланса у существующих пользователей

Когда вы создаёте валюту, у всех существующих профилей баланс начинается с 0, а привязка продуктов действует только для будущих покупок. Чтобы начислить текущим пользователям стартовый баланс, выполните единоразовое пополнение через ваш бэкенд.

1. В своей базе данных соберите ID пользователей, которым нужно начислить валюту.
2. Для каждого вызовите Create virtual currency transaction, как показано выше. Массового эндпоинта нет: один запрос — один профиль, при этом один запрос может охватывать до 20 валют для этого профиля.
3. По мере выполнения ведите запись по каждому пользователю из предыдущего раздела, чтобы можно было остановить задачу и продолжить её без повторного начисления.
4. Соблюдайте ограничение в 600 запросов в минуту на приложение. Запрос сверх лимита завершится ошибкой rate_limited, поэтому регулируйте нагрузку и повторяйте запросы для неудавшихся пользователей.

Следующие шаги

• Списывайте баланс и читайте его в рантайме: Быстрый старт с виртуальной валютой.
• Смотрите, что есть у пользователя, и отслеживайте каждое изменение: Баланс виртуальной валюты.