アイテム付与
処理の概要
コインの引き落としがおこなわれた後、次に行われるのが アイテム付与 です。
アイテム付与 では、以下の実装を行います。
- Game Server にてコイン引き落としの結果を検証をする
- Game Server にてユーザーにアイテムを付与する
- Game Server にて Order DB の Order データを更新する
- Client にて localStorage の Transaction データを削除する
これらの処理のシーケンス図が下記になります。
Game Server にてコイン引き落としの結果を検証をする
Platform にてモバコインによる決済が成功した場合、Client の Callback 関数に result オブジェクトが渡されます。
前述した実装により、Client はその result オブジェクトの result.signedResponse を Game Server に送信しましたが、Game Server にて result.signedResponse が妥当であるかを確認するため、検証する処理を実装します。
Clientからのリクエストである result.signedResponse はJSON Web Token(JWT)というフォーマットです。このJWTは署名アルゴリズムが RS256 となっています。ここではJWTの検証として以下のライブラリを利用します。
https://github.com/firebase/php-jwt
ClientからのリクエストはPlatform側の秘密鍵で署名が付けられているため、X.509 形式の公開鍵を利用して署名の妥当性を検証します。
署名の検証で利用する公開鍵
なお、JWT である result.signedResponse の payload(JWT Claims Set)は下記のようなデータ構造をしています。
Game Server で検証する項目は以下になります。
- iss (Issuer Claim, この JWT を発行したサーバの識別子)が妥当か
- aud (Audience Claim, この JWT の公開範囲として指定された Client ID)がアプリケーションのClient IDと一致しているか
- iat (Issued At Claim)が現在時刻よりも過去の日時を表すUNIXタイムスタンプ値となっているか
- sub (Subject Claim)がログインユーザの所持する Mobage ユーザー IDと一致するか
なお、iss 値は sandbox/service で以下のように異なる値となっています。
環境 |
issの値 |
|---|---|
sandbox |
https://sb-widget.mobage.jp |
service |
https://widget.mobage.jp |
Game Server にてユーザーにアイテムを付与する
「アイテムの付与」を実施する上で忘れずに対応したいのが、「アイテムの付与状態」を確認して「アイテム付与される」まで、他のプロセスによって邪魔されない（アイテムを付与されない）ことを担保することです。
ここでは、処理が始まってアイテム付与が終わるまで他のプロセスによって邪魔されないように、Order データを排他制御する手法を採用します。
排他制御を取り入れることで、同じようなタイミングで複数プロセスからリクエストがあった際に、アイテムの間違った重複付与を防ぐことができます。
また、他プロセスに直前に Order データを更新されていることも考慮して、排他制御で取得した最新の Order データの確認も行います。
すでにアイテムが付与されている場合は、order_state が closed になっています。この場合、エラーで処理を中止します。
最新のアイテム付与状態を確認し、まだアイテム付与していない場合、アイテム付与が終わるまで他のプロセスに寄って邪魔されないように Order データを排他制御します。
このチュートリアルではMySQLのストレージエンジンInnoDBを利用して、行レベルでの排他制御を行い、最新の Order データを確認します。
排他制御により最新の Order データを取得して確認した結果、まだユーザーにアイテムが付与されていない場合にアイテムを付与します。
ここでは、以下のようなテーブルでユーザーが保持するアイテムを管理します。
 | 上記に定義したアイテム管理テーブルは、あくまでこのチュートリアル用のサンプルであり、一例です。実際にゲームに実装する際には、ゲームの要件に従ったテーブルを定義してください。 |
またここでは、以下のようにユーザのアイテムを管理するテーブルにレコードを追加/更新することでアイテムを付与します。
Game Server にて Order DB の Order データを更新する
ユーザーへのアイテム付与が完了したら、Order データを更新し、Order データの排他制御を開放します。
このチュートリアルではMySQLのストレージエンジンInnoDBを利用して、行レベルでの排他制御を行っていましたが、排他制御していたトランザクションをcommitすることで排他制御を開放します。
Clientからのリクエストに対して、以下の場合に 成功レスポンス を返します。
- ユーザーへのアイテム付与が成功した場合
また、以下の場合には 失敗レスポンス を返します。
- 既にアイテムを付与していた場合
- Clientからのリクエストに異常があった場合
- Game Server 側の内部処理で異常があった場合
Clientへの成功レスポンス
ユーザへのアイテム付与が完了した場合、成功レスポンスを返します。
成功レスポンスのhttp status code は 200 OK とします。
Clientへの失敗レスポンス
ゲームサーバの処理で異常があった場合、失敗レスポンスを返します。
失敗レスポンスのhttp status code は 4xxもしくは5xxなどの適切なレスポンスを返します。
TOC
Client にて localStorage の Transaction データを削除する
Callback関数を利用して Game Server からのレスポンスを受け取ります。
Game Server からのレスポンスは、アイテム付与処理が行われた場合に http status 200 OK となるように実装しました。
Clientが http status 200 OK を受け取った場合、Callback関数にて、必ず mobage.bank.clearPaymentBacklog() を呼び出します。
mobage.bank.clearPaymentBacklog() を呼び出すことで、 localStorage 内にある Transaction データが削除されます。
 | 後に説明するClient 側での非同期確認処理に対応した場合、localStorage 内に Transaction データが残っていると、Client から Game Server に確認リクエストが送信され続けます。この確認リクエストが送信されないように、アイテム付与が成功した場合には、mobage.bank.clearPaymentBacklog() を呼び出して、 localStorage 内にある Transaction データを削除します。 |
アイテム付与に失敗した時には、失敗した旨をユーザに伝えつつ、後に紹介する非同期確認処理によりフォローしましょう。
開発したコード
このチュートリアルで開発したコードは Github から clone できます。
利用したライブラリは下記になります。