無料アイテム

仕組み

無料アイテムとは、仮想通貨や実際通貨を消費することなく、ユーザーが獲得できるアイテムです。

無料アイテムは、以下のシナリオで利用可能です：

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

使用事例：

• プロジェクトのマイルストーンや記念日などの特別な日に、ユーザーのロイヤルティへの報酬として無料アイテムを提供します。
• ベースゲームをすでに購入したユーザー向けに、ロイヤルティ報酬として無料アドオンを提供します。
• 新規ユーザー獲得のため、ウェブストアで無料のスターターパックを提供します。

無料の仮想アイテム、仮想通貨、およびバンドルは、認証されたユーザーのみが利用可能です。無料ゲームキーは、認証済みユーザーと未認証ユーザーの両方が利用可能です。無料アイテムの数量制限の設定は、認証されたユーザーに限定されます。

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

2. 「手動で作成」をクリックし、ドロップダウンリストから仮想アイテムを選択します。

3. 一般設定セクションで、次を指定します：
   • SKU
   • アイテムが属すべき1つまたは複数のグループ（任意）
   • 名称
   • 簡潔な説明
   • 詳細な説明 — 追加するには、対応するトグルをオンにします（任意）

4. メディアセクションで、1つ以上の画像または動画をアップロードします（任意）。デバイスから直接、またはリンク経由で追加できます。エクソーラのサイトエディターで作成したストアでは、すべてのアイテムカードにメインとしてマークされたファイルが表示され、残りのファイルはメディアギャラリー付きのアイテムカードでのみ表示されます。メインとしてマークされたファイルは、カタログ取得のAPIコールのレスポンスでも返されます。

5. 価格設定セクションで無料アイテムを選択します。

6. 購入可能なアイテム数を制限するには：
   1. 制限セクションでトグルをオンにし、数量を指定します。
   2. 制限のリセット頻度を設定します。ドロップダウンリストから期間を選択します：
      1. 毎日
      2. 毎週
      3. 毎月
      4. カスタム間隔。間隔はストアでのアイテムの表示開始日時から計算されます。
      5. 定期的なリセットなし
   3. 選択した期間に対応するパラメータを指定して、リセットスケジュールを設定します。

7. アイテムの表示期間制限を設定する（任意）：

   1. 特定の表示期間を追加セクションでトグルをオンにします。
   2. タイムゾーン、開始日時、終了日時を指定します。

   アイテムの表示期間の終了を指定しない場合は、終了日なしのトグルをオンにします。

8. 以下のいずれかのオプションを使用して属性を設定します（任意）：
   1. JSON形式で属性とその値を追加する
   2. 属性とその値を手動で作成し、アイテムに関連付ける

9. 「作成」をクリックします。
10. 表示されたウィンドウで、アイテムのステータス を選択し、「続ける」をクリックします。

作成したアイテムはすべてのアイテムセクションに表示されます。

API経由でのセットアップ

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

• 仮想アイテムを作成する または 仮想アイテムを更新する
• ゲームを作成する、ID でゲームを更新する または SKU でゲームを更新する
• 仮想通貨を作成する または 仮想通貨を更新する
• 仮想通貨パッケージを作成する または 仮想通貨パッケージを更新する
• バンドルを作成する または バンドルを更新する ユーザーが受け取れる無料アイテムの数を制限したい場合は、アイテムの作成または更新のコールで以下のパラメータを渡してください：
  • 数量を指定するlimits
  • 制限のリセット頻度を指定するlimits.recurrent_schedule

ストアでのアイテム表示期間の制限を設定し、地域別制限を設定できます。

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

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

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

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

1. 無料アイテムを作成します。

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

2. モバイルゲーム用アカウントのプロジェクトで、ウェブショップセクションに移動します。
3. 希望するサイトのペインをクリックします。

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

サイトが公開されると、無料アイテムのセクションが利用可能になります。アイテムが表示されない場合は、ステータスが「利用可能」に設定され、表示期間の制限が有効になっていないことを確認してください。

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

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

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

ユーザーに無料アイテムを付与する

無料アイテムを含む注文の処理方法は、購入時にカートを使用するかどうかによって異なります。

ユーザーがカートを使用せずにアイテムを購入する場合は、指定された無料アイテムを含む注文を作成するAPIコールを使用します。

ユーザーがカートを使用してアイテムを購入する場合、以下のシナリオが考えられます：

• ユーザーのカートに有料アイテムと無料アイテムの両方が含まれている場合は、注文作成の特定のカート内のすべてのアイテムで注文を作成するまたは現在のカート内のすべてのアイテムで注文を作成するAPIコールを使用します。この場合、ユーザーは決済UIで決済を完了します。
• ユーザーのカートに無料アイテムのみが含まれている場合は、無料カートで注文を作成するまたは特定の無料カートで注文を作成するAPIコールを使用します。この場合、決済UIは使用しません。

  どちらの場合も、エクソーラはアイテム付与に使用するアイテムデータを含む注文の支払い成功ウェブフックを送信します。無料アイテムの場合、このウェブフック内のorder.invoice_idパラメータは「null」に設定されます。

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

 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インベントリに自動的に付与されます。
• カスタムの配信システムを使用している場合、すべての仮想アイテムと仮想通貨は運営者側で付与されます。バックエンドで注文データを受信するために、ウェブフックハンドラをセットアップすることをお勧めします。必要なデータは注文の支払い成功ウェブフックに含まれています。

この件およびその他の購入データ取得オプションの詳細については、注文ステータス追跡のセットアップセクションを参照してください。