無料アイテム

どのように動作するか

無料アイテムとは、ユーザーが仮想通貨や実際通貨を使わずに手に入れることができるアイテムの一種です。以下が含まれます：

• 仮想アイテム
• バンドル
• 仮想通貨パッケージ

無料アイテムは、認証されたユーザーだけが利用できます。認証されていないユーザーは、無料アイテムのカタログのみを表示できます。

使用例：

• プロジェクトにとって重要な日（例えば、プロジェクト設立の日など）に無料アイテムを配布し、ユーザーロイヤリティに報いることができます。
• ストアでゲームのスターターパックを無料で配布することで、新しいユーザーをゲームに引き付けることができます。

ユーザーがすでに持っている場合は、ユニークなアイテムの無料配布を制限することができます。

使用に適した方

• すでにインゲームストアを持っていて、新しいタイプの製品 — 無料アイテムをセットアップしたいパートナー向け。
• 現在のユーザーロイヤルティを高めたい、または新しいプレーヤーを引き付けたいパートナー向け。

統合フロー

1. 次の方法で無料アイテムを作成します：
   • アドミンページ経由
   • APIコール経由
2. ストアをセットアップする。
3. ユーザーの注文状況を取得します。

アドミンページ経由で作成する

1. アドミンページであなたのプロジェクトを開きます。
2. サイドメニューでストアをクリックします。
3. 仮想アイテムペインで、構成するをクリックします。
4. +をクリックし、ドロップダウンリストからアイテムを作成するを選択します。
5. 以下を指定します：
   • 画像
   • SKU
   • アイテムが属するべき1つまたは複数のグループ
   • 名前
   • 説明
   • アイテム属性：消耗品、非消耗品、期間限定品など。
6. 価格を設定ブロックで、無料アイテムを選択します。
7. 特定のユーザーにアイテムの購入を制限したい場合は、1ユーザーがこのアイテムを購入できる回数を制限するのトグルをオンに切り替えて、回数を指定してください。
8. ストアにアイテムを表示する場合は、ストアでアイテムを表示するのトグルをオンに設定します。
9. アイテムを作成するをクリックします。

APIコール経由で作成する

1. 無料アイテムを作成するには、管理サブセクションからAPIコールを使用します。
   • 仮想通貨の場合 — 仮想アイテムを作成する
   • 通貨パッケージの場合 — 仮想通貨パッケージを作成する
   • バンドルの場合 — バンドルを作成する
   アイテムの作成または編集時には、リクエスト本文にis_free = trueを渡してください。
2. 特定のユーザーにアイテムの利用を制限したい場合は、アイテムを作成または編集する任意のAPIメソッドを呼び出し、limits.per_userパラメータの値を指定します。

ストアをセットアップする

迅速な購入

{
  "method": "POST",
  "url": "https://mybestgame.com/xsolla/notification",
  "body": {
    "items": [
      {
        "sku": "gift_direct_game_reward-supercoin",
        "type": "virtual_currency",
        "is_pre_order": false,
        "quantity": 500,
        "amount": "0",
        "promotions": [

        ]
      },
      {
        "sku": "package-500_supercoin",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "0",
        "promotions": [

        ]
      },
      {
        "sku": "xsolla-giveaway_offer_11_14_22",
        "type": "bundle",
        "is_pre_order": false,
        "quantity": 1,
        "amount": "0",
        "promotions": [

        ]
      }
    ],
    "notification_type": "order_paid",
    "order": {
      "id": 12345678,
      "mode": "default",
      "currency_type": "unknown",
      "currency": null,
      "amount": "0",
      "status": "paid",
      "platform": "xsolla",
      "comment": null,
      "invoice_id": null,
      "promotions": [

      ]
    },
    "user": {
      "external_id": "1234567812345678",
      "email": null
    }
  },
  "headers": {
    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  "type": "webhook_payment",
  "callback_parameters": {
    "order_id": 12345678
  }
}

• リスナーがウェブフックを正しく受け入れて処理した場合 — HTTP応答コード200または204。
• 予期したエラーが発生した場合 — HTTP応答コード4xx。
お知らせ
この場合、アイテムはプレイヤーのインベントリに追加され、注文はエクソーラ側で成功としてマークされます。
• リスナーは、サーバー上の一時的なエラーのために5xxHTTP応答コードを返すこともあります。この場合、エクソーラアラートサービスは再試行イメカニズムを使用します。

カート購入

ユーザーがカート購入を使用する場合：

• ユーザーのカートに有料アイテムと無料アイテムの両方が含まれている場合は、標準の特定のカートの全アイテムを対象とした注文を作成すると現在のカートの全アイテムを含む注文を作成するAPIを呼び出して注文を作成します。ユーザーは、ペイステーションの支払いフォームを通じて注文の支払いを行います。
• ユーザーのカートに無料のアイテムしか含まれていない場合は、無料カートで注文を作成するおよび特定の無料カートで注文を作成するAPIを呼び出して、無料のカートを取得します。この場合、支払いインターフェースは使用されず、支払いは自動的に処理されます。

ウェブフックの例は、迅速的な購入の例と同様です。