コンテンツへスキップ
/
現在のユーザーのバリューポイント残高を取得する

LiveOps API (2.0.0)

概要

  • バージョン: 2.0.0
  • サーバー: https://store.xsolla.com/api
  • メールでのお問い合わせ
  • お問い合わせURL： https://xsolla.com/
  • 必要なTLSバージョン： 1.2

LiveOpsは、プロモーションやパーソナライズされたオファーを通じて、プレイヤーの継続的なエンゲージメントを高めるためのツールキットです。

APIを使用して、以下の機能を管理できます：

  • プロモーション — クーポン、プロモコード、割引、ボーナスキャンペーンを作成または管理します。
  • 個人用設定 — アイテムカタログの表示や、特定の認証済みユーザーのみにプロモーションを適用するための条件を指定します。
  • プロモーション制限 — ユーザーがプロモーションを利用できる回数の上限を設定し、これらの制限を定期的にリセットするスケジュールを構成します。
  • 報酬チェーンとバリューポイント — バリューポイントの蓄積に連動した報酬進行度を構成します。
  • デイリーチェーン — 定期的なログインを促すために、繰り返し受け取れるデイリー報酬を設定します。
  • オファーチェーン — ステップごとの価格設定や無料リワードのオプションを含む、段階的な購入オファーを構築します。
  • アップセル — ユーザーに対して、追加の価値を持つアイテムの購入を促す販売手法です。

APIコール

APIは次のグループに分かれています：

  • Admin — キャンペーンとチェーン設定の作成、更新、アクティブ化、削除のためのコールです。マーチャントまたはプロジェクトの認証情報を使用した基本アクセス認証によって認証されます。
  • Client — 認証済みエンドユーザーの代理として、利用可能なプロモーションの取得、アクティブなチェーンの取得、コードの引き換え、よび報酬の請求を実行するAPIコール。ユーザーのJWTにより認証を行います。

認証

APIコールには、ユーザーまたはプロジェクトのいずれかに代わって認証が必要です。使用される認証スキームは、各コールの説明のセキュリティセクションに指定されています。

ユーザーのJWTを使用した認証

ユーザーのJWTを使用した認証は、ブラウザ、モバイルアプリケーション、またはゲームからリクエストが送信される場合に使用されます。デフォルトでは、XsollaLoginUserJWTスキームが適用されます。トークンの作成方法の詳細については、エクソーラログインAPIに関するドキュメントを参照してください。

トークンはAuthorizationヘッダーに次の形式で渡されます：Authorization: Bearer <user_JWT>。ここで<user_JWT>はユーザートークンです。このトークンによってユーザーが特定され、パーソナライズされたデータへのアクセスが可能になります。

別の方法として、決済UIを開くためのトークンを使用することも可能です。

基本HTTP認証

基本HTTP認証は、ユーザーのブラウザやモバイルアプリケーションからではなく、サーバーから直接APIコールが送信される場合のサーバー間のやり取りに使用されます。通常、APIキーを使用したHTTP基本認証が使用されます。

注意

APIキーは機密性高いため、クライアントアプリケーション側での保存および使用は厳禁とします。

基本的なサーバーサイド認証では、すべてのAPIリクエストに以下のヘッダーを含める必要があります：

  • basicAuthの場合 — Authorization: Basic <your_authorization_basic_key>。ここでyour_authorization_basic_keyは、Base64でエンコードされたproject_id:api_keyペアです。
  • basicMerchantAuthの場合 — Authorization: Basic <your_authorization_basic_key>。ここでyour_authorization_basic_keyは、Base64でエンコードされたmerchant_id:api_keyペアです。

パラメータの値はパブリッシャーアカウントで確認できます：

  • merchant_idは次の場所に表示されます：
    • 会社設定 > 会社。
    • パブリッシャーアカウントの任意のページのブラウザアドレスバーのURLに。URLの形式は以下の通りです： https://publisher.xsolla.com/<merchant_id>。
  • project_idは次の場所に表示されます：
    • パブリッシャーアカウントのプロジェクト名の横に。
    • パブリッシャーアカウントでプロジェクトを操作しているときのブラウザアドレスバーのURLに。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
  • api_keyは作成時にのみパブリッシャーアカウントに表示され、あなたの側で安全に保管する必要があります。APIキーは次のセクションで作成できます：
注意

必要なAPIコールにproject_idパスパラメータが含まれていない場合、認証を行うには、会社のすべてのプロジェクト共通で有効なAPIキーを使用してください。

APIキーの操作に関する詳細は、APIリファレンスを参照してください。

ゲストアクセスをサポートする認証

AuthForCart認証スキームはカートでの購入用であり、以下の2つのモードに対応しています：

  1. ユーザーのJWTによる認証。 トークンはAuthorizationヘッダーで次の形式で渡されます：Authorization: Bearer <user_JWT>、ここで<user_JWT>はユーザートークンです。このトークンによってユーザーが特定され、パーソナライズされたデータへのアクセスが可能になります。あるいは、決済UIを開くためのトークンを使用することもできます。

  2. 認証ヘッダーを使用しない簡易モード。 このモードは未認証ユーザーにのみ使用され、ゲームキー販売にのみ適用できます。リクエストにはトークンの代わりに、以下のヘッダーを含める必要があります：

    • リクエストIDを含むx-unauthorized-id
    • Base64でエンコードされたユーザーのメールアドレスを含むx-user

主要なエンティティ構造

すべてのタイプ（仮想アイテム、バンドル、仮想通貨、キー）のアイテムは、同様のデータ構造を使用しています。この基本構造を理解することで、APIの利用が簡素化され、ドキュメントをよりスムーズに読み進められるようになります。

注意

一部のコールには追加のフィールドが含まれる場合がありますが、基本構造が変わることはありません。

識別

  • merchant_id — パブリッシャーアカウントにおける会社ID
  • project_id — パブリッシャーアカウントにおけるプロジェクトID
  • sku — アイテムSKU、プロジェクト内で一意です

ストア表示

  • name — アイテム名
  • description — アイテム説明
  • image_url — 画像URL
  • is_enabled — アイテムの可用性
  • is_show_in_store — アイテムがカタログに表示されるかどうか

カタログ内のアイテムの可用性管理に関する詳細は、ドキュメントを参照してください。

組織

  • type — アイテムタイプ、例：仮想アイテム（virtual_item）またはバンドル（bundle）
  • groups — アイテムが属するグループ
  • order — カタログ内の表示順序

販売条件

  • prices — 実際通貨または仮想通貨での価格
  • limits — 購入制限
  • periods — 可用期間
  • regions — 地域別制限

主要なエンティティ構造の例：

{
  "attributes": [],
  "bundle_type": "virtual_currency_package",
  "content": [
    {
      "description": {
        "en": "Main in-game currency"
      },
      "image_url": "https://.../image.png",
      "name": {
        "en": "Crystals",
        "de": "Kristalle"
      },
      "quantity": 500,
      "sku": "com.xsolla.crystal_2",
      "type": "virtual_currency"
    }
  ],
  "description": {
    "en": "Crystals x500"
  },
  "groups": [],
  "image_url": "https://.../image.png",
  "is_enabled": true,
  "is_free": false,
  "is_show_in_store": true,
  "limits": {
    "per_item": null,
    "per_user": null,
    "recurrent_schedule": null
  },
  "long_description": null,
  "media_list": [],
  "name": {
    "en": "Medium crystal pack"
  },
  "order": 1,
  "periods": [
    {
      "date_from": null,
      "date_until": "2020-08-11T20:00:00+03:00"
    }
  ],
  "prices": [
    {
      "amount": 20,
      "country_iso": "US",
      "currency": "USD",
      "is_default": true,
      "is_enabled": true
    }
  ],
  "regions": [],
  "sku": "com.xsolla.crystal_pack_2",
  "type": "bundle",
  "vc_prices": []
}

基本的な購入フロー

エクソーラAPIを使用すると、ゲーム内ストアのロジックを実装でき、アイテムカタログの取得、カートの管理、注文の作成、そのステータスの追跡が可能です。統合シナリオに応じて、APIコールは管理者とカタログのサブセクションに分かれ、異なる認証スキームを使用します。

以下の例は、アイテムの作成から購入に至るまで、ストアのセットアップおよび運用の基本フローを示しています。

アイテムおよびグループの作成（管理者向け）

仮想アイテム、バンドル、仮想通貨など、ストアのアイテムカタログを作成します。

APIコールの例：

プロモーション、チェーン、および制限の設定（管理者向け）

割引、ボーナス、デイリー報酬、またはオファーチェーンなど、ユーザー獲得および収益化のためのツールを設定します。

APIコールの例：

アイテム情報の取得（クライアント向け）

アプリケーション内でのアイテム表示を設定します。

注意

ユーザーカタログを構築するために管理サブセクションのAPIコールを使用しないでください。これらのAPIコールにはレート制限があり、ユーザーのトラフィックを対象としていません。

APIコールの例：

注意

デフォルトでは、カタログAPIコールはリクエスト時にストアで現在利用可能なアイテムを返します。まだ利用可能でない、または利用できなくなったアイテムを取得するには、カタログリクエストにパラメータ"show_inactive_time_limited_items": 1を含めてください。

アイテムの販売

アイテムは以下の方法で販売できます：

  • 迅速な購入 — 1つのSKUを複数回販売します。
  • カート購入 — ユーザーがアイテムをカートに追加し、アイテムを削除し、単一の注文内で数量を更新します。

アイテムが実際のお金ではなく仮想通貨で購入された場合は、仮想通貨で購入した指定アイテムで注文を作成するAPIコールを使用してください。当該APIコールの実行時に課金処理が行われるため、決済UIを表示する必要はありません。

無料アイテムの購入には、指定した無料アイテムで注文を作成するAPIコールまたは無料カートで注文を作成するAPIコールを使用してください。決済UIを表示する必要はありません。注文は即時にdoneステータスに設定されます。

迅速な購入

クライアント側のAPIコールを使用して、指定したアイテムで注文を作成します。このコールは、決済UIを開くために使用するトークンを返します。

注意

割引情報は決済UIでのみユーザーに提供されます。プロモーションコードはサポートされていません。

カート購入

カートの設定と購入は、クライアントまたはサーバー側で実行できます。

クライアント側でのカートのセットアップと購入

アイテムの追加および削除のロジックは、独自に実装してください。カートを設定するためのAPIを呼び出す前は、購入にどのプロモーションが適用されるかに関する情報は取得できません。つまり、合計金額や、追加されるボーナスアイテムの詳細を事前に知ることはできません。

以下のカートロジックを実装します：

  1. プレイヤーがカートにアイテムを入れた後、カートにアイテムを入れるAPIコールを使用します。このコールは、選択されたアイテムに関する現在の情報（割引前後の価格、ボーナスアイテム）を返します。
  2. ユーザーのアクションに基づいてカートの内容を更新します：
注意

カートの現在のステータスを取得するには、現在のユーザーのカートを取得するAPIコールを使用してください。
  1. 現在のカートからすべてのアイテムで注文を作成するAPIコールを使用します。このコールは注文IDと決済トークンを返します。新しく作成された注文はデフォルトでnewステータスに設定されます。

サーバー側でのカートのセットアップと購入

カートへの変更ごとにAPIコールを伴う必要があるため、この設定オプションではカートの設定に時間がかかる場合があります。

以下のカートロジックを実装します：

  1. プレイヤーがカートにアイテムを入れた後、カートにアイテムを入れるAPIコールを使用します。このコールは、選択されたアイテムに関する現在の情報（割引前後の価格、ボーナスアイテム）を返します。
  2. 現在のカートのすべてのアイテムで注文を作成するAPIコールを使用します。このコールは、注文IDと支払いトークンを返します。新しく作成された注文は、デフォルトでnewステータスに設定されます。

決済UIを開く

返されたトークンを使用して、新しいウィンドウで決済UIを開きます。決済UIを開くその他の方法は、ドキュメントに記載されています。

| アクション | エンドポイント | |：--------------------------------|：--------------------------------------------------------------------------| | 本番環境で開きます。 | https://secure.xsolla.com/paystation4/?token={token} | | サンドボックスモードで開きます。 | https://sandbox-secure.xsolla.com/paystation4/?token={token} |

注意

開発およびテスト中はサンドボックスモードを使用してください。テスト購入では実際のアカウントに料金は発生しません。テスト用銀行カードを使用できます。

最初の実際の支払いが行われた後、厳格なサンドボックス決済ポリシーが適用されます。サンドボックスモードでの支払いは、パブリッシャーアカウント > 会社設定 > ユーザーで指定されたユーザーのみが利用可能です。

実際通貨で仮想通貨やアイテムを購入するには、エクソーラとのライセンス契約を締結する必要があります。これを行うには、パブリッシャーアカウントで契約と税金 > 契約に移動し、契約フォームを記入して確認を待ちます。契約の審査には最大3営業日かかる場合があります。

サンドボックスモードを有効または無効にするには、迅速な購入およびカート購入のリクエストでsandboxパラメータの値を変更します。サンドボックスモードはデフォルトでオフになっています。

可能な注文状況：

  • new — 注文作成済み
  • paid — 支払い受領済み
  • done — アイテム付与完了
  • canceled — 注文キャンセル済み
  • expired — 注文期限切れ

以下のいずれかの方法を使用して、注文ステータスを追跡します：

ページネーション

大規模なレコードセットを返すAPIコール（カタログを構築する場合など）では、データがページ分割されて返されます。ページネーションは、単一のAPI応答で返されるアイテム数を制限し、下一ページのデータを順次取得できるようにするための仕組みです。

返されるアイテム数を制御するには、以下のパラメータを使用します：

  • limit — 1ページあたりのアイテム件数
  • offset — ページ上の最初のアイテムのインデックス（番号付けは0から始まります）
  • has_more — 次のページが利用可能かどうかを示します
  • total_items_count — アイテムの総数

リクエスト例：

GET /items?limit=20&offset=40

応答例：

{
  "items": [...],
  "has_more": true,
  "total_items_count": 135
}

応答がhas_more = falseを返すまで、後続のリクエストを送信することをお勧めします。

日付と時刻の形式

日付と時間の値は、ISO 8601フォーマットで渡されます。

以下がサポートされています：

  • UTCオフセット
  • アイテムの表示に時間制限がない場合はnull値
  • 一部のフィールドで使用されるUnixタイムスタンプ（秒単位）

フォーマット：YYYY-MM-DDTHH:MM:SS±HH:MM

例：2026-03-16T10:00:00+03:00

ローカリゼーション

エクソーラは、アイテム名や説明などのユーザー向けフィールドのローカライズをサポートしています。ローカライズされた値は、言語コードをキーとするオブジェクトとして渡されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。

サポートされているフィールド

次のパラメータに対してローカリゼーションを指定できます：

  • name
  • description
  • long_description

ロケール形式

ロケールキーは、以下のいずれかのフォーマットで指定できます：

  • 2文字の言語コード：en、ru
  • 5文字の言語コード： en-US、ru-RU、de-DE

例

2文字の言語コードの例：

{
  "name": {
    "en": "Starter Pack",
    "ru": "Стартовый набор"
  }
}

5文字の言語コードの例：

{
  "description": {
    "en-US": "Premium bundle",
    "de-DE": "Premium-Paket"
  }
}

エラー応答フォーマット

エラーが発生した場合、APIはHTTPステータスとJSON応答本文を返します。ストア関連のエラーの全リストはドキュメントで確認できます。

応答例：

{
  "errorCode": 1102,
  "errorMessage": "Validation error",
  "statusCode": 422,
  "transactionId": "c9e1a..."
}
  • errorCode — エラーコード。
  • errorMessage — 短いエラー説明。
  • statusCode — HTTP応答ステータス。
  • transactionId — リクエストID。一部の場合にのみ返されます。
  • errorMessageExtended — リクエストパラメータなどの追加エラー詳細。一部の場合にのみ返されます。

拡張応答例：

{
  "errorCode": 7001,
  "errorMessage": "Chain not found",
  "errorMessageExtended": {
    "chain_id": "test_chain_id",
    "project_id": "test_project_id",
    "step_number": 2
  },
  "statusCode": 404
}

共通のHTTPステータスコード

  • 400 — 無効なリクエスト
  • 401 — 認証エラー
  • 403 — 権限不足
  • 404 — リソースが見つかりません
  • 422 — 検証エラー
  • 429 — レート制限超過

推奨事項

  • HTTPステータスと応答本文を一緒に処理します。
  • errorCodeを使用してアプリケーションロジックに関連するエラーを処理します。
  • transactionIdを使用して、エラーを分析する際にリクエストをより迅速に特定します。
OpenAPI記述をダウンロード
index.json
index.yaml
言語
サーバー
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/ja/api/liveops/

概要

プロモーションは、新規ユーザーの獲得や売上の向上を目的としたマーケティングツールです。エクソーラAPIを使用することで、以下のようなプロモーションを設定できます：

  • 割引 — 選択したアイテムの価格を下げます。
  • ボーナス — 購入時に、商品とあわせてユーザーに付与されるアイテムです。
  • クーポン — 引き換え時1つ以上のボーナスアイテムを受け取ることができるコードです。
  • プロモーションコード — ボーナスアイテムの受け取り、特定アイテムの割引、またはカート全体の割引を可能にするコードです。入力後に引き換えるクーポンとは異なり、プロモーションコードは購入手続き中（チェックアウト時）に適用されます。
  • ユニークオファー — 専用のオファーコードを入力したユーザーにのみカタログに表示される、非公開のアイテムです。コードを入力しない限り、これらのアイテムは表示されません。

割引プロモーション設定のフロー例：

  1. 仮想アイテムと仮想通貨、バンドル、またはゲームキーグループの管理者サブセクションにあるAPIコールを使用して、アイテムを作成します。
  2. アイテムの割引プロモーション作成するコールを使用して、プロモーションを作成します。items配列内で、必要なアイテムのSKUを渡します。
  3. プロモーションの有効期間を設定します。設定するには、アイテムの割引プロモーションを作成するまたはアイテムのプロモーションを更新するメソッドを呼び出し、promotion_periodsフィールドを、オブジェクトの配列として渡します。ここで、date_fromは開始日を、date_untilは有効期間の終了日を定義します。
  4. アイテムプロモーションを更新するコールを使用して、プロモーションをアクティブ化します。"is_enabled": true パラメータを渡します。
  5. 割引価格を含むアイテム価格の情報を取得するには、共通 > カタログ、仮想アイテムと仮想通貨 > カタログ、またはバンドル > カタログのサブセクションにある、アイテムカタログ取得用のクライアントAPIメソッドを呼び出してください。

プロモーションの設定例

プロモーション設定の詳細については、ドキュメントを参照してください。

共通のAPIコール

このサブセクションのAPIメソッドを呼び出すことで、さまざまなタイプのプロモーションを管理できます。

操作

クーポン

クーポンプロモーションを設定または管理するには、本サブセクションのAPIメソッドを使用してください。

注

クーポンに関する詳細情報は、ドキュメントを参照してください。

操作

プロモーションコード

このサブセクションのAPIメソッドを呼び出して、プロモーションコードのプロモーションを設定および管理します。

注

プロモーションコードに関する詳細情報は、ドキュメントを参照してください。

操作

ユニークなカタログオファー

ユニークカタログオファーを設定または管理するには、本サブセクションのAPIメソッドを使用してください。

注

ユニークオファーに関する詳細情報は、ドキュメントを参照してください。

操作

ディスカウント

割引プロモーションを設定または管理するには、本サブセクションのAPIメソッドを使用してください。

注

割引に関する詳細情報は、ドキュメントを参照してください。

操作

ボーナス

ボーナスプロモーションを設定または管理するには、本サブセクションのAPIメソッドを使用してください。

注

ボーナスに関する詳細情報は、ドキュメントを参照してください。

操作

個人用カタログ

個人用設定機能を使用すると、認証された特定のユーザーに対してのみ、アイテムカタログの表示条件を設定したりプロモーションを適用したりすることができます。条件はユーザー属性に基づいて定義され、特定のユーザーに最も関連性の高いアイテムやプロモーションを提供できるようになります。

利用可能な個人用設定のタイプは次のとおりです：

  • エクソーラ側の個人用設定。個人用設定のルールとロジックはエクソーラ側で設定および保存されます。ユーザー属性を渡すと、エクソーラがそれを使用してパーソナライズされたカタログを生成します。
  • パートナー側の個人用設定。個人用設定のルールとロジックを自分の側で設定し、指定したユーザーに対する最終的なカタログペイロードをエクソーラに送信します。
注意

使用できる個人用設定のタイプは1つだけです。変更するには、 説明に従ってください。

エクソーラAPIを使用してエクソーラ側で個人用設定を構成するには：

  1. 仮想アイテムと仮想通貨、バンドル、またはゲームキーグループの管理者サブセクションにあるAPIコールを使用して、アイテムを作成します。

  2. エクソーラログインAPIを使用してユーザー属性をセットアップし、ゲーム内で変更が発生した場合はエクソーラ内のデータを更新して同期を保ちます。

  3. アイテムまたはプロモーションの個人用設定を設定します：

  4. ユーザー属性を含むユーザーJWTをカタログ取得APIコールに渡して、パーソナライズされたカタログを受け取ります。

アイテムカタログにおけるエクソーラ側パーソナライズの設定および適用手順：

アイテムカタログの個人用設定

プロモーションにおけるエクソーラ側パーソナライズの設定および適用手順：

プロモーションの個人用設定

注意

詳細情報は以下に提供されています：
操作

概要

プロモーション使用制限により、指定したユーザーがプロモーションを使用できる回数を制限できます。また、制限を定期的にリセットするスケジュールを設定することも可能です。

制限はエクソーラ側で保存され、パブリッシャーアカウントのプロモーション設定または次のAPIコールのlimitsオブジェクトを介して設定されます：

制限情報は、アイテムカタログを取得するための次のAPIコールでitems.promotions.limitsオブジェクトに返されます：

制限グループの管理サブセクションに属するAPIコールにより、制限の現在状態の取得、および指定したユーザーに対する制限値の更新が可能となります（例：クエスト完了時におけるカウンターのリセット、残存数量の手動調整など）。

注意

カタログでの制限設定の詳細については、プロモーション使用制限セクションを参照してください。

limits.per_user — 単一のユーザーがプロモーションを使用できる回数の制限を設定できます。

未認証のユーザーには、常にプロモーションの最大利用回数が表示されます。

有効な制限が適用されたユーザーの「残りのプロモーション利用回数」を表示するには、アイテムカタログをリクエストする際にユーザーの認証データを渡してください。

スケジュールされたリセット期間を設定するには — 毎日、毎週、または毎月 — プロモーションを作成または更新する際にlimits.recurrent_scheduleオブジェクトを渡します。

制限設定および適用シナリオ

  1. アイテムの割引プロモーションを作成するまたはボーナスプロモーションを作成するAPIコールを使用してプロモーションを作成し、limitsオブジェクトを渡します。
  2. 未認証のユーザーに対してカタログをリクエストします。応答のitems.promotions.limitsオブジェクトに、プロモーションの最大利用回数が返されます。
  3. ユーザーがログインします。
  4. ユーザーの認証トークンを含めてカタログをリクエストします。応答には、アクティブな制限が適用された状態の「残り利用回数」が返されます。
  5. ユーザーがプロモーション対象のアイテムを選択し、購入手続きを行います。
  6. 決済が正常に完了すると、エクソーラはitems.promotions.limits.per_userの値を更新します。この値が 0 に達すると、以降のカタログAPIコールのレスポンスにおいて、該当アイテムは割引やボーナスがない状態で返されるようになります。
  7. 管理サブセクションのAPIコールを使用して制限を更新できます：
  8. 次回、ユーザーの認証トークンを使用してカタログをリクエストした際に、items.promotions.limitsから更新された制限値を取得し、ユーザーに表示します。

プロモーション制限

管理

操作

概要

報酬チェーンは、ユーザーが実際通貨を使ってストアで購入を行うことを促進する機能です。購入ごとにユーザーはバリューポイントを獲得し、報酬チェーンを進めることができます。ユーザーがクランに所属している場合、その購入によって獲得したバリューポイントはクラン全体に付与されます。報酬チェーンの設定に関する詳細情報については、報酬システムのセクションを参照してください。

報酬チェーンを設定するには、管理者サブセクションのAPIコールを使用します。チェーンの表示や報酬のオファー受け取りを行うには、クライアントサブセクションのAPIコールを使用します。クラン報酬チェーンを操作するには、クランクライアントサブセクションのAPIコールを使用します。

報酬チェーンの設定フローの例：

  1. 仮想アイテムと仮想通貨またはバンドルグループの管理者サブセクションにあるAPIコールを使用して、アイテムを作成します。
  2. バリューポイントを作成する APIコールを使用して、バリューポイントを作成します。
  3. アイテムのバリューポイントを設定するAPIコールを使用して、バリューポイントを作成します。
  4. 報酬チェーンを作成するAPIコールを使用して、チェーンを作成します。チェーンをアクティブにするには、is_enabled: trueパラメータを渡します。
  5. 報酬チェーンの表示を実装します。これを行うには、現在のユーザーの報酬チェーンを取得するAPIコールを使用して、利用可能なチェーンのリストをリクエストします。応答には、すべてのアクティブなチェーンと、それらのステップおよびステータスが含まれています。
  6. バリューポイント残高の表示を実装します。これを行うには、現在のユーザーのバリューポイント残高を取得するAPIコールを使用します。
  7. ステップ報酬のオファー受け取りを実装します。これを行うには、ステップ報酬のオファーを受け取るAPIコールを使用します。
  8. 受け取った報酬に関するデータを迅速に受信し、それをユーザーに付与するために、ウェブフックなどを使用した注文状況の追跡を設定します。

報酬チェーンの設定フロー

管理者

操作

クライアント

操作

現在のユーザーの報酬チェーンを取得するClient-side

リクエスト

クライアントエンドポイント。現在のユーザー報酬チェーンを取得します。

注意

すべてのプロジェクトには、応答で取得できるアイテム数に制限があります。デフォルトおよび最大値は1応答あたり50アイテムです。ページごとにデータを取得するには、制限とオフセットフィールドを使用してください。

注意

このAPIコールはユーザーJWTを使用して認証を行います。

トークンはAuthorizationヘッダーへ次の形式でトークンを設定します：Bearer <user_JWT>。ユーザーJWTに関する詳細情報は、該当コールのセキュリティブロックで確認できます。
セキュリティ
XsollaLoginUserJWT
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
クエリ
limitinteger>= 1

ページでの要素数の制限。

例: limit=50
offsetinteger>= 0

リストが生成される要素番号（カウントは0から始まります）。

例: offset=0
curl -i -X GET \
  'https://store.xsolla.com/api/v2/project/44056/user/reward_chain?limit=50&offset=0' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

レスポンス

ユーザーの報酬チェーンが正常に取得されました。

ボディapplication/json
has_moreboolean

ページ数がもっとあることを示す指標として使用されます。

例: true
total_items_countinteger

システム内の報酬チェーンの総数。

例: 10
itemsArray of objects
items[].​reward_chain_idinteger

報酬チェーンID。

例: 9
items[].​namestring

報酬チェーン名。

例: "Weekly quest"
items[].​descriptionstring or null

Reward chain description.

例: "Major weekly quest"
items[].​long_descriptionstring or null

報酬チェーンの長い説明。

例: "You can get a lot of additional items just by shopping during the week"
items[].​image_urlstring or null

画像URL。

items[].​orderinteger

配列順序を定義します。

items[].​date_startstring(date-time)

報酬チェーンの開始日。

items[].​date_endstring or null(date-time)

報酬チェープロモーションが終了する日付。「null」も可能です。date_endがnullの場合、報酬チェーンは時間制限がありません。

items[].​clan_typestring or null

クランタイプ。

列挙型"clan""guild""faction""community""team""squad""alliance""association""coalition""union"
items[].​top_contributorsArray of objects or null
items[].​top_contributors[].​namestring

認証プロセス中にエクソーラに送信されるユーザーID。ユーザーIDは、ユーザーをエクソーラログインプロジェクトにリンクするために使用され、ニックネームとして表示されます。ユーザーID経由での認証を使用している場合は、ウェブフック応答でnameパラメータを渡すことをお勧めします。このパラメータには、ニックネームとして使用されるユーザー名が含まれています。

例: "Rocket"
items[].​top_contributors[].​contributed_amountinteger

ユーザーが獲得したバリューポイントの額。

例: 100
items[].​value_pointobject
items[].​value_point.​skustring

一意のバリューポイントID。

items[].​value_point.​namestring

バリューポイント名。

items[].​value_point.​image_urlstring

画像URL。

items[].​value_point.​descriptionstring or null

バリューポイントの説明。

items[].​value_point.​long_descriptionstring or null

バリューポイントの長い説明。

items[].​value_point.​amountinteger

バリューポイントの量。

items[].​value_point.​is_clanboolean

バリューポイントがクランリワードチェーンで使用されるかどうか。

items[].​stepsArray of objects
items[].​steps[].​step_idinteger

ステップID。

例: 10
items[].​steps[].​namestring

ステップ名。

例: "Level 1"
items[].​steps[].​is_claimedboolean

ステップ報酬が請求されるかどうか。

例: false
items[].​steps[].​image_urlstring

画像URL。

items[].​steps[].​priceobject
items[].​steps[].​price.​amountinteger

ユーザーがそのステップに対して請求したバリューポイントの数。

例: 100
items[].​steps[].​rewardArray of objects
items[].​steps[].​reward[].​skustring[ 1 .. 255 ] characters^[a-zA-Z0-9_\-–.]*$

一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。

items[].​steps[].​reward[].​namestring

アイテム名。

例: "Super box"
items[].​steps[].​reward[].​typestring

アイテムタイプ。

例: "bundle"
items[].​steps[].​reward[].​descriptionstring

Item description.

例: "Super box with items"
items[].​steps[].​reward[].​image_urlstring

画像URL。

items[].​steps[].​reward[].​quantityinteger

アイテム数量。

例: 2
items[].​recurrent_scheduleobject or null

報酬チェーンの定期リセット期間。

items[].​recurrent_schedule.​interval_typestring
One of:

報酬チェーンの定期リセット頻度。

string
値"weekly"
items[].​recurrent_schedule.​reset_next_dateinteger

計算された報酬チェーンが次回にリセットされる日時Unixタイムスタンプ。

例えば、報酬チェーンは2024年3月1日01:00（クアラルンプール時間 GMT+8）から毎月リセットされます。報酬チェーンが次回にリセットされる日時：2024年4月1日01:00（クアラルンプール時間 GMT+8）。これは、2024年3月31日17:00 GMT+0またはUnixタイムスタンプのフォーマットで1711904400000に相当します。

例：1711904400000

items[].​popup_headerobject or null

クラン報酬チェーンツールチップポップアップウィンドウのヘッダーのローカライズ付きオブジェクト。 小文字の2文字言語コード。

items[].​popup_header.​enstring or null
例: "How to unlock rewards"
items[].​popup_header.​arstring or null
例: null
items[].​popup_header.​bgstring or null
例: null
items[].​popup_header.​cnstring or null
例: null
items[].​popup_header.​csstring or null
例: null
items[].​popup_header.​destring or null
例: "Wie man Belohnungen freischaltet"
items[].​popup_header.​esstring or null
例: "Cómo desbloquear recompensas"
items[].​popup_header.​frstring or null
例: "Comment débloquer des récompenses"
items[].​popup_header.​hestring or null
例: null
items[].​popup_header.​itstring or null
例: "Come sbloccare ricompense"
items[].​popup_header.​jastring or null
例: "報酬をアンロックする方法"
items[].​popup_header.​kostring or null
例: null
items[].​popup_header.​plstring or null
例: null
items[].​popup_header.​ptstring or null
例: null
items[].​popup_header.​rostring or null
例: null
items[].​popup_header.​rustring or null
例: null
items[].​popup_header.​thstring or null
例: null
items[].​popup_header.​trstring or null
例: null
items[].​popup_header.​twstring or null
例: null
items[].​popup_header.​vistring or null
例: null
items[].​popup_instructionobject or null

クラン報酬チェーンツールチップポップアップウィンドウに関する説明のローカライズ付きオブジェクト。 小文字の2文字言語コード。

items[].​popup_instruction.​enstring or null
例: "You must be a clan member to get clan rewards. You join a clan when a clan member invites you to the clan, and you accept the invite. You can also create your own clan."
items[].​popup_instruction.​arstring or null
例: null
items[].​popup_instruction.​bgstring or null
例: null
items[].​popup_instruction.​cnstring or null
例: null
items[].​popup_instruction.​csstring or null
例: null
items[].​popup_instruction.​destring or null
例: "Du musst ein Clanmitglied sein, um Clananreize zu erhalten. Du trittst einem Clan bei, wenn ein Clanmitglied dich einlädt, und du die Einladung annimmst. Du kannst auch deinen eigenen Clan erstellen."
items[].​popup_instruction.​esstring or null
例: "Debes ser miembro de un clan para obtener las recompensas del clan. Te unes a un clan cuando un miembro del clan te invita al clan y aceptas la invitación. También puedes crear tu propio clan."
items[].​popup_instruction.​frstring or null
例: "Vous devez être membre d'un clan pour obtenir les récompenses du clan. Vous rejoignez un clan lorsque qu'un membre du clan vous invite au clan et que vous acceptez l'invitation. Vous pouvez également créer votre propre clan."
items[].​popup_instruction.​hestring or null
例: null
items[].​popup_instruction.​itstring or null
例: "Devi essere un membro del clan per ottenere le ricompense del clan. Ti unisci a un clan quando un membro del clan ti invita al clan e accetti l'invito. Puoi anche creare il tuo clan."
items[].​popup_instruction.​jastring or null
例: "クランリワードを受け取るには、クランメンバーでなければなりません。 クランメンバーがあなたをクランに招待し、招待を受け入れると、クランに参加できます。 あなた自身のクランを作成することもできます。"
items[].​popup_instruction.​kostring or null
例: null
items[].​popup_instruction.​plstring or null
例: null
items[].​popup_instruction.​ptstring or null
例: null
items[].​popup_instruction.​rostring or null
例: null
items[].​popup_instruction.​rustring or null
例: null
items[].​popup_instruction.​thstring or null
例: null
items[].​popup_instruction.​trstring or null
例: null
items[].​popup_instruction.​twstring or null
例: null
items[].​popup_instruction.​vistring or null
例: null
items[].​popup_image_urlstring or null(uri)

クラン報酬チェーンのツールチップポップアップウィンドウの画像。

レスポンス
application/json
{
  "has_more": false,
  "total_items_count": 1,
  "items": [
    { … },
    { … }
  ]
}

現在のユーザーのバリューポイント残高を取得するClient-side

リクエスト

クライアント向けエンドポイント。現在のユーザーのバリューポイント残高を取得します。

注意

このAPIコールはユーザーJWTを使用して認証を行います。

トークンはAuthorizationヘッダーへ次の形式でトークンを設定します：Bearer <user_JWT>。ユーザーJWTに関する詳細情報は、該当コールのセキュリティブロックで確認できます。
セキュリティ
XsollaLoginUserJWT
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
reward_chain_idinteger必須

報酬チェーンID。

例: 101
curl -i -X GET \
  https://store.xsolla.com/api/v2/project/44056/user/reward_chain/101/balance \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

レスポンス

ユーザーのバリューポイント残高が正常に取得されました。

ボディapplication/json
skustring

一意のバリューポイントID。

namestring

バリューポイント名。

image_urlstring

画像URL。

descriptionstring or null

バリューポイントの説明。

long_descriptionstring or null

バリューポイントの長い説明。

amountinteger

バリューポイントの数量。

is_clanboolean

バリューポイントがクランリワードチェーンで使用されるかどうか。

レスポンス
application/json
{
  "sku": "com.xsolla.value_point_1",
  "name": "Value point",
  "image_url": "https://cdn3.xsolla.com/img/misc/images/54c0cf9d345817cdacfdde198db178e0.jpg",
  "description": null,
  "long_description": null,
  "amount": 130,
  "is_clan": false
}

ステップ報酬を請求するClient-side

リクエスト

クライアント向けエンドポイント。現在のユーザーが、報酬チェーンから現在のステップの報酬を受け取ります。

注意

このAPIコールはユーザーJWTを使用して認証を行います。

トークンはAuthorizationヘッダーへ次の形式でトークンを設定します：Bearer <user_JWT>。ユーザーJWTに関する詳細情報は、該当コールのセキュリティブロックで確認できます。
セキュリティ
XsollaLoginUserJWT
パス
project_idinteger必須

プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。

例: 44056
reward_chain_idinteger必須

報酬チェーンID。

例: 101
step_idinteger必須

報酬チェーンのステップID。

例: 120
curl -i -X POST \
  https://store.xsolla.com/api/v2/project/44056/user/reward_chain/101/step/120/claim \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

レスポンス

現在のユーザーのステップ報酬を報酬チェーンから取得することに成功しました。

レスポンス
コンテンツなし

クランクライアント

操作

管理者

操作

クライアント

操作

概要

オファーチェーンとは、アクティブなオファーの一環として、ユーザーが無料、または購入によって獲得できるアイテムが含まれた一連のステップのことです。オファーチェーンには、チェーン内でのみ入手できる限定アイテムや、通常のストア価格よりも割引された価格のアイテムを含めることができます。このマーケティングツールの設定に関する詳細な情報については、オファーチェーンセクションを参照してください。

オファーチェーンを構成するには、管理者サブセクションのAPIコールを使用します。チェーンを表示し、ユーザーが獲得するアイテムを処理するためのロジックを実装するには、クライアントサブセクションのAPIコールを使用します。

オファーチェーンの設定フローの例：

  1. 仮想アイテムと仮想通貨またはバンドルグループの管理者サブセクションにあるAPIコールを使用して、アイテムを作成します。

  2. オファーチェーンを作成するAPIコールを使用して、チェーンを作成します。チェーンをアクティブにするには、is_enabled: trueパラメータを渡します。

  3. オファーチェーンの表示を実装します。これを行うには現在のユーザーのオファーチェーンを取得する APIコールを使用して、利用可能なチェーンのリストをリクエストします。応答には、すべてのアクティブなチェーンと、それらのステップおよびステータスが含まれています。

  4. ユーザーが獲得するアイテムを処理するためのロジックを実装します：

  5. オファーを受け取った、または購入したアイテムに関するデータを迅速に受信し、それをユーザーに付与するために、ウェブフックなどを使用した注文状況の追跡を設定します。

報酬チェーンの設定フロー

管理者

操作

クライアント

操作

管理者

操作

クライアント

操作