無料アイテム

仕組み

無料アイテムとは、仮想通貨や実際通貨を消費することなく、ユーザーが獲得できるアイテムです。 無料アイテムは、以下のシナリオで利用可能です：

• ゲーム内アイテムの販売 — 仮想アイテム、仮想通貨パッケージ、およびバンドル
• ゲームキーによるゲームおよびDLCの販売

• 周年記念などの特別な日やプロジェクトの節目に、ロイヤルティ向上を目的として提供される無料アイテム。
• ロイヤリティ報酬として、すでにベースゲームを購入済みのユーザーに提供される無料のアドオン。
• ゲームへの新規ユーザーを誘致するために、ウェブストアで提供される無料スターターパック。

無料アイテムのセットアップ

パブリッシャーアカウントでのセットアップ

1. パブリッシャーアカウントのプロジェクトで、アイテムカタログ > すべてのアイテムセクションに移動します。
2. 「追加」をクリックしてドロップダウンリストから仮想アイテムを選択します。

3. 以下のパラメータを指定します：
   • イメージ（任意）。
   • SKU。
   • バンドルが属する1つまたは複数のグループ。
   • 名称。
   • 説明（任意）。
4. 価格設定セクションで、無料アイテムを選択してください。
5. 1人のユーザーが購入できるアイテム数を制限するには、1ユーザーあたりの購入可能回数を制限するトグルをオンにして、必要な数量を入力してください。
6. 制限がリセットされる頻度を設定するには：
   1. ドロップダウンリストから期間を選択します：
      • 毎日。
      • 毎週。
      • 毎月。
      • カスタムの間隔 — バンドルの表示開始日から計算されます。
      • 定期的なリフレッシュなし。
   2. 選択した期間に基づいて、リセットスケジュールを設定します。
7. ストアでのアイテムの表示方法を設定します：
   • ステータスを選択します。
   • アイテムの表示期間制限を設定します（任意）：タイムゾーンと、期間の開始日時および終了日時を指定します。表示終了日時を設定しない場合は、終了日なしにチェックを入れてください。
8. 以下のいずれかのオプションを使用して、アイテム属性を設定します（任意）：
   • 属性とその値をJSON形式で追加します。
   • 属性と値を手動で作成し、それらを特定のアイテムにリンクさせます。
9. 「アイテムを作成」をクリックします。

API経由のセットアップ

アイテムを無料に設定するには、以下の管理者のAPIコールを実行する際、リクエスト本文に“is_free”: trueを渡してください。

• 仮想アイテムを作成するまたは仮想アイテムを更新する
• ゲームを作成する、IDによるゲームを更新する、またはSKUによるゲームを更新する
• 仮想通貨を作成するまたは仮想通貨を更新する
• 仮想通貨パッケージを作成するまたは仮想通貨パッケージを更新する
• バンドルを作成するまたはバンドルを更新する

• limitsは制限する数量を指定する
• limits.recurrent_scheduleは制限がリセットされる頻度を指定する

カタログ内での無料アイテム表示

無料アイテムは、カタログの実装方法サイトビルダーまたはAPI経由に応じて表示されます。

サイトビルダー経由での表示

ウェブサイトに無料アイテムを表示するには：

1. 無料アイテムを作成する。
2. パブリッシャーアカウントのプロジェクトで、ストアフロント > ウェブサイトセクションに移動します。
3. ご希望のサイトのウィンドウで、「サイトビルダーを開く」をクリックします。

4. ストアセクションのアイテムタイプフィールドで、無料アイテムのタイプを選択し、該当する場合はそのグループを指定してください。
5. アイテムカードレイアウトを設定します。
6. 必要な変更をすべて行い、ウェブサイトを公開する準備が整ったら：
   1. サイトビルダーの右上隅で「公開」をクリックします。
   2. 公開したいページ名の横にあるチェックボックスをオンにします。
   3. 「公開」をクリックします。

API経由で無料アイテム情報の取得

カタログをAPIで構成している場合、無料アイテムのデータはカタログサブセクションにある以下のAPIコールを通じて返されます：

• 仮想アイテムリストを取得する
• 仮想通貨リストを取得する
• 仮想通貨パッケージリストを取得する
• バンドルリストを取得する
• ゲームリストを取得する

ユーザーへの無料アイテム付与

無料アイテムを含む注文の処理方法は、購入時にカートを使用するかどうかによって異なります。 ユーザーがカートを使用せずにアイテムを購入する場合は、指定された無料アイテムで注文を作成するAPIコールを使用してください。 ユーザーがカートを使用してアイテムを購入する場合、以下のようなシナリオが想定されます：

• ユーザーのカートに有料アイテムと無料アイテムの両方が含まれている場合は、注文作成のAPIコール特定のカートの全アイテムを対象とした注文を作成するまたは現在のカートの全アイテムを対象とした注文を作成するを使用してください。このシナリオでは、ユーザーは決済UI上で決済処理を完了します。
• ユーザーのカートに無料アイテムのみが含まれている場合、無料カートで注文を作成するまたは特定の無料カートで注文を作成するAPIコールを使用してください。この場合、決済UIは使用されません。

両方の場合も、エクソーラは注文支払い完了ウェブフックを送信します。これには、ユーザーにアイテムを付与するために必要なアイテムデータが含まれています。なお、無料アイテムの場合、ウェブフック内のorder.invoice_idパラメータはnullに設定されます。

無料アイテムの注文オブジェクト例：

 1{
 2  "method": "POST",
 3  "url": "https://mybestgame.com/xsolla/notification",
 4  "body": {
 5    "items": [
 6      {
 7        "sku": "gift_direct_game_reward-supercoin",
 8        "type": "virtual_currency",
 9        "is_pre_order": false,
10        "quantity": 500,
11        "amount": "0",
12        "promotions": [
13
14        ]
15      },
16      {
17        "sku": "package-500_supercoin",
18        "type": "bundle",
19        "is_pre_order": false,
20        "quantity": 1,
21        "amount": "0",
22        "promotions": [
23
24        ]
25      },
26      {
27        "sku": "xsolla-giveaway_offer_11_14_22",
28        "type": "bundle",
29        "is_pre_order": false,
30        "quantity": 1,
31        "amount": "0",
32        "promotions": [
33
34        ]
35      }
36    ],
37    "notification_type": "order_paid",
38    "order": {
39      "id": 12345678,
40      "mode": "default",
41      "currency_type": "unknown",
42      "currency": null,
43      "amount": "0",
44      "status": "paid",
45      "platform": "xsolla",
46      "comment": null,
47      "invoice_id": null,
48      "promotions": [
49
50      ]
51    },
52    "user": {
53      "external_id": "1234567812345678",
54      "email": null
55    }
56  },
57  "headers": {
58    "Authorization": "Signature 3b840ccefea111dcdfd111db1fdc6df969a3ec11",
59    "Accept": "application/json",
60    "Content-Type": "application/json"
61  },
62  "type": "webhook_payment",
63  "callback_parameters": {
64    "order_id": 12345678
65  }
66}

プロジェクトの統合設定に基づき、アイテムは以下のいずれかの方法でユーザーに付与されます：

• PlayFabを統合している場合、仮想通貨とアイテムはユーザーのPlayFabインベントリに自動的に付与されます。
• カスタム配信システムを使用している場合は、すべての仮想アイテムと通貨は貴社側で付与されます。注文データをご自身のバックエンドで受信するために、ウェブフックハンドラーを設定することをお勧めします。必要なデータは、注文支払い成功ウェブフックに含まれています。