Microtransaction API

Surveys show that the acceptance of users to spend real money in online games is steadily increasing. With the Platogo Microtransaction API you can easily benefit from this trend and monetize your games more successfully. Sell game upgrades, items and customizations to players and let us take care of all the hassle of handling different payment providers for different countries.

Our currency is Platogo Coins. Currently, our users can buy these coins through PayPal and Buxter – with more payment options to come. Users can then, obviously, use these coins to pay for your must-have items on Platogo.

Game settings

Before you can sell virtual goods in your game, one or more items have to be added to your game. To do so, go to the Edit Game page in your developer dashboard. Under the menu item Virtual Goods you can add new items or edit existing ones. As long as the game has not been published, you can delete items. You can also clear all owned items on the page if the need arises, but this – again – only works during development mode.

Item definition

An item has the following properties:

• name
• coins
• key
• consumable
• description
• image

The name is the title of the virtual good. Choose something appealing!

Every item is worth a certain amount of coins. It's up to you to choose an adequate Platogo Coin value of your item. This is a crucial decision! Think about how much you would be willing to pay for it.

Each item is uniquely identified by its key property. You address the desired item in your code via its key. You can choose the key yourself to make sure it is meaningful and memorable for you. For example, in Picross users can buy the feature "20x20 Puzzles" which enables them to solve bigger puzzles. In this case, we decided upon the key "20x20puzzles".

If you mark the item as consumable, it can only be used once (e.g. a one-time power-up). After it has been consumed, it will be gone. However, a user can own more then one of the same consumable item. Non-consumable items will remain in the user's possession forever, but can only be owned once. A good example for this is our "20x20 Puzzles" feature in Picross.

The description is a short text that should explain what the user can expect to get when he buys an item.

Every item should have an icon to be easily recognizable. So we recommend uploading an image for each of your items.

All these properties can be retrieved at runtime using PlatogoAPI.gameInformation.getItem( itemKey ).

Selling / Buying items

The following code example uses the buyItem() method to offer five (consumable) "powerUp" items for buying. After issuing this method a popup is being shown which summarizes the payment process. The user has then the option to confirm or decline the transaction.

var item : Item = PlatogoAPI.gameInformation.getItem( "powerUp" );
trace( item.quantity ); // 0

PlatogoAPI.microtransactionService.buyItem( "powerUp", 5, buyItemHandler );

function buyItemHandler( response : PlatogoResponse ) : void
{
	switch( response.status )
	{
		case PlatogoStatus.OK:
			trace( "The user was logged in and bought five powerUp items." );
			var item : Item = response.data as Item;
			trace( item.quantity ); // 5
			break;

		case PlatogoStatus.NOT_LOGGED_IN:
			trace( "The user was not logged and the powerUp items have not been bought." );
			break;

		case PlatogoStatus.ERROR:
			switch (response.data)
			{
				case MicrotransactionErrorCode.NOT_ENOUGH_COINS:
					trace( "User rejected to buy additional coins." );
					break;
				case MicrotransactionErrorCode.ITEM_PURCHASE_FAILED:
					trace( "User rejected to buy this item." );
					break;
				case MicrotransactionErrorCode.MULTIPLE_PURCHASE_OF_ITEM_FAILED:
					trace( "You cannot buy not consumable items multiple times." );
					break;
				default:
					trace( "Something went wrong. This should never happen." );
			}
			break;
	}
}

Using / Consuming Items

The following code example uses the useItem() method to consume one of five (consumable) "powerUp" items that are already owned by the currently playing user:

var item : Item = PlatogoAPI.gameInformation.getItem( "powerUp" );
trace( item.quantity ); // 5
var quantity : int = 1;

if ( item.consumable && item.quantity >= quantity )
{
	PlatogoAPI.microtransactionService.useItem( "powerUp", quantity, useItemHandler );
}
else
{
	trace( "Prevent the user to consume more than he is allowed to." );
}

function useItemHandler( response : PlatogoResponse ) : void
{
	switch( response.status )
	{
		case PlatogoStatus.OK:
			trace( "The user was logged in and one powerUp item has been consumed." );
			var item : Item = response.data as Item;
			trace( item.quantity ); // 4
			break;

		case PlatogoStatus.NOT_LOGGED_IN:
			trace( "The user was not logged and the item has not been used." );
			break;

		case PlatogoStatus.ERROR:
			trace( "Something went wrong. This should never happen." );
			break;
	}
}

Shop in the Social Bar

On Platogo and its partner sites the games are embedded using our Platogo Wrapper. The wrapper already has a neat shop built into the Social Bar (just below the game). There, users can browse through all the items available in the game and buy them immeditately. So there isn't a need for you to build a custom shop into the game as it is handeled automatically by our wrapper.

Registering for events of the shop

Users can immediately buy items from within the Social Bar. Sometimes you might not really care when the item is bought as you are just querying if the user has the item at a given moment (using getItem()). If the state of the game should change when the user buys an item, e.g. removing the "Buy this item!!!" message from within the game, it is preferable to listen for events dispatched by the wrapper.

You can do so by invoking PlatogoAPI.registerBuyItemCallback() – the function passed as a parameter is then called every time an user purchases an item using the wrapper. Your function receives the same parameters as the callback method in buyItem(). You can basically use the same code for both.

Things to consider before publishing

Adding, editing and removing items

After you have published your game, existing items can no longer be removed. If you decide to add another item to an already published game, it will be visible immediately and you won't be able to delete it afterwards. However, you can always edit existing items, but you should know what you are doing! For example, if you change the key of an item, you may have to edit your code in order to keep your game working.

This work is licensed under a Creative Commons License.