Currency & Commerce Service の使い方

Mobage オープンプラットフォームではゲーム内でアイテムなどを販売することができます。この機能は Mobage SDK により、Bank API として提供されます。
パートナーデベロッパーはこの API を使ってゲームを実装することにより、アイテムなどの決済サービスを提供できます。 

ゲーム内で販売するアイテムの一覧はパートナーのゲームサーバーに持たせることも、プラットフォームに持たせることもできます。ゲームサーバーに持たせる場合には処理が若干複雑になりますが、データはゲームサーバーで一元管理できます。
一方で、プラットフォームに持たせる場合は、処理が簡素化されますが、プラットフォームにアイテムを登録して管理する手間が発生します。
アイテムの登録にはデベロッパーサイトのアイテム管理からの入力で行います。アイテムの登録の仕方はアイテムをプラットフォームに登録する方法をご確認下さい。

ユーザーがアイテムを購入する際の仮想通貨には、Andoroid の場合はモバコインが利用でき、iOS では各ゲーム独自のゲーム内仮想通貨を利用します。ゲーム内仮想通貨はデベロッパーサイトで通貨名などを登録することができます。

アイテムをトランザクションごとに指定する場合

他のデバイスのAPIとの互換性があります。


 

トランザクションの生成

1. クライアントからゲームサーバーへトランザクション生成の要求をします。
2. ゲームサーバーからAPI サーバーに RESTful API を使ってトランザクション生成の要求を行います。
3. トランザクションがAPI サーバー上で生成されます。
4. API サーバーからゲームサーバーにトランザクション情報を返します。
5. ゲームサーバーからクライアントにトランザクション情報を返します。

RESTful API に関しまして、こちらをご参照下さい。

 

トランザクションの承認

6. SDKのBankDebitクラスのcontinueTransaction() を実行します。※
7. ユーザーにアイテム購入の確認画面が表示されます。
8. ユーザーが購入を許可すると、トランザクションがAPI サーバーで承認されます。
9. コールバックに結果が返ります。

※ 以下、SDKのBankDebitクラスになります。

SDK名

SDKのBankDebitクラス名

Mobage ngCore SDK

Bank.Debit

トランザクションの確定

10. クライアントからゲームサーバーへトランザクション確定の要求をします。
11. ゲームサーバーからAPI サーバーに RESTful API を使ってトランザクションの開始要求を行います。
12. 指定されたトランザクションがAPI サーバー上で開始状態になります。
13. API サーバーからゲームサーバーに結果が返ります。
14. ゲームサーバー上でアイテムの付与などの処理を行います。
15. ゲームサーバーからAPI サーバーに RESTful API を使ってトランザクションの終了要求を行います。
16. 指定されたトランザクションがAPI サーバー上で終了状態になります。
17. API サーバーからゲームサーバーに結果が返ります。
18. ゲームサーバーからAPI サーバーに RESTful API を使ってトランザクションの確認要求を行います。
19. 指定されたトランザクションの状態をAPI サーバー上で確認します。
20. API サーバーからゲームサーバーに結果が返ります。
21. アイテム付与の確定処理を行います。
22. ゲームサーバーからクライアントに結果を返します。
23. クライアントからゲームサーバーへアイテムの付与状態を確認する要求をすることができます。
24. ゲームサーバーからクライアントに結果を返します。
 

15 のトランザクションの終了要求で 500 系エラーの場合は、state が更新されている可能性がありますので、次の『トランザクションの確認』まで行ってからアイテム付与を確定させてください。

アイテムをプラットフォームに登録する場合

スマートフォン(アプリ版)はアイテムをプラットフォームに登録して利用することができます。

トランザクションの生成と承認

1. SDKのBankDebitクラスのcreateTransaction() を実行します。
2. ユーザーにアイテム購入の確認画面が表示されます。
3. ユーザーが購入を許可すると、トランザクションがAPI サーバー上で承認されます。
4. コールバックに結果が返ります。

トランザクションの確定

5. クライアントからゲームサーバーへトランザクション確定の要求をします。
6. ゲームサーバーからAPI サーバーに RESTful API を使ってトランザクションの開始要求を行います。
7. 指定されたトランザクションがAPI サーバー上で開始状態になります。
8. API サーバーからゲームサーバーに結果が返ります。
9. ゲームサーバー上でアイテムの付与などの処理を行います。
10. ゲームサーバーからAPI サーバーに RESTful API を使ってトランザクションの終了要求を行います。
11. 指定されたトランザクションがAPI サーバー上で終了状態になります。
12. API サーバーからゲームサーバーに結果が返ります。
13. ゲームサーバーからAPI サーバーに RESTful API を使ってトランザクションの確認要求を行います。
14. 指定されたトランザクションの状態をAPI サーバー上で確認します。
15. API サーバーからゲームサーバーに結果が返ります。
16. アイテム付与の確定処理を行います。
17. ゲームサーバーからクライアントに結果を返します。
18. クライアントからゲームサーバーへアイテムの付与状態を確認する要求をすることができます。
19. ゲームサーバーからクライアントに結果を返します。

10 のトランザクションの終了要求で 500 系エラーの場合は、state が更新されている可能性がありますので、次の『トランザクションの確認』まで行ってからアイテム付与を確定させてください。

クライアントAPIのみを利用する場合

ゲームサーバーを持たない場合などは、RESTful APIを使用せずにクライアントAPIのみで課金を行うこともできます。

その場合は、プラットフォームにアイテムを登録することが必須となり、トランザクション毎にアイテム情報を指定することはできません。

トランザクションの生成と承認

1. SDKのBankDebitクラスのcreateTransaction() を実行します。
2. ユーザーにアイテム購入の確認画面が表示されます。
3. ユーザーが購入を許可すると、トランザクションがAPI サーバー上で承認されます。
4. コールバックに結果が返ります。

トランザクションの確定

5. SDKのBankDebitクラスのopenTransaction() を実行します。
6. 指定されたトランザクションがAPI サーバー上で開始状態になります。
7. コールバックに結果が返ります。
8. クライアント上でアイテムの付与などの処理を行います。
9. SDKのBankDebitクラスのcloseTransaction() を実行します。
10. 指定されたトランザクションがAPI サーバー上で終了状態になります。
11. コールバックに結果が返ります。
12. SDKのBankDebitクラスのgetTransaction()を使ってトランザクションの確認を行います。
13. 指定されたトランザクションの状態をAPI サーバー上で確認します。
14. コールバックに結果が返りますので、トランザクションの状態確認します。

Mobage Developersにアクセスします。
1. 左のペインより、「Item」をクリックします。
2. アイテムを登録します。アイテム識別名がItemIdになりますのでご注意下さい。

アイテムの登録の仕方はアイテムをプラットフォームに登録する方法をご確認下さい。

アイテム購入時の制限について

  • 一度に購入できるアイテムの数は100個までになります。
  • 一回に決済できる金額の上限は、100000までになります。(モバコイン、およびゲームポイントのいずれも)

サンプルコード

サーバー実装のサンプル

PHP版

  • request_temporary_credential.phpはOAuth 認証の流れの「Temporary Credentials の取得」部分のサンプルです
  • request_token.phpはOAuth 認証の流れの「Access Token Credentials の取得」部分のサンプルです
  • create_transaction.phpは本ページの「トランザクションの生成」部分のサンプルです
  • commit_transaction.phpは本ページの「トランザクションの確定」部分のサンプルです

事前準備

アプリケーションが登録され、ConsumerKeyおよびSecretが共通設定タブにて発行されている必要があります。
iOSのクライアントの場合は、iOSアプリ設定およびゲームポイントの名称と単位が設定されている必要があります。
Androidのクライアントの場合は、Androidアプリ設定がされている必要があります。
クライアント・アプリケーションの初期化を正しく行い、起動時にテストアカウントでログインする必要があります。

  • ngCoreの場合は、登録したアプリケーションの設定をconfiguration.jsonに記載する。
  • Native/Unityの場合は、登録したアプリケーションの設定でinitialize関数をコールする。

制限事項

  • 可読性向上のためエラーハンドリングやトランザクション管理は全く意識していないサンプルになっています。エラー時のデータ一貫性の維持やチート対策はパートナー様の開発基準に併せて修正してください。
  • temporary credentialやtoken credentialを保持するためにサーバー側のセッションを使用しています。サーバーの冗長構成がある場合は、DBやmemcached等を使用する必要があります。

Android / iOS の通貨の違い

Android と iOS で以下の様な通貨の違いがあります。

  • Android の場合
    • Mobage 配信版の場合は、Mobage 共通で使用出来る『モバコイン』を購入して、アプリ内でのアイテム購入などに使用します。『モバコイン』の消費は Bank API を用いて行います。
    • Google Play 配信版の場合は、In-App Billing を使用してアプリ内でアイテム購入などに使える『Android ゲームポイント』を購入します。ゲームポイント名はデベロッパーサイトで登録でき、『ゲームポイント』の消費は Bank API で行うことができます。『ゲームポイント』は各アプリで独立した仮想通貨になりますので、他のアプリから消費することはできません。※ ただし、Android のゲームポイントと iOS のゲームポイントは、OS をまたいで共通で使用できる仮想通貨ではありません。
  • iOS の場合は、Apple の提供する In-App Purchase を使用してアプリ内でアイテム購入などに使える『iOS ゲームポイント』を購入します。ゲームポイント名はデベロッパーサイトで登録でき、『ゲームポイント』の消費は Bank API で行うことができます。『ゲームポイント』は各アプリで独立した仮想通貨になりますので、他のアプリから消費することはできません。※ ただし、Android のゲームポイントと iOS のゲームポイントは、OS をまたいで共通で使用できる仮想通貨ではありません。

それぞれの通貨の現在(2016/03/09 時点)の購入フローに関しては以下の図をご確認下さい。
(バランスボタンの設定は必須ではありません)

Android の場合

iOS の場合

更新履歴 

  • 2016/03/09
    • Android ゲームポイント対応にあわせて記載内容を変更。
  • 2013/06/10
    • アイテムをプラットフォームに登録する方法から Bank Inventory の POST を削除
  • 2012/12/18
    • シーケンス画像を変更
    • 各処理内容の簡略化
  • 2012/08/01
    • 「アイテムをプラットフォームに登録する方法」を追記
    • 「Android / iOS の通貨の違い」を追記
  • 2012/05/01
    • 「アイテム購入時の制限について」を追記
  • 2012/01/17
    • 新規作成

 


PREVIOUS

APIの使い方

NEXT

アイテムをプラットフォームに登録する方法