Conditions for validating user attributes. Determine chain availability based on whether user attributes match all specified conditions.
/
オファーチェーンを更新する
LiveOps API (2.0.0)
- バージョン: 2.0.0
- サーバー:
https://store.xsolla.com/api - メールでのお問い合わせ
- お問い合わせURL： https://xsolla.com/
- 必要なTLSバージョン： 1.2
LiveOpsは、プロモーションやパーソナライズされたオファーを通じて、プレイヤーの継続的なエンゲージメントを高めるためのツールキットです。
APIを使用して、以下の機能を管理できます：
- プロモーション — クーポン、プロモコード、割引、ボーナスキャンペーンを作成または管理します。
- 個人用設定 — アイテムカタログの表示や、特定の認証済みユーザーのみにプロモーションを適用するための条件を指定します。
- プロモーション制限 — ユーザーがプロモーションを利用できる回数の上限を設定し、これらの制限を定期的にリセットするスケジュールを構成します。
- 報酬チェーンとバリューポイント — バリューポイントの蓄積に連動した報酬進行度を構成します。
- デイリーチェーン — 定期的なログインを促すために、繰り返し受け取れるデイリー報酬を設定します。
- オファーチェーン — ステップごとの価格設定や無料リワードのオプションを含む、段階的な購入オファーを構築します。
- アップセル — ユーザーに対して、追加の価値を持つアイテムの購入を促す販売手法です。
APIは次のグループに分かれています：
Admin — キャンペーンとチェーン設定の作成、更新、アクティブ化、削除のためのコールです。マーチャントまたはプロジェクトの認証情報を使用した基本アクセス認証によって認証されます。Client — 認証済みエンドユーザーの代理として、利用可能なプロモーションの取得、アクティブなチェーンの取得、コードの引き換え、よび報酬の請求を実行するAPIコール。ユーザーのJWTにより認証を行います。
ユーザーのJWTを使用した認証は、ブラウザ、モバイルアプリケーション、またはゲームからリクエストが送信される場合に使用されます。デフォルトでは、XsollaLoginUserJWTスキームが適用されます。トークンの作成方法の詳細については、エクソーラログインAPIに関するドキュメントを参照してください。
トークンはAuthorizationヘッダーに次の形式で渡されます：Authorization: Bearer <user_JWT>。ここで<user_JWT>はユーザートークンです。このトークンによってユーザーが特定され、パーソナライズされたデータへのアクセスが可能になります。
別の方法として、決済UIを開くためのトークンを使用することも可能です。
基本HTTP認証は、ユーザーのブラウザやモバイルアプリケーションからではなく、サーバーから直接APIコールが送信される場合のサーバー間のやり取りに使用されます。通常、APIキーを使用したHTTP基本認証が使用されます。
注意
APIキーは機密性高いため、クライアントアプリケーション側での保存および使用は厳禁とします。
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コールに
必要なAPIコールに
project_idパスパラメータが含まれていない場合、認証を行うには、会社のすべてのプロジェクト共通で有効なAPIキーを使用してください。APIキーの操作に関する詳細は、APIリファレンスを参照してください。
AuthForCart認証スキームはカートでの購入用であり、以下の2つのモードに対応しています：
ユーザーのJWTによる認証。 トークンは
Authorizationヘッダーで次の形式で渡されます：Authorization: Bearer <user_JWT>、ここで<user_JWT>はユーザートークンです。このトークンによってユーザーが特定され、パーソナライズされたデータへのアクセスが可能になります。あるいは、決済UIを開くためのトークンを使用することもできます。認証ヘッダーを使用しない簡易モード。 このモードは未認証ユーザーにのみ使用され、ゲームキー販売にのみ適用できます。リクエストにはトークンの代わりに、以下のヘッダーを含める必要があります：
- リクエストIDを含む
x-unauthorized-id - Base64でエンコードされたユーザーのメールアドレスを含む
x-user
- リクエストIDを含む
すべてのタイプ（仮想アイテム、バンドル、仮想通貨、キー）のアイテムは、同様のデータ構造を使用しています。この基本構造を理解することで、APIの利用が簡素化され、ドキュメントをよりスムーズに読み進められるようになります。
注意
一部のコールには追加のフィールドが含まれる場合がありますが、基本構造が変わることはありません。
一部のコールには追加のフィールドが含まれる場合がありますが、基本構造が変わることはありません。
識別
merchant_id— パブリッシャーアカウントにおける会社IDproject_id— パブリッシャーアカウントにおけるプロジェクトIDsku— アイテムSKU、プロジェクト内で一意です
ストア表示
name— アイテム名description— アイテム説明image_url— 画像URLis_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コールはリクエスト時にストアで現在利用可能なアイテムを返します。まだ利用可能でない、または利用できなくなったアイテムを取得するには、カタログリクエストにパラメータ
"show_inactive_time_limited_items": 1を含めてください。
アイテムは以下の方法で販売できます：
- 迅速な購入 — 1つのSKUを複数回販売します。
- カート購入 — ユーザーがアイテムをカートに追加し、アイテムを削除し、単一の注文内で数量を更新します。
アイテムが実際のお金ではなく仮想通貨で購入された場合は、仮想通貨で購入した指定アイテムで注文を作成するAPIコールを使用してください。当該APIコールの実行時に課金処理が行われるため、決済UIを表示する必要はありません。
無料アイテムの購入には、指定した無料アイテムで注文を作成するAPIコールまたは無料カートで注文を作成するAPIコールを使用してください。決済UIを表示する必要はありません。注文は即時にdoneステータスに設定されます。
クライアント側のAPIコールを使用して、指定したアイテムで注文を作成します。このコールは、決済UIを開くために使用するトークンを返します。
注意
割引情報は決済UIでのみユーザーに提供されます。プロモーションコードはサポートされていません。
割引情報は決済UIでのみユーザーに提供されます。プロモーションコードはサポートされていません。
カートの設定と購入は、クライアントまたはサーバー側で実行できます。
クライアント側でのカートのセットアップと購入
アイテムの追加および削除のロジックは、独自に実装してください。カートを設定するためのAPIを呼び出す前は、購入にどのプロモーションが適用されるかに関する情報は取得できません。つまり、合計金額や、追加されるボーナスアイテムの詳細を事前に知ることはできません。
以下のカートロジックを実装します：
- プレイヤーがカートにアイテムを入れた後、カートにアイテムを入れるAPIコールを使用します。このコールは、選択されたアイテムに関する現在の情報（割引前後の価格、ボーナスアイテム）を返します。
- ユーザーのアクションに基づいてカートの内容を更新します：
- アイテムの追加または数量の変更を行うには、カートIDでカートアイテムを更新するAPIコールを使用します。
- アイテムを削除するには、カートIDでカートアイテムを削除するAPIコールを使用します。
注意
カートの現在のステータスを取得するには、現在のユーザーのカートを取得するAPIコールを使用してください。
カートの現在のステータスを取得するには、現在のユーザーのカートを取得するAPIコールを使用してください。
- 現在のカートからすべてのアイテムで注文を作成するAPIコールを使用します。このコールは注文IDと決済トークンを返します。新しく作成された注文はデフォルトで
newステータスに設定されます。
サーバー側でのカートのセットアップと購入
カートへの変更ごとにAPIコールを伴う必要があるため、この設定オプションではカートの設定に時間がかかる場合があります。
以下のカートロジックを実装します：
- プレイヤーがカートにアイテムを入れた後、カートにアイテムを入れるAPIコールを使用します。このコールは、選択されたアイテムに関する現在の情報（割引前後の価格、ボーナスアイテム）を返します。
- 現在のカートのすべてのアイテムで注文を作成するAPIコールを使用します。このコールは、注文IDと支払いトークンを返します。新しく作成された注文は、デフォルトで
newステータスに設定されます。
返されたトークンを使用して、新しいウィンドウで決済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
エクソーラは、アイテム名や説明などのユーザー向けフィールドのローカライズをサポートしています。ローカライズされた値は、言語コードをキーとするオブジェクトとして渡されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
サポートされているフィールド
次のパラメータに対してローカリゼーションを指定できます：
namedescriptionlong_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記述をダウンロード
言語
サーバー
https://store.xsolla.com/api/
Mock server
https://xsolla.redocly.app/_mock/ja/api/liveops/
概要
プロモーションは、新規ユーザーの獲得や売上の向上を目的としたマーケティングツールです。エクソーラAPIを使用することで、以下のようなプロモーションを設定できます：
- 割引 — 選択したアイテムの価格を下げます。
- ボーナス — 購入時に、商品とあわせてユーザーに付与されるアイテムです。
- クーポン — 引き換え時1つ以上のボーナスアイテムを受け取ることができるコードです。
- プロモーションコード — ボーナスアイテムの受け取り、特定アイテムの割引、またはカート全体の割引を可能にするコードです。入力後に引き換えるクーポンとは異なり、プロモーションコードは購入手続き中（チェックアウト時）に適用されます。
- ユニークオファー — 専用のオファーコードを入力したユーザーにのみカタログに表示される、非公開のアイテムです。コードを入力しない限り、これらのアイテムは表示されません。
割引プロモーション設定のフロー例：
- 仮想アイテムと仮想通貨、バンドル、またはゲームキーグループの管理者サブセクションにあるAPIコールを使用して、アイテムを作成します。
- アイテムの割引プロモーション作成するコールを使用して、プロモーションを作成します。
items配列内で、必要なアイテムのSKUを渡します。 - プロモーションの有効期間を設定します。設定するには、アイテムの割引プロモーションを作成するまたはアイテムのプロモーションを更新するメソッドを呼び出し、
promotion_periodsフィールドを、オブジェクトの配列として渡します。ここで、date_fromは開始日を、date_untilは有効期間の終了日を定義します。 - アイテムプロモーションを更新するコールを使用して、プロモーションをアクティブ化します。
"is_enabled": trueパラメータを渡します。 - 割引価格を含むアイテム価格の情報を取得するには、共通 > カタログ、仮想アイテムと仮想通貨 > カタログ、またはバンドル > カタログのサブセクションにある、アイテムカタログ取得用のクライアントAPIメソッドを呼び出してください。
プロモーション設定の詳細については、ドキュメントを参照してください。
クーポン
クーポンプロモーションを設定または管理するには、本サブセクションのAPIメソッドを使用してください。
注
クーポンに関する詳細情報は、ドキュメントを参照してください。
操作
プロモーションコード
このサブセクションのAPIメソッドを呼び出して、プロモーションコードのプロモーションを設定および管理します。
注
プロモーションコードに関する詳細情報は、ドキュメントを参照してください。
操作
ユニークなカタログオファー
ユニークカタログオファーを設定または管理するには、本サブセクションのAPIメソッドを使用してください。
注
ユニークオファーに関する詳細情報は、ドキュメントを参照してください。
操作
ディスカウント
割引プロモーションを設定または管理するには、本サブセクションのAPIメソッドを使用してください。
注
割引に関する詳細情報は、ドキュメントを参照してください。
操作
ボーナス
ボーナスプロモーションを設定または管理するには、本サブセクションのAPIメソッドを使用してください。
注
ボーナスに関する詳細情報は、ドキュメントを参照してください。
操作
個人用カタログ
個人用設定機能を使用すると、認証された特定のユーザーに対してのみ、アイテムカタログの表示条件を設定したりプロモーションを適用したりすることができます。条件はユーザー属性に基づいて定義され、特定のユーザーに最も関連性の高いアイテムやプロモーションを提供できるようになります。
利用可能な個人用設定のタイプは次のとおりです：
- エクソーラ側の個人用設定。個人用設定のルールとロジックはエクソーラ側で設定および保存されます。ユーザー属性を渡すと、エクソーラがそれを使用してパーソナライズされたカタログを生成します。
- パートナー側の個人用設定。個人用設定のルールとロジックを自分の側で設定し、指定したユーザーに対する最終的なカタログペイロードをエクソーラに送信します。
エクソーラAPIを使用してエクソーラ側で個人用設定を構成するには：
仮想アイテムと仮想通貨、バンドル、またはゲームキーグループの管理者サブセクションにあるAPIコールを使用して、アイテムを作成します。
エクソーラログインAPIを使用してユーザー属性をセットアップし、ゲーム内で変更が発生した場合はエクソーラ内のデータを更新して同期を保ちます。
アイテムまたはプロモーションの個人用設定を設定します：
- アイテムカタログをパーソナライズするには、カタログフィルタルールを作成するAPIコールを使用してカタログの表示ルールを定義します：
- attribute_conditions配列で、ユーザー属性に基づいてアイテムの可用性を決定する条件を指定します。
- items配列で、指定された条件に一致するユーザーに表示されるべきアイテムのリストを提供します。
- パーソナライズされたプロモーションを設定するには、必要なプロモーションタイプのAPIコールを作成または更新するを使用します。attribute_conditions配列で、ユーザー属性に基づいてプロモーションの可用性を決定する条件を指定します。
- アイテムカタログをパーソナライズするには、カタログフィルタルールを作成するAPIコールを使用してカタログの表示ルールを定義します：
ユーザー属性を含むユーザーJWTをカタログ取得APIコールに渡して、パーソナライズされたカタログを受け取ります。
アイテムカタログにおけるエクソーラ側パーソナライズの設定および適用手順：
プロモーションにおけるエクソーラ側パーソナライズの設定および適用手順：
操作
概要
プロモーション使用制限により、指定したユーザーがプロモーションを使用できる回数を制限できます。また、制限を定期的にリセットするスケジュールを設定することも可能です。
制限はエクソーラ側で保存され、パブリッシャーアカウントのプロモーション設定または次のAPIコールのlimitsオブジェクトを介して設定されます：
制限情報は、アイテムカタログを取得するための次のAPIコールでitems.promotions.limitsオブジェクトに返されます：
制限グループの管理サブセクションに属するAPIコールにより、制限の現在状態の取得、および指定したユーザーに対する制限値の更新が可能となります（例：クエスト完了時におけるカウンターのリセット、残存数量の手動調整など）。
limits.per_user — 単一のユーザーがプロモーションを使用できる回数の制限を設定できます。
未認証のユーザーには、常にプロモーションの最大利用回数が表示されます。
有効な制限が適用されたユーザーの「残りのプロモーション利用回数」を表示するには、アイテムカタログをリクエストする際にユーザーの認証データを渡してください。
スケジュールされたリセット期間を設定するには — 毎日、毎週、または毎月 — プロモーションを作成または更新する際にlimits.recurrent_scheduleオブジェクトを渡します。
制限設定および適用シナリオ
- アイテムの割引プロモーションを作成するまたはボーナスプロモーションを作成するAPIコールを使用してプロモーションを作成し、
limitsオブジェクトを渡します。 - 未認証のユーザーに対してカタログをリクエストします。応答の
items.promotions.limitsオブジェクトに、プロモーションの最大利用回数が返されます。 - ユーザーがログインします。
- ユーザーの認証トークンを含めてカタログをリクエストします。応答には、アクティブな制限が適用された状態の「残り利用回数」が返されます。
- ユーザーがプロモーション対象のアイテムを選択し、購入手続きを行います。
- 決済が正常に完了すると、エクソーラは
items.promotions.limits.per_userの値を更新します。この値が 0 に達すると、以降のカタログAPIコールのレスポンスにおいて、該当アイテムは割引やボーナスがない状態で返されるようになります。 - 管理サブセクションのAPIコールを使用して制限を更新できます：
- 次回、ユーザーの認証トークンを使用してカタログをリクエストした際に、
items.promotions.limitsから更新された制限値を取得し、ユーザーに表示します。
概要
報酬チェーンは、ユーザーが実際通貨を使ってストアで購入を行うことを促進する機能です。購入ごとにユーザーはバリューポイントを獲得し、報酬チェーンを進めることができます。ユーザーがクランに所属している場合、その購入によって獲得したバリューポイントはクラン全体に付与されます。報酬チェーンの設定に関する詳細情報については、報酬システムのセクションを参照してください。
報酬チェーンを設定するには、管理者サブセクションのAPIコールを使用します。チェーンの表示や報酬のオファー受け取りを行うには、クライアントサブセクションのAPIコールを使用します。クラン報酬チェーンを操作するには、クランクライアントサブセクションのAPIコールを使用します。
報酬チェーンの設定フローの例：
- 仮想アイテムと仮想通貨またはバンドルグループの管理者サブセクションにあるAPIコールを使用して、アイテムを作成します。
- バリューポイントを作成する APIコールを使用して、バリューポイントを作成します。
- アイテムのバリューポイントを設定するAPIコールを使用して、バリューポイントを作成します。
- 報酬チェーンを作成するAPIコールを使用して、チェーンを作成します。チェーンをアクティブにするには、
is_enabled: trueパラメータを渡します。 - 報酬チェーンの表示を実装します。これを行うには、現在のユーザーの報酬チェーンを取得するAPIコールを使用して、利用可能なチェーンのリストをリクエストします。応答には、すべてのアクティブなチェーンと、それらのステップおよびステータスが含まれています。
- バリューポイント残高の表示を実装します。これを行うには、現在のユーザーのバリューポイント残高を取得するAPIコールを使用します。
- ステップ報酬のオファー受け取りを実装します。これを行うには、ステップ報酬のオファーを受け取るAPIコールを使用します。
- 受け取った報酬に関するデータを迅速に受信し、それをユーザーに付与するために、ウェブフックなどを使用した注文状況の追跡を設定します。
概要
Daily rewards motivate users to log into the store every day to receive free items. The behavior when a day is skipped depends on the chain type. For daily rewards to work correctly, you need to configure user authentication. Unauthenticated users can see the full daily reward chain but cannot claim rewards. For detailed information on configuring daily rewards, refer to the Daily rewards section.
Chains are configured using the API calls from the Admin subsection. To grant rewards, use the API calls from the Client subsection.
Daily chain configuration scenario:
- Create items using the API calls from the Admin subsection of the Virtual items and currency or Bundles groups.
- Create a chain using the Create daily reward API call.
- Activate the chain by passing the
"is_enabled": trueparameter to the Create daily reward API call. - Request the list of available chains using the Get current user's daily rewards API call, passing the user JWT. The response contains all active chains with their steps and statuses.
- Set up item granting via webhooks.
- Grant the user their daily reward using the Claim daily reward step API call, passing
daily_chain_idandstep_number.
概要
オファーチェーンとは、アクティブなオファーの一環として、ユーザーが無料、または購入によって獲得できるアイテムが含まれた一連のステップのことです。オファーチェーンには、チェーン内でのみ入手できる限定アイテムや、通常のストア価格よりも割引された価格のアイテムを含めることができます。このマーケティングツールの設定に関する詳細な情報については、オファーチェーンセクションを参照してください。
オファーチェーンを構成するには、管理者サブセクションのAPIコールを使用します。チェーンを表示し、ユーザーが獲得するアイテムを処理するためのロジックを実装するには、クライアントサブセクションのAPIコールを使用します。
オファーチェーンの設定フローの例：
仮想アイテムと仮想通貨またはバンドルグループの管理者サブセクションにあるAPIコールを使用して、アイテムを作成します。
オファーチェーンを作成するAPIコールを使用して、チェーンを作成します。チェーンをアクティブにするには、
is_enabled: trueパラメータを渡します。オファーチェーンの表示を実装します。これを行うには現在のユーザーのオファーチェーンを取得する APIコールを使用して、利用可能なチェーンのリストをリクエストします。応答には、すべてのアクティブなチェーンと、それらのステップおよびステータスが含まれています。
ユーザーが獲得するアイテムを処理するためのロジックを実装します：
ステップアイテムが無料の場合、無料オファーチェーンステップを受け取るAPIコールを使用します。リクエスト内に
offer_chain_idとstep_numberを渡してください。ステップアイテムが有料の場合、有料オファーチェーンステップの注文を作成するAPIコールを使用します。リクエスト内に
offer_chain_idとstep_numberを渡してください。レスポンスとして、order_idと決済UIを開くためのトークンが返されます。
オファーを受け取った、または購入したアイテムに関するデータを迅速に受信し、それをユーザーに付与するために、ウェブフックなどを使用した注文状況の追跡を設定します。
パス
プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
例: 44056
- https://store.xsolla.com/api/v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}
- Mock serverhttps://xsolla.redocly.app/_mock/ja/api/liveops/v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/offer_chain/id/101オファーチェーンのデータが正常に取得されました。
アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
Any of:
2文字の小文字の言語コード。
アイテムの説明に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
Any of:
2文字の小文字の言語コード。
オファーチェーンのステップが無料であるかどうかを示します：
trueの場合、ステップは無料オファーチェーンステップを請求するコールを使用して請求する必要があります。falseの場合、有料オファーチェーンステップの注文を作成するコールを使用して購入する必要があります。
商品価格通貨。ISO 4217 による3文字コード。
一意のアイテムID。SKUには、小文字と大文字のラテン英数字、ピリオド、ダッシュ、およびアンダースコアのみが含まれます。
アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
Any of:
2文字の小文字の言語コード。
アイテムの説明に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
Any of:
2文字の小文字の言語コード。
報酬チェーンをすべてのユーザーに表示するかどうかを設定します。trueの場合、ユーザーの認証ステータスや属性に関わらず、チェーンは常に表示されます。
個人用設定を設定するには、falseを渡す必要があります。チェーンの表示ロジックは以下のようになります：
falseが渡され、かつattribute_conditions配列に表示条件が指定されている場合、そのチェーンはパーソナライズされているとみなされ、指定された条件を満たす認証されたユーザーにのみ表示されます。falseが渡され、かつattribute_conditions配列が渡されないか空である場合、チェーンは未認証のユーザーに表示されます。また、認証されたユーザーに対して一致するチェーンが見つからない場合にも表示されます。
One of:
条件によって実行される操作のタイプ。string属性タイプの場合。
可能な値：
eq— イコールne— ノットイコール
Enum"eq""ne"
レスポンス
application/json
{ "id": 3, "name": { "en": "Offer chain", "ru": "Цепочка", "de": "Angebotskette", "fr": "Chaîne d'offres", "it": "Catena di offerte" }, "description": { "en": "Personalized offer chain with user attribute conditions - for level 10 and above elves who reached level 10 no later than 2026-01-01 00:00:00, inclusive", "ru": "Персонализированная цепочка предложений - для эльфов 10 уровня и выше, достигших 10 уровня не позднее 2026-01-01 00:00:00 включительно", "de": "Personalisierte Angebotskette mit Benutzerattributbedingungen - für Elfen der Stufe 10 und höher, die Stufe 10 spätestens am 2026-01-01 00:00:00 erreicht haben, einschließlich", "fr": "Chaîne d'offres personnalisée avec des conditions d'attribut utilisateur - pour les elfes de niveau 10 et plus qui ont atteint le niveau 10 au plus tard le 2026-01-01 00:00:00, inclus", "it": "Catena di offerte personalizzata con condizioni di attributo utente - per elfi di livello 10 e superiore che hanno raggiunto il livello 10 non più tardi del 2026-01-01 00:00:00, inclusi" }, "date_start": "2023-04-15T18:16:00+05:00", "date_end": "2025-04-25T18:16:00+05:00", "order": 1, "recurrent_schedule": null, "steps": [ { … }, { … }, { … } ], "is_enabled": true, "is_always_visible": false, "attribute_conditions": [ { … }, { … }, { … } ] }
パス
ボディapplication/jsonプロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
例: 44056
アイテム名に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字の言語コード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
Any of:
2文字の小文字の言語コード。
アイテムの説明に関するローカライズ用オブジェクト。2文字の小文字の言語コード（例：en）または5文字のロケールコード（例：en-US）のいずれかの形式で値を受け入れます。どちらの形式も入力として受け入れられますが、応答は2文字の小文字の言語コードを返します。同じ言語に対して両方のオプションが提供された場合（例：enとen-US）、最後に提供された値が保存されます。サポートされている言語の完全なリストは、ドキュメントで確認できます。
Any of:
2文字の小文字の言語コード。
オファーチェーンのステップが無料であるかどうかを示します：
trueの場合、ステップは無料オファーチェーンステップを請求するコールを使用して請求する必要があります。falseの場合、有料オファーチェーンステップの注文を作成するコールを使用して購入する必要があります。
報酬チェーンをすべてのユーザーに表示するかどうかを設定します。trueの場合、ユーザーの認証ステータスや属性に関わらず、チェーンは常に表示されます。
個人用設定を設定するには、falseを渡す必要があります。チェーンの表示ロジックは以下のようになります：
falseが渡され、かつattribute_conditions配列に表示条件が指定されている場合、そのチェーンはパーソナライズされているとみなされ、指定された条件を満たす認証されたユーザーにのみ表示されます。falseが渡され、かつattribute_conditions配列が渡されないか空である場合、チェーンは未認証のユーザーに表示されます。また、認証されたユーザーに対して一致するチェーンが見つからない場合にも表示されます。
Conditions for validating user attributes. Determine chain availability based on whether user attributes match all specified conditions.
One of:
条件によって実行される操作のタイプ。string属性タイプの場合。
可能な値：
eq— イコールne— ノットイコール
Enum"eq""ne"
- https://store.xsolla.com/api/v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}
- Mock serverhttps://xsolla.redocly.app/_mock/ja/api/liveops/v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X PUT \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/offer_chain/id/101 \
-H 'Content-Type: application/json' \
-d '{
"name": {
"en": "Updated offer chain",
"ru": "Обновляемая цепочка предложений",
"de": "Aktualisierte Angebotskette",
"fr": "Chaîne d'\''offres mise à jour",
"it": "Catena di offerte aggiornata"
},
"description": {
"en": "A short description of a regular offer chain",
"ru": "Краткое описание обычной цепочки предложений",
"de": "Eine kurze Beschreibung einer regulären Angebotskette",
"fr": "Une brève description d'\''une chaîne d'\''offres régulière",
"it": "Una breve descrizione di una catena di offerte regolare"
},
"order": 4,
"date_start": "2023-04-15T18:16:00+05:00",
"date_end": null,
"recurrent_schedule": null,
"is_enabled": true,
"steps": [
{
"step_id": 10,
"step_number": 1,
"is_free": false,
"items": [
{
"sku": "chain_step_1_paid_bundle_sku",
"quantity": 2
}
]
},
{
"step_number": 2,
"is_free": true,
"items": [
{
"sku": "chain_step_2_free_virtual_good_sku",
"quantity": 1
}
]
},
{
"step_number": 3,
"is_free": false,
"items": [
{
"sku": "chain_step_3_paid_virtual_currency_package_sku",
"quantity": 5
}
]
},
{
"step_id": 9,
"step_number": 4,
"is_free": true,
"items": [
{
"sku": "chain_step_4_free_bundle_sku",
"quantity": 1
}
]
}
],
"is_always_visible": true
}'リクエスト
特定のオファーチェーンを削除します。
削除後：
- ユーザーがすでに受け取ったすべての報酬は保持されます。
- 未完了のステップは利用不可になり、その報酬は取得できなくなります。
オファーチェーンの有効/無効切り替えるコールによるオファーチェーンの無効化とは異なり、削除は元に戻すことができず、ユーザーの進捗状況は保持されません。
セキュリティ
basicAuth
パス
プロジェクトID。このパラメータは、パブリッシャーアカウントのプロジェクト名の横、またはプロジェクトの作業中にブラウザのアドレスバーで確認できます。URLの形式は以下の通りです：https://publisher.xsolla.com/<merchant_id>/projects/<project_id>。
例: 44056
- https://store.xsolla.com/api/v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}
- Mock serverhttps://xsolla.redocly.app/_mock/ja/api/liveops/v2/project/{project_id}/admin/offer_chain/id/{offer_chain_id}
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X DELETE \
-u <username>:<password> \
https://store.xsolla.com/api/v2/project/44056/admin/offer_chain/id/101概要
Upsell is a sales method in which the user is offered to buy an item with additional value. For example, this could be the item that is in the greatest demand among other users. You can also configure regional restrictions for upsell items. For detailed information, refer to the Upsell section.
The list of items configured for upsell and the upsell status (enabled or disabled) are returned by the Get information about upsell in project API method. On the client side, the list of items is returned by the Get list of upsell items in project API method and displayed to the user at the appropriate point in the purchase flow.
Upsell configuration scenario:
- Create items using the API calls from the Admin subsection of the Virtual items and currency, Bundles, or Game keys groups.
- Set up the upsell using the Create upsell API call. Pass the SKUs of the required items in the
itemsarray. - Activate upsell for the project using the Activate/Deactivate project's upsell API call.
- Display the upsell offer to the user at the appropriate point in the purchase flow using the Get list of upsell items in project API call.
- Implement the opening of the payment UI to pay for the order. For example, you can use the Create order with all items from particular cart API call. The response returns a token to open the payment UI.
- Configure order status tracking, e.g., using webhooks, to promptly receive data about successfully paid items and grant them to the user.
