初期残高を付与する

すべてのプロファイルは、あらゆる通貨において残高 0 からスタートします。リンクされたプロダクトは、購入または更新時にのみクレジットを付与します。そのため、何も購入していないユーザーは自動的にクレジットを受け取ることはありません。

新規ユーザーに初期残高を付与することもできます。ウェルカムボーナス、無料トライアルの利用枠、またはライフのセットなどです。ユーザーを識別した後、サーバーサイドAPIを通じてバックエンドから付与してください。

新規ユーザーへの残高付与

まずユーザーを特定する: 残高は1つのプロファイルに紐付いており、別のプロファイルに移動することはありません。そのため、プロファイルに顧客ユーザーIDが設定された後にのみクレジットを付与してください。アプリ内でSDKを使ってユーザーを特定するか（ユーザーの特定を参照）、バックエンドからサーバーサイドAPIを通じて行ってください。

匿名プロファイルへの付与は、ここで最もよくある間違いです。匿名プロファイルは1つのアプリインストールに紐付いているため、ユーザーがアプリを再インストールしたり別のデバイスで開いたりすると、クレジットが失われます。詳しくは残高、プロファイル、デバイスをご覧ください。

クレジットを付与する: 正の 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 のようなタグを付けると、トランザクション履歴で付与を簡単に識別でき、自分のレポートで購入クレジットと区別するのに役立ちます。

データベースに付与記録を残す: このユーザーが初回残高を受け取ったという事実をデータベースに保存し、再サインインやジョブの再試行で二重付与が発生しないようにします。次のセクションでは、この記録が必要な理由を説明します。

正確に1回だけ付与する

ユーザーが初期残高を受け取ったかどうかの信頼できる情報源は、あなた自身のデータベースです。十分に見えても実際には不十分なアプローチが2つあります。

Idempotency-Key は1回の呼び出しを保護するものであり、1人のユーザーを保護するものではありません: 同じキーでリクエストをリトライすると、再付与ではなく元の結果が返されるため、タイムアウト後に安全にリトライできます。Adapty は各キーをプロファイルごとに最大1時間記憶します。それ以降は同じキーで再付与が行われるため、数ヶ月後にそのヘッダーでユーザーが初回残高をすでに受け取ったかどうかを判断することはできません。新しい付与を行うたびに新しいキーを生成してください。
先に残高を確認しても何も証明できません: 残高が0の場合、クレジットが一度も付与されていないか、付与されたが全て消費済みかのどちらかです。仮想通貨残高の一覧取得では、この2つを区別することはできません。

自分のレコードを確認してからAPIを呼び出し、レスポンスが成功したらレコードを書き込んでください。

既存ユーザーへのバックフィル

通貨を作成すると、既存のすべてのプロファイルの残高は0からスタートします。また、プロダクトとのリンクは以降の購入にのみ適用されます。現在のユーザーに初期残高を付与するには、バックエンドから一括バックフィルを実行してください。

付与対象のカスタマーユーザーIDを自分のデータベースから収集します。
各ユーザーに対して、上記のように仮想通貨トランザクションの作成を呼び出します。一括エンドポイントは存在しません。1リクエストで1つのプロファイルに付与され、1回のリクエストでそのプロファイルに対して最大20種類の通貨を処理できます。
処理中は前のセクションで説明したユーザーごとの記録を常に保持してください。これにより、ジョブを中断して再開した際に二重付与を防げます。
アプリごとに1分あたり600リクエストのレート制限を超えないようにしてください。制限を超えたリクエストは rate_limited エラーで失敗するため、ジョブをスロットルしてエラーになったユーザーをリトライしてください。

リーチしたいユーザー（アクティブユーザーや課金ユーザーなど）のみをバックフィルしてください。APIを通じて付与されたクレジットに有効期限はないため、今付与した残高はユーザーが使い切るまでプロファイルに残り続けます。

次のステップ

残高を消費してランタイムで読み取る: バーチャル通貨クイックスタート
ユーザーの保有量を確認してすべての変更を監査する: バーチャル通貨残高