サードパーティストアでアイテムの取り消しを管理する
注釈:本資料はAI技術を用いて翻訳されています。
概要
AccelByte Gaming Services(AGS)の取り消しサービスは、サードパーティストアと統合し、サービスのロジックを使用してプレイヤーのインベントリからアイテムを同期および取り消すことができます。統合の一環として、ストアの注文データを AGS の取り消しエンドポイントにマッピングするミドルウェアとして機能するサーバーをセットアップする必要があります。
統合されたサードパーティストアを通じてプレイヤーにアイテムを付与する方法については、サードパーティストアでアイテムのフルフィルメントを管理するも参照してください。
この記事では、サードパーティストアでアイテムの取り消しを管理する方法について説明します。
前提条件
- ユーザー認証:ユーザー認証を実装し、プレイヤーの有効なユーザー ID があることを確認してください。
- API エンドポイントのアクセストークン:フルフィルメントおよび取り消しエンドポイントにアクセスするために必要なアクセストークンと権限があることを確認してください。
- ミドルウェアのセットアップ:サードパーティストアの注文データを AGS API リクエスト形式にマッピングおよび変換するためのミドルウェアサーバーをセットアップします。
- アイテムの設定:付与するアイテムを AGS で設定し、サードパーティストアで販売されているアイテムと一致することを確認します。
- インベントリ統合:予期しないエンタイトルメント更新を防ぐため、Inventory サービスと Commerce サービスの統合が有効になっていないことを確認してください。
- 取り消し設定:仮想通貨およびその他の消費可能アイテムの取り消しの処理など、特定の取り消しシナリオをどのように処理するかに基づいて、取り消しルールを設定します。
サポートされているアイテムタイプ
サードパーティの取り消し方法は、次のアイテムタイプをサポートしています。
- 永続および消費可能なゲーム内アイテム
- バンドル
- コイン
- メディア
- オプションボックス
- ルートボックス
- 非アクティブなアイテムも取り消せます。アイテムの状態だけで取り消しの可否が決まるわけではありません。アイテムが存在しない場合や、エンタイトルメントが消費済みの場合は、取り消しが失敗することがあります。
- ルートボックスまたはオプションボックスが開封されている場合、そのエンタイトルメントは消費済みのため、取り消しは失敗します。
SUBSCRIPTION、SEASON、EXTENSIONの付与は、トランザクションによる取り消しに対応していません。これらは付与されたままとなり、失敗したアイテムの一覧に表示されます。再試行しても、未対応のアイテムタイプを取り消せるようにはなりません。
仮想通貨およびその他の消費可能アイテムの取り消しの処理
仮想通貨およびその他の消費可能アイテムの取り消しは複雑で、プレイヤーによる悪用の可能性があります。次のように取り消し戦略を設定することをお勧めします。
-
仮想通貨:取り消されるアイテムが仮想通貨またはその他の消費可能アイテムである場合は、マイナスのウォレット残高を許可するように取り消し戦略を変更することを検討してください。これは、仮想通貨がプレイヤーによってすでに使用されている場合に特に重要です。たとえば、プレイヤーがすべての通貨を使用した後に取り消しが実行された場合、ゲームの経済の整合性を維持するために、残高がマイナスになる必要がある場合があります。
-
その他の消費可能アイテム:消費可能なゲーム内アイテムがすでに使用または消費されている場合、取り消しは困難になる可能性があります。不整合や潜在的な不正を回避するために、取り消し戦略にそのようなシナリオを処理するための明確なルールが含まれていることを確認してください。
取り消し戦略を管理するには、取り消しルールを設定するを参照してください。
API エンドポイント
このエンドポイントに対応した環境では、トランザクションの取り消しに V3 を使用してください。サーバートークンには、ADMIN:NAMESPACE:{namespace}:USER:{userId}:FULFILLMENT 権限と UPDATE(2)アクションが必要です。従来の統合を変更する前に、既存のトランザクションを検証してください。
フルフィルメントの取り消し V3
PUT /v3/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId}/revoke は、保存済みトランザクションに関連する付与を取り消し、その状態を記録します。環境のベース URL を使用して呼び出す場合は、このパスの先頭に /platform を付けてください。リクエストボディは不要です。
元のフルフィルメントのトランザクション ID を使用してください。この操作は、実際に適用されたバンドル構成アイテムの数量を含め、保存済みの付与情報を使用します。エンタイトルメント ID を指定して個別のエンタイトルメントを取り消す操作とは異なります。
レスポンスの処理
- HTTP 200 は取り消しの成功を保証しません。
stateを確認してください。REVOKEDは完了を示し、REVOKE_FAILEDは 1 つ以上の構成アイテムを取り消せなかったことを示します。 - 原因を確認するには、
stateInfo.failedList[].errorと、その中のstateInfo.failedList[].items[].errorを確認してください。取り消し可能な他のアイテムの処理は、独立して成功する場合があります。 - 復旧可能な問題を修正したら、元のトランザクション ID を使って同じ取り消しリクエストを再送してください。取り消しの再試行には、フルフィルメントの再試行エンドポイントを使用しないでください。
- 未対応のアイテムタイプについては、適切な業務上の復旧手順を用意してください。無期限に再試行したり、アイテムが削除されたとみなしたりしないでください。
サンプルレスポンス
以下は、サブスクリプションをこのエンドポイントで取り消せないため、取り消しに失敗したトランザクションのレスポンスの抜粋です。
{
"namespace": "your-namespace",
"userId": "22222222222242228222222222222222",
"transactionId": "store-order-123",
"state": "REVOKE_FAILED",
"stateInfo": {
"successList": [],
"failedList": [
{
"itemId": "11111111111141118111111111111111",
"error": "Cannot revoke SUBSCRIPTION item"
}
]
}
}
上記のエラー文は、失敗を説明するための例です。実際の環境から返されたエラーフィールドを確認してください。