注文状況追跡のセットアップ
ユーザーにアイテムを付与するには、支払いが成功したことを確認する必要があります。
注文状況を追跡する方法を選択します:
エクソーラデータにアクセスするために、プロジェクトに最も適した方法を選択してください:
サーバーがない場合、またはクライアント側で購入処理のロジックを実装している場合は、次のメソッドを使用できます:
WebSocket APIを使用してクライアント側で注文状況の取得
このソリューションでは、websocketを使用して、注文の詳細情報を取得せずに注文状況を取得します。このメソッドが推奨されます:クライアント(例えば、ウェブサイトやモバイルアプリケーション)とエクソーラサーバー間には1つの接続しか作成されないため、クライアントやサーバーへの追加の負荷は発生しません。
以下の手順を完了してください:
- エクソーラのwebsocketサーバーとクライアントが注文状況メッセージを識別できるようにするために、接続を作成します:
- javascript
const client = new Centrifuge(
connectionURL,
{
data: {
user_external_id: user_external_id,
auth: auth,
project_id: project_id
}
}
)
connectionURL - wss://ws-store.xsolla.com/connection/websocket
auth - user JWT token
- 注文状況に関する新しいメッセージを受信するには、
client.on
関数を使用してイベントを登録します:
- javascript
client.on('publication', (ctx) => {
//handle the status
});
- 実際の接続確立をトリガーします:
- javascript
client.connect()
- 注文状況の変更履歴を受信するには、API履歴メソッドに接続してください。
- javascript
client.on('subscribed', function (ctx) {
client.history(ctx.channel, { limit: -1, since: { offset: 0 }, reverse: false }).then(function (resp) {
resp.publications.forEach((ctx) => {
/handle the status
});
}, function (err) {
//handle the status
});
});
メッセージ本文の例:
- javascript
{
order_id: 59614241,
status: 'new'
}
以下の注文状況があります:
New
— オーダーは作成されたが未払いであるPaid
— 注文は支払われるDone
— 注文が配信されたこと(すべての領収書の送付、エクソーラ側での配信、外部プラットフォームでの配信、など)Canceled
— 注文がキャンセルされ、代金がユーザーに返金される
Websocketの使用に関する推奨事項:
- Websocket経由の応答待ち時間は最大5分です。
- 決済インターフェースを開くときに接続を確立する必要があります。
- 最終的な注文ステータスが
Canceled
またはDone
になったら、接続を中止する必要があります。 - WebSocket の寿命が切れた場合、または接続に問題がある場合は、ショートポーリングを使用します。
ショートポーリング
ステータスを切り替えた後のオーダーのアイテムの詳細情報を取得するには、注文を取得するAPIを呼び出します。
お知らせ定期的な注文状況のポーリングが使用されます。これは、注文状況と注文に関する情報を受信する単純なHTTPリクエストです。リクエスト間の推奨遅延時間は3秒です。
XsollaCatalog.Purchase
メソッドは、注文状況を追跡するためのいくつかのメソッドをカプセル化しています。追跡メカニズムは、Unity(PC、ウェブ)向けのSDKのドキュメンテーションに詳しく記載されています。
さらに、購入メソッドのonSuccess
コールバック関数に渡される注文状況と内容の処理を実装することができます。
CheckPendingOrder
SDKメソッドを使用して注文状況を追跡することができます。メソッドに以下のパラメータを渡します:
AccessToken
— 商品を購入する時に受け取った支払いトークン。OrderId
— 商品を購入する時に受け取った注文ID。SuccessCallback
— 決済成功時のコールバック。ErrorCallback
— リクエストエラー時のコールバック。bIsUserInvolvedToPayment
— ユーザーが支払いプロセスに関与しているかどうか。実際通貨で購入する場合はtrue
を、無料アイテム購入と仮想通貨で購入する場合はfalse
を渡します。
追跡メカニズムは、Unreal Engine向けエンタープライズレベルSDKのドキュメンテーションに詳しく記載されています。
注文状況と内容をリクエストするには、CheckOrder
SDKメソッドを呼び出し、次のパラメータを渡します:
作成された注文のステータスを追跡して検証するには、アプリケーションのサーバー側でウェブフック処理を構成する必要があります。
インゲームストアを完全に操作するには、主要なウェブフックの処理を実装する必要があります:
ウェブフック | 通知タイプ | 説明 |
---|---|---|
ユーザー検証 | user_validation | ユーザーがゲームに登録されていることを確認するため、決済プロセスのさまざまな段階で送信されます。 |
支払い | payment | 注文が支払われたときに送信され、支払いデータおよび取引詳細が含まれます。 |
ご注文の決済が完了した | order_paid | 支払いウェブフックが正常に処理されたときに送信され、購入したアイテムに関する情報とトランザクションIDが含まれています。ウェブフックのデータを使用して、ユーザーにアイテムを追加します。 |
返金 | refund | 注文がキャンセルされたときに送信され、キャンセルされた決済データと取引の詳細が含まれます。 |
注文キャンセル | order_canceled | 返金ウェブフックが正常に処理されたときに送信され、購入したアイテムに関する情報とキャンセルされたトランザクションのIDが含まれています。購入した商品を削除するには、ウェブフックのデータを使用します。 |
ウェブフックの完全なリストと、ウェブフックの操作に関する一般情報については、ウェブフックのドキュメンテーションを参照してください。
ウェブフックの送信を設定する
エクソーラ側でウェブフックを構成するには:
- アドミンページでプロジェクトを開きます。
- サイドメニューで「プロジェクト設定」をクリックし、「ウェブフック」セクションに移動します。
- 「ウェブフックURL」フィールドに、エクソーラがウェブフックを送信するURLを指定します:
- 「ウェブフックを有効にする」をクリックします。
ウェブフックリスナーを追加する
ウェブフックリスナーは、指定されたURLアドレスで受信したウェブフックを受信し、署名を生成し、エクソーラウェブフックサーバーに応答を送信できるようにするプログラムコードです。
署名の生成
ウェブフックを受信する場合、データ伝送のセキュリティを確保する必要があります。そのためには、ウェブフックのデータから署名を生成し、それがHTTPリクエストヘッダで送信された署名と一致することを検証する必要があります。
署名を生成するには:
- リクエスト本文のJSONとプロジェクトの秘密鍵を連結します。
- 最初のステップで取得した文字列にSHA-1暗号化ハッシュ関数を適用します。
ウェブフックへの応答の送信
ウェブフックの受信を確認するには、サーバーが以下のことを返す必要があります:
- 成功した応答の場合は
200
、201
、または204
HTTPコード。 - 指定されたユーザーが見つからなかったり、無効な署名が渡された場合、問題に関する説明が記載された
400
HTTPコードが表示されます。
ウェブフックハンドラーは、サーバーに一時的な問題が発生した場合に5xx
コードを返すこともあります。
「ご注文の決済が完了した」と「注文キャンセル」のウェブフックで応答を受信しなかった場合、または5xx
コードの応答を受信した場合、以下のスケジュールでウェブフックを再送信します:
- 5分間隔で2回再試行
- 15分間隔で7回再試行
- 60分間隔で10回再試行
ウェブフックの送信は、最初の試行から12時間以内に最大20回まで試行されます。
決済ウェブフックの応答が受信されなかった場合、または5xx
コードを含む応答を受け取った場合は、ウェブフックも時間間隔を空けて再送信されます。12時間以内に最大12回の試行が行われます。
ユーザー検証ウェブフックに対する応答が受信されなかった場合、400
または5xx
のコードを含む応答が受信された場合、ユーザー検証ウェブフックは再送信されません。
この場合、ユーザーにはエラーが表示され、「決済」と「ご注文の決済が完了した」のウェブフックは送信されません。
誤字脱字などのテキストエラーを見つけましたか? テキストを選択し、Ctrl+Enterを押します。