仮想アイテム

概要

仮想アイテムとは、ユーザーが実際通貨または仮想通貨で購入したり、ボーナスとして受け取ることができるゲーム内アイテムです。これらのアイテムは物理的な形を持たず、ゲーム内でのみ使用されます。仮想アイテムの例：スキン、ポーション、武器、キー、およびゲームプレイやキャラクターの外観に影響を与えるその他の要素。

主な機能：

• 柔軟な価格設定：
  • 同じアイテムに対して、実際通貨と仮想通貨の両方で価格を指定する機能。
  • 同じアイテムに対して、複数の実際通貨と仮想通貨で価格を指定する機能。この場合、それぞれの通貨タイプ（実際通貨と仮想通貨）に対して、デフォルトとなる通貨を一つ指定する必要があります。
  • 無料アイテムの作成。
  • 地域別価格の設定。
• 通貨と国の自動判別。
• 可用性設定：
  • 異なる地域でのアイテム販売を制限します。
  • 購入可能なアイテム数を制限します。
  • ストア内のアイテムの表示期間を制限します。
  • 購入不可アイテムの設定。アイテムをカタログから非表示にできますが、バンドルの一部として、または別のアイテム購入のボーナスとして受け取ることは可能です。
• カタログの整理：
  • グループを作成します。
  • カタログ内のアイテムを並べ替えます。

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

グループを作成する

グループを使用すると、多階層のカタログを構築できます。グループに割り当てられていないアイテムは、「未分類」グループに配置されます。「未分類」グループは編集または削除できません。

グループを作成するには：

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

3. 以下のパラメータを指定します：
   • External ID — 一意のグループID。
   • グループ名。
4. ストアでグループを利用可能にするには、「ストアにグループを表示する」トグルを「オン」に設定します。この場合、グループは「有効」ステータスで作成されます。グループのステータスは後で変更できます。
5. 「グループを作成」をクリックします。

お知らせ

グループが「無効」ステータスの場合、そのようなグループは次のようになります：

• アイテムグループリストを取得するAPIメソッドを呼び出す際のレスポンスで返されません。
• クライアントAPIメソッドを呼び出してアイテムのリストを取得する際、このグループに含まれるアイテムのプロパティには表示されません。
• サイトビルダーでは利用できません。

作成後にグループのステータスを変更するには、ストア > 仮想アイテムセクションで目的のグループを見つけ、「ステータス」列で必要なステータスを選択します。

既存のグループ内に新しいグループを追加することで、多階層のカタログを作成できます。ただし、「未分類」グループ内には、ネストされたグループを作成することはできません。

既存のグループを別のグループ内にネストするには：

1. パブリッシャーアカウントのプロジェクトで、ストア > 仮想通貨セクションに移動します。
2. 別の既存のグループの下にネストしたいグループを選択します。
3. 「•••」をクリックしてドロップダウンリストから「グループを編集」を選択します。
4. ディレクトリロケーションの場所ドロップダウンリストから、現在のグループを配置したい親グループを選択します。

5. 「変更内容を保存する」をクリックします。

仮想アイテムを作成する

仮想アイテムを作成するには：

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

3. カタログにおける仮想アイテムの可用性ステータスを定義します。次のいずれかのオプションを選択してください：
   • 利用不可（デフォルト） — アイテムはカタログで購入できず、バンドルに含めることも、別のアイテム購入のボーナスとして使用することもできません。
   • 利用可能 — アイテムはカタログで購入でき、バンドルに含めることも、別のアイテム購入のボーナスとして使用することもできます。
   • 一部利用可能 — アイテムはカタログからは購入できませんが、バンドルに追加したり、別のアイテム購入のボーナスとして使用したりすることはできます。
   アイテムの可用性ステータスは後で変更できます。

4. 基本設定を行います。以下を指定してください：
   • 画像（任意）
   • SKU
   • アイテムが属する1つまたは複数のグループ
   • アイテム名
   • アイテムの説明（任意）

5. アイテムタイプはデフォルトのままにします — 消耗品（推奨）。

6. 仮想アイテムの価格を設定します：
   • 無料の仮想アイテムを作成するには、「有料または無料」フィールドで「無料アイテム」を選択します。
   • 有料の仮想アイテムを作成するには、有料または無料フィールドで有料アイテムを選択し、1つまたは複数の通貨で価格を指定します。
   • 地域別価格を設定します（任意）。

7. 購入可能なアイテム数を制限します（任意）。これを行うには：
   1. 「1人のユーザーがこのアイテムを購入できる回数を制限する」トグルを「オン」に設定して、ユーザーが購入できるアイテム数を指定します。
   2. 制限のリフレッシュ頻度を構成します：
      1. 制限をリセットしない場合は、ドロップダウンリストから「定期的なリフレッシュなし」を選択します。
      2. 制限を定期的にリセットする場合は、ドロップダウンリストからリフレッシュ頻度を選択し、リセットが発生するタイミングを指定します。
8. ストア内のアイテムの表示期間を制限します（任意）。これを行うには、「ストアにアイテムを表示する」フィールドで、「期間」を選択して、タイムゾーン、期間の開始と終了を指定します。アイテムの表示期間の終了を示したくない場合は、終了日なしのチェックボックスを入れてください。
9. 追加属性を追加します（任意）。
10. アイテムを作成するをクリックします。

APIによる仮想アイテムの取り扱い

仮想アイテムをセットアップするには、仮想アイテム＆通貨グループの管理者サブセクションからのAPIコールを使用します。

APIコールには基本的な認証が使用されます。Authorization:Basic <your_authorization_basic_key>を渡し、そこで、<your_authorization_basic_key>はマーチャントID：APIキーペア、はBase64規格に基づいてエンコードされています。パブリッシャーアカウントに移動して、以下のパラメータを見つかります：

• マーチャントIDは以下の場所で表示されます：
  • 会社設定 > 会社セクション。
  • パブリッシャーアカウントページのブラウザーアドレスバーのURL。URLは以下の形式があります：https://publisher.xsolla.com/<merchant_id>/。

• APIキーは、作成時に一度だけパブリッシャーアカウントに表示され、お客様側で保存する必要があります。次のセクションで新しいキーを作成できます：
  • 会社設定 > APIキー
  • プロジェクト設定 > APIキー

クライアント側で仮想アイテムのカタログを取得するには、仮想アイテム＆通貨グループのカタログサブセクションからのAPIコールを使用します。これらの呼び出しは基本的な認証を必要としません。

グループに分かれていないアイテムの完全なリストを取得するには、仮想アイテムリストを取得するAPIコールを使用します。特定のグループからアイテムのリストを取得するには、指定したグループからアイテムリストを取得するコールにexternal_idパラメータを渡します。

仮想アイテムの詳細設定

購入できるアイテム数を制限する

特定の仮想アイテムが1人のユーザーによって購入できる回数を制限できます。これは、アイテムの可用性を制御し、限定オファーの作成をサポートするのに役立ちます。

使用例は以下の通り：

• 仮想アイテムに対する、日次、週次、または月次の購入制限。
• ユーザーあたり一度のみ購入可能なウェルカムアイテム。

購入制限を設定する方法は2つあります：

• パブリッシャーアカウント経由の場合：アイテムの作成または編集時に、「1人のユーザーがこのアイテムを購入できる回数を制限する」トグルを「オン」にし、購入可能なアイテムの数量を指定し、更新スケジュールを設定します。
• API経由の場合：アイテムの作成または更新時に、リクエスト本文のlimitsオブジェクトに購入制限の設定を渡します。

購入制限の適用は、完全にエクソーラ側で処理されます。システムは、各ユーザーがアイテムを何回購入したかを追跡し、設定された制限を超える購入を阻止します。

カタログリクエストにユーザーアクセストークンが含まれている場合（仮想アイテム&仮想通貨グループの「カタログ」サブセクションからAPIメソッドを呼び出す場合）、エクソーラはその特定のユーザーがまだ購入できる各アイテムのユニット数を計算します。レスポンスには、合計許可数量（totalパラメータ）と、そのユーザーが利用可能な残りの数量（availableパラメータ）を含むlimitsオブジェクトが含まれます。これらの値を使用して、インターフェースに可用性を表示できます。

リクエストにユーザーアクセストークンが提供されない場合、レスポンス内のavailableパラメータの値は常に合計制限数と一致します。

購入制限のあるアイテムを含むレスポンスの例：

 1{
 2  "items": [
 3    {
 4      "sku": "big_rocket",
 5      "name": "Big Rocket",
 6      "groups": [
 7        {
 8          "external_id": "accessory",
 9          "name": "Accessory"
10        }
11      ],
12      "attributes": [
13        {
14          "external_id": "stack_size",
15          "name": "Stack size",
16          "values": [
17            {
18              "external_id": "size_e3364991f92e751689a68b96598a5a5a84010b85",
19              "value": "5"
20            }
21          ]
22        }
23      ],
24      "type": "virtual_good",
25      "description": "Big Rocket - description",
26      "image_url": "https://popmedia.blob.core.windows.net/popyourself/male/outfit/male_armor_white_a-01.png",
27      "is_free": false,
28      "price": {
29        "amount": "100.99",
30        "amount_without_discount": "100.99",
31        "currency": "USD"
32      },
33      "virtual_prices": [
34        {
35          "amount": 100,
36          "sku": "vc_test",
37          "is_default": true,
38          "amount_without_discount": 100,
39          "image_url": "http://image.png",
40          "name": "SHOTGUN FOR TRUE RAIDERS",
41          "type": "virtual_currency",
42          "description": "description"
43        }
44      ],
45      "can_be_bought": true,
46      "inventory_options": {
47        "consumable": {
48          "usages_count": 1
49        },
50        "expiration_period": {
51          "type": "day",
52          "value": 1
53        }
54      },
55      "virtual_item_type": "non_renewing_subscription",
56      "limits": {
57        "per_user": {
58            "total": 5,
59            "available": 5
60        },
61        "per_item": null
62      },
63}

加えて、エクソーラはチェックアウト開始時と注文完了時の両方で、購入制限を強制的に適用します。ユーザーが複数のタブを開いていたり、同時に複数の注文を試みても、システムは制限を超過することを防ぎます。すでに購入されたアイテムを含む未払いの注文は、すべてキャンセルされます。

ストア内のアイテムの表示時間を制限する

ストア内のアイテムの表示期間を指定することで、以下が可能になります：

• 特定の期間（例：ホリデーセール中）にカタログの関連性を維持する
• カタログに表示せずに事前にアイテムを作成する
• アイテムの横にタイマーを表示して、ユーザーの購買意欲を高める

ストア内のアイテムの表示期間は、以下のいずれかの方法で構成できます：

• パブリッシャーアカウントで：アイテムを作成または編集する場合、「ストアにアイテムを表示する」フィールドで「期間」を選択し、タイムゾーン、開始日、終了日を指定してください。終了日をオープンのままにするには、「終了日なし」のチェックボックスを入れてください。
• API経由：アイテムを作成または更新する時に、periodsオブジェクトに以下のパラメータを含めます：
  • periods[0].date_from — 表示期間の開始日時（形式：YYYY-MM-DDThh:mm:ss±hh:mm）。
  • periods[0].date_until — 表示期間の終了日時。終了日時を指定しない場合は、nullを渡してください。

APIを使用して複数の表示期間を定義するには、開始日と終了日を持つオブジェクトの配列を渡します。

期間配列の例：

 1"periods": [
 2      {
 3        "date_from": "2022-06-10T14:00:00+03:00",
 4        "date_until": "2022-06-30T14:00:00+03:00"
 5      },
 6       {
 7        "date_from": "2022-07-10T14:00:00+03:00",
 8        "date_until": "2022-07-30T14:00:00+03:00"
 9      },
10       {
11        "date_from": "2022-08-10T14:00:00+03:00",
12        "date_until": "2022-08-30T14:00:00+03:00"
13      }
14]

地域制限を設定する

どの地域で仮想アイテムを購入可能にするかを設定できます。これにより、誰に、どこでアイテムを表示するかを制御できます。例えば、特定の国のユーザーにはアイテムを非表示にしたり、地域限定のプロモーションキャンペーンの一環として、特定の地域でのみ利用可能にしたりできます。

仮想アイテムの地域制限を設定するには、仮想アイテムを作成するまたは仮想アイテムを更新するのAPIメソッドを呼び出す際に、リクエスト本文に該当する地域IDを持つregionsオブジェクトの配列を含めます。

地域配列の例：

1"regions": [{
2     “id”: 123
3  }, {
4     “id”: 456
5  }
6]

地域別価格を設定する

地域別価格設定を構成することで、異なる国の経済状況に基づいて仮想アイテムの価格を調整できます。これにより、購買力の異なる地域のユーザーにとってオファーがより利用しやすくなり、コンバージョン率と全体的な売上の両方を向上させるのに役立ちます。

地域価格は以下の方法でセットアップできます：

• パブリッシャーアカウントで（手動設定）：アイテムの作成または編集時に、価格設定セクションに移動し、「実際通貨での価格」トグルを「オン」に設定し、「価格を設定」をクリックします。価格を手動で入力するか、通貨と税金に基づいて自動的に計算できます。
• パブリッシャーアカウントでのCSVインポート経由：CSVファイル内で、特定の地域向けのアイテム価格を複数行追加できます。ファイル構造と例の詳細については、現地価格の説明をご覧ください。

 1SKU,Currency,Amount,Country,IsDefault,Platform
 2game-key-1,EUR,9.09,,1,steam
 3game-key-1,EUR,9.2,DE,0,steam
 4game-key-1,EUR,8.09,IT,0,steam
 5game-key-1,USD,10.1,US,0,steam
 6game-key-1,MYR,47,MY,0,steam
 7game-key-2,EUR,2.09,,1,steam
 8game-key-2,EUR,2.2,DE,0,steam
 9game-key-2,EUR,1.79,IT,0,steam
10game-key-2,USD,2.3,US,0,steam
11game-key-2,MYR,24,MY,0,steam

• API経由：アイテムの作成または更新時に、リクエスト本文に地域別価格設定を含むprices配列を含めます。

 1"prices": [
 2      {
 3        "amount": 100,
 4        "currency": "USD",
 5        "is_enabled": true,
 6        "is_default": true
 7      },
 8      {
 9        "amount": 200,
10        "currency": "CZK",
11        "country_iso": "CZ",
12        "is_enabled": false,
13        "is_default": false
14      }
15    ]

お役立ちリンク