アイテム付与

 

処理の概要

コインの引き落としがおこなわれた後、次に行われるのが アイテム付与 です。
 
アイテム付与 では、以下の実装を行います。

  1. Game Server にてコイン引き落としの結果を検証をする
  2. Game Server にてユーザーにアイテムを付与する
  3. Game Server にて Order DB の Order データを更新する
  4. 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 形式の公開鍵を利用して署名の妥当性を検証します。
署名の検証で利用する公開鍵

mobage-jssdk-sample-payment/purchase_with_item_setting/fulfill_order.php

なお、JWT である result.signedResponse の payload(JWT Claims Set)は下記のようなデータ構造をしています。

 
Platform にてモバコインによる決済が成功した場合、Client の Callback 関数に result オブジェクトが渡されました。
Client はその result オブジェクトの result.signedResponse を Game Server に送信しましたが、JWT である result.signedResponse が妥当であるかを確認するため、JWT 中の本文である 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
     
    TOC
     

    Game Server にてユーザーにアイテムを付与する

    「アイテムの付与」を実施する上で忘れずに対応したいのが、「アイテムの付与状態」を確認して「アイテム付与される」まで、他のプロセスによって邪魔されない(アイテムを付与されない)ことを担保することです。
    ここでは、処理が始まってアイテム付与が終わるまで他のプロセスによって邪魔されないように、Order データを排他制御する手法を採用します。
    排他制御を取り入れることで、同じようなタイミングで複数プロセスからリクエストがあった際に、アイテムの間違った重複付与を防ぐことができます。
    また、他プロセスに直前に Order データを更新されていることも考慮して、排他制御で取得した最新の Order データの確認も行います。
    すでにアイテムが付与されている場合は、order_state が closed になっています。この場合、エラーで処理を中止します。

 
最新のアイテム付与状態を確認し、まだアイテム付与していない場合、アイテム付与が終わるまで他のプロセスに寄って邪魔されないように Order データを排他制御します。
このチュートリアルではMySQLのストレージエンジンInnoDBを利用して、行レベルでの排他制御を行い、最新の Order データを確認します。

mobage-jssdk-sample-payment/purchase/fulfill_order.php

 
排他制御により最新の Order データを取得して確認した結果、まだユーザーにアイテムが付与されていない場合にアイテムを付与します。
ここでは、以下のようなテーブルでユーザーが保持するアイテムを管理します。

上記に定義したアイテム管理テーブルは、あくまでこのチュートリアル用のサンプルであり、一例です。実際にゲームに実装する際には、ゲームの要件に従ったテーブルを定義してください。

 
またここでは、以下のようにユーザのアイテムを管理するテーブルにレコードを追加/更新することでアイテムを付与します。

mobage-jssdk-sample-payment/purchase/fulfill_order.php

 
TOC
 

Game Server にて Order DB の Order データを更新する

 
ユーザーへのアイテム付与が完了したら、Order データを更新し、Order データの排他制御を開放します。
このチュートリアルではMySQLのストレージエンジンInnoDBを利用して、行レベルでの排他制御を行っていましたが、排他制御していたトランザクションをcommitすることで排他制御を開放します。

mobage-jssdk-sample-payment/purchase/fulfill_order.php

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 データを削除します。
mobage-jssdk-sample-payment/purchase/purchase.js

アイテム付与に失敗した時には、失敗した旨をユーザに伝えつつ、後に紹介する非同期確認処理によりフォローしましょう。

開発したコード

このチュートリアルで開発したコードは Github から clone できます。

利用したライブラリは下記になります。

PREVIOUS

コインの引き落とし(トランザクションのクローズ)

NEXT

動作確認と開発したコード