How to Use the Bank and Economy

Introduction to the Mobage Bank

Mobage serves as a centralized portal for accessing and managing virtual currency and virtual goods. Regardless of the platform, game code uses the same API to access virtual currency. Players' experiences when purchasing and spending virtual currency will vary depending on whether they are using iOS or Android.

Apple: On Apple iOS, a player uses a game specific currency to buy virtual goods. Mobage provides an interface that enables the player to purchase virtual currency through In App Purchasing (IAP) and manages the in-game balance. Players on Mobage iOS also have the ability to purchase virtual goods for actual currency directly.
Android: On Android, Mobage provides a common virtual currency, called MobaCoin, that is available within all games in the Mobage service.

Mobage's Bank functionality is one of several ways Mobage apps generate revenue. This document provides an overview of the Mobage Bank functionality.

App producers may access the Bank tab of the Dev Portal to manage Bank inventory items for an app. For more information, see the App Deployment section of the Resource Center.

Freemium Apps

Mobage apps operate on the "Freemium" concept, which means that Mobage apps are free to download but they provide users with the opportunity to purchase in-app inventory items. Freemium apps accelerate user adoption by making the price elasticity of demand "perfectly inelastic," which means that users do not make a decision about which apps to use based on the price of the app. Rather, users select the apps that appeal to them without regard to price. Also see Free-to-play.

How Mobage Enhances Freemium Apps

Mobage enhances the freemium app concept by adding a social component to Mobage apps. When a group of users like the same app (e.g., they enjoy playing the same games), they can become friends and use the app together. When multiple users interact with each other in an app, the number and duration of user sessions increases. This gives developers more opportunities to monetize their apps. Additionally, as users develop social connections on Mobage, they become aware of apps that their friends are using. This improves the "cross elasticity of demand" for an app by ensuring that two or more apps are complements rather than substitutes.

Purchasing Items in Freemium Apps

Ideally, a freemium app such as a game should be usable without requiring the user to "pay to play." For example, in a basic card game app like "Blackjack," the user is not required to purchase "Casino Chips" in order to enjoy the game experience. However, the app provides the user with the ability to purchase "Casino Chips" to enhance the user experience. In-app purchasing is one way Mobage apps make money.

Background on Virtual Currency

Mobage employs the notion of a 'virtual currency' (e.g., MobaCoin), which the user purchases with real money (e.g., U.S. Dollars, Euros, Japanese Yen, etc.). Virtual currency reduces the need to execute real-world transactions, such as credit card transactions for each in-app item the user chooses to purchase.

Each of your app's deployment contexts determines how a user may purchase and spend virtual currency within that context. Mobage may pre-define some or all of the virtual currency settings for an app's deployment contexts. Where there is no default currency setting for a deployment context, you must provide one (e.g., in iOS, you must specify a currency name). Where there are no currency items for sale, you must define them in the currency catalog.

Mobage App Inventory

'Mobage App Inventory' is any virtual item that a user may purchase within a Mobage app by spending either Mobage platform virtual currency or a context currency to pay for the purchased item.

Mobage App Inventory may be a bundled quantity of an in-app item, such as gold (e.g., 50 gold coins) or casino chips (e.g., a stack of 100 casino chips), which are in turn used to procure other in-app items (e.g., a road section in "We Rule") or engage in in-app activity (e.g., placing a bet with casino chips).

Distinguishing Mobage App Inventory from Local App Inventory

Mobage App Inventory is inventory you create on the Mobage Dev Portal and is available for your app users to purchase with virtual currency. For example, in We Rule on iOS, a player can purchase the 'mojo' virtual currency, and then purchase in-app items such as castles. The Mobage platform will decrement the user's balance of the virtual currency by the price of the purchased in-app item.

Your app may increment in-game value stores that increase as a user gains experience (XP). This does not create virtual currency, but allows you to create the impression of increasing a store of value. (e.g., collecting rent in "We Rule" increases the number of gold coins, but not the amount of 'mojo'; playing with your dog in "Touch Pets Dogs" increases the number of 'coins', but not the amount of a virtual currency such as 'bones.')

Apps may also have their own inventory, which is not managed by the Mobage service. We refer to this as "Local App Inventory," so that it is not confused with Mobage app inventory. You are responsible for managing local app inventory items, and the Mobage platform provides functionality for you to manage Mobage app inventory. For example, when the player uses virtual currency to purchase a Mobage app inventory item that may be spent within the app (e.g., gold coins, casino chips, bones, etc.), the items purchased by the Mobage app inventory item are not managed by the Mobage service. (e.g., local app inventory may be a length of roadway in "We Rule," a ball in "Touch Pets," etc., that is not managed on the Mobage platform.)

At this time, players can only purchase currency inventory items with with real money.

Transaction Lifecycle

The transaction lifecycle begins when a player wishes to purchase in-game items, causing the app to create a transaction. The Mobage platform verifies that the user has enough virtual currency to purchase the requested items.

The next step is to open the transaction. Opening the transaction places the funds into escrow. During this stage, you are responsible for delivering the virtual item to the player. Once your game server has delivered the virtual item, the game can close the transaction, which transfers the funds to your account.

If you do not close the transaction after delivering the purchased items, the funds will not be transferred to your account, and you will not be paid for the transaction.

If your game server cannot deliver the item to the user (for example, due to network error), you may cancel the transaction. Canceling the transaction releases the funds from escrow and returns the funds to the player.

Each Mobage SDK provides methods for managing the transaction lifecycle. You can also use the REST API to manage the transaction lifestyle.

Transaction State Transition

To begin a transaction, the player must add at least one item from the game's inventory to a shopping cart. Once this step is complete, the player can proceed to checkout. During the transaction lifecycle, the typical state transition for transactions is as follows:

1	`new` `=> authorized => open => closed`

With the exception of the closed state, you may cancel the transaction any time after you create it. When you cancel a transaction, the transaction state changes to canceled, and funds are restored back to the user.

Transaction State Transition

Game Client Transaction Flow

In the game client transaction flow, your app processes a transaction by calling methods that are provided by the SDK. The SDK manages communication with the Mobage platform. Your game server may deliver items to the game, but it does not manage the transaction.

A successful transaction in the game client transaction flow is processed as follows:

When the user attempts to purchase a virtual item, the app uses the SDK to create the transaction.
The Mobage platform checks the game's inventory for the item, then sets the transaction's state to new.
The SDK prompts the user to authorize the transaction.
The user authorizes the transaction. The virtual item is added to the transaction, and the transaction's state is set toauthorized.
The SDK notifies the app that the transaction was successfully created.
The app uses the SDK to open the transaction.
The Mobage platform places the user's funds in escrow, then sets the transaction's state to open.
The SDK notifies the app that the transaction was successfully opened.
The virtual item is added to the user's inventory, which is typically managed by a game server.
After the user receives the virtual item, the game client uses the SDK to close the transaction.
The Mobage platform transfers the user's funds to your account, and the transaction's state is set to closed.
The SDK notifies the app that the transaction was successfully closed.

At any point before the transaction is closed, you can cancel the transaction. Canceling a transaction will set its state tocanceled, which prevents it from being processed further. If the user's funds have been placed in escrow for the transaction, the funds are returned to the user when the transaction is canceled.

Game Server Transaction Flow

In the game server transaction flow, your game server uses the Mobage REST API to process part or all of a transaction. The game server manages some or all of the communication with the Mobage platform. See the Mobage REST API Reference for more information about the REST API.

The game server transaction flow can be used in either of the following cases:

The Mobage Developer Portal is used to manage the app's virtual items.
The game server is used to manage the app's virtual items.

Developer Portal Manages Virtual Items

In this transaction flow, you use the Mobage Developer Portal to set up the virtual items for your app. The app is responsible for creating a new transaction, which can contain only virtual items from the Developer Portal. The game server is responsible for opening the transaction, delivering the virtual item, and closing the transaction.

A successful transaction in this flow is processed as follows:

When the user attempts to purchase a virtual item, the app uses the SDK to create the transaction.
The Mobage platform checks the game's inventory for the item, then sets the transaction's state to new.
The SDK prompts the user to authorize the transaction.
The user authorizes the transaction. The virtual item is added to the transaction, and the transaction's state is set toauthorized.
The SDK notifies the app that the transaction was successfully created.
The app notifies the game server that a transaction was authorized.
The game server uses the REST API to open the transaction. The Mobage platform places the user's funds in escrow, then sets the transaction's state to open.
The game server adds the virtual item to the user's inventory.
After the user receives the virtual item, the game server uses the REST API to close the transaction. The Mobage platform transfers the user's funds to your account, and the transaction's state is set to closed.
The game server notifies the app that the transaction was successfully closed.

At any point before the transaction is closed, the app or the game server can cancel the transaction. Canceling a transaction will set its state to canceled, which prevents it from being processed further. If the user's funds have been placed in escrow for the transaction, the funds are returned to the user when the transaction is canceled.

Because this transaction flow uses the REST API, the OAuth authentication process must be completed before the game server sends a request to the Mobage platform. See the Authentication section of the Mobage Resource Center for more information.

Game Server Manages Virtual Items

In this transaction flow, you are not required to set up your virtual items in advance. Instead, you can specify information for each virtual item when you create a new transaction. The game server is responsible for managing the list of virtual items that are available. In addition, the game server is responsible for creating a new transaction, opening the transaction, delivering the virtual item, and closing the transaction.

Immediately after the game server creates a transaction, the game server must temporarily return control to the app. The app then uses the Mobage SDK to allow the user to authorize the transaction. This step ensures that the user has personally authorized the purchase.

A successful transaction in this flow is processed as follows:

When the user attempts to purchase a virtual item, the app asks the game server to create the transaction.
The game server uses the REST API to create the transaction, including detailed information about the virtual item in the request. The Mobage platform sets the transaction's state to new.
The game server notifies the app that the transaction was successfully created.
The app asks the SDK to continue the transaction.
The SDK verifies that the transaction exists and has its state set to new, then prompts the user to authorize the transaction.
The user authorizes the transaction.
The SDK sets the transaction's state to authorized.
The SDK notifies the app that the transaction was successfully continued.
The app notifies the game server that a transaction was authorized.
The game server uses the REST API to open the transaction. The Mobage platform places the user's funds in escrow, then sets the transaction's state to open.
The game server adds the virtual item to the user's inventory.
After the user receives the virtual item, the game server uses the REST API to close the transaction. The Mobage platform transfers the user's funds to your account, and the transaction's state is set to closed.
The game server notifies the app that the transaction was successfully closed.

At any point before the transaction is closed, the game server can cancel the transaction. Canceling a transaction will set its state to canceled, which prevents it from being processed further. If the user's funds have been placed in escrow for the transaction, the funds are returned to the user when the transaction is canceled.

Because this transaction flow uses the REST API, the OAuth authentication process must be completed before the game server sends a request to the Mobage platform. See the Authentication section of the Mobage Resource Center for more information.