コンテンツへスキップ
/
ユニークなカタログオファープロモーションを削除

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メソッドを使用してください。

注

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

操作

ユニークなカタログオファープロモーションを取得Server-side管理者

リクエスト

指定されたユニークなカタログオファープロモーションを取得します。

セキュリティ
basicAuth
パス
project_idinteger必須

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

例: 44056
external_idinteger必須

プロモーションexternal ID。プロジェクト内での一意のプロモーション識別子。

例: coupon_44056_1
curl -i -X GET \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/unique_catalog_offer/coupon_44056_1

レスポンス

ユニークなカタログオファーは正常に受信されました。

ボディapplication/json
external_idstring

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

promotion_periodsArray of objects

プロモーションの有効期間。複数の期間を指定する場合は、date_fromとdate_untilの両方が必須となります。

promotion_periods[].​date_fromstring(date-time)必須

指定されたプロモーションの開始日。

例: "2020-08-11T10:00:00+03:00"
promotion_periods[].​date_untilstring or null(date-time)

指定されたプロモーションの終了日。nullに設定した場合、プロモーションは無期限となります。単一の有効期間のみが指定されている場合に限り、nullに設定可能です。

例: "2020-08-11T20:00:00+03:00"
nameobject

プロモーションの名前。キーと値のペアを含む必要があります。 キーは"^[a-z]{2}-[A-Z]{2}$"形式のロケール、値は文字列です。

name.​property name*string追加プロパティ
itemsArray of strings

ユニークカタログオファー使用後に利用可能なアイテムSKUリスト。

例: ["booster_mega_1"]
is_enabledboolean
redeem_total_limitinteger or null

クーポンの総数を制限します。

redeem_user_limitinteger or null

一人のユーザーが引き換えできるクーポンの総数を制限します。

redeem_code_limitinteger or null

コードごとの引き換え回数。

total_limit_stateobject or null

各クーポンコードには制限があります。

total_limit_state.​availableinteger

クーポンの残り使用可能回数。

例: 3
total_limit_state.​reservedinteger

クーポンの予約番号。

例: 3
total_limit_state.​usedinteger

クーポンの使用回数。

例: 5
レスポンス
application/json
{
  "external_id": "secret_shop",
  "promotion_periods": [
    { … },
    { … }
  ],
  "name": {
    "en-US": "Secret shop",
    "ru-RU": "Секретный магазин"
  },
  "items": [
    "helmet",
    "sword",
    "shield"
  ],
  "is_enabled": true,
  "redeem_user_limit": 1,
  "redeem_total_limit": 100,
  "redeem_code_limit": 1,
  "total_limit_state": {
    "available": 50,
    "reserved": 10,
    "used": 40
  }
}

ユニークなカタログオファープロモーションを削除Server-side管理者

リクエスト

ユニークなカタログオファープロモーションを削除します。削除されたプロモーション：

  • プロジェクトで設定されたプロモーションのリストから消えます。
  • アイテムカタログとカートに適用されなくなります。

削除後、プロモーションを復元することはできません。

セキュリティ
basicAuth
パス
project_idinteger必須

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

例: 44056
external_idinteger必須

プロモーションexternal ID。プロジェクト内での一意のプロモーション識別子。

例: coupon_44056_1
curl -i -X DELETE \
  -u <username>:<password> \
  https://store.xsolla.com/api/v3/project/44056/admin/unique_catalog_offer/coupon_44056_1

レスポンス

ユニークなカタログオファーは正常に削除されました。

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

ユニークなカタログオファープロモーションをアクティブ化にするServer-side管理者

リクエスト

ユニークなカタログオファープロモーションをアクティブ化にします。 作成されたユニークなカタログオファープロモーションは、デフォルトでは無効になっています。 アクティブ化するまで引き換えることはできません。 このエンドポイントを使用して、クーポンプロモーションを有効化およびアクティブ化します。

セキュリティ
basicAuth
パス
project_idinteger必須

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

例: 44056
external_idinteger必須

プロモーションexternal ID。プロジェクト内での一意のプロモーション識別子。

例: coupon_44056_1
curl -i -X PUT \
  -u <username>:<password> \
  https://store.xsolla.com/api/v2/project/44056/admin/unique_catalog_offer/coupon_44056_1/activate

レスポンス

ユニークなカタログオファーが正常にアクティブ化されました。

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

ディスカウント

割引プロモーションを設定または管理するには、本サブセクションの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. 受け取った報酬に関するデータを迅速に受信し、それをユーザーに付与するために、ウェブフックなどを使用した注文状況の追跡を設定します。

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

管理者

操作

クライアント

操作

クランクライアント

操作

管理者

操作

クライアント

操作

概要

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

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

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

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

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

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

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

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

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

管理者

操作

クライアント

操作

管理者

操作

クライアント

操作