Kongregate Developers

Virtual Goods

The Microtransaction client API allows you to bring up the standard Kongregate checkout UI, enabling users to purchase virtual items in your game.

Setup

In order to use this API, your game must have special permissions granted by an administrator. This will allow you to access the item management tools by adding /items to the end of your game URL, for example:

http://www.kongregate.com/games/BenV/mygame/items

You should also review the process of implementing the Kongregate APIs in general, as this documentation assumes that you have access to the Kongregate API object.

Once the API is loaded, you can access the microtransaction functions from the mtx object on the API, for example kongregate.mtx.purchaseItems, etc.

Note: This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please email us at apps@kongregate.com and we will review your game.

API Functions

Requesting Item Purchase

You may bring up the "purchase items" dialog box by using the purchaseItems method on the microtransaction services object. It takes either an array of item identifiers or an array of identifier/metadata objects, as well as a callback function which should be called with the result of the purchase, as shown below:

purchaseItems(items:Array, callback:Function):void
  • items:Array - The array of item identifier strings or item/metadata objects.
  • callback:Function - The callback function

The callback will be called with a single Object argument which has one field:

  • success:Boolean - True if the user successfully purchased the items

Example: Purchasing a "sword" and "shield" with no metadata, and then purchasing a "sword" with metadata equal to "+1str"

// Purchase item with no metadata:
kongregate.mtx.purchaseItems(["sword","shield"], onPurchaseResult );

// Purchase item with metadata:
var items:Array=[{identifier:"sword",data:"+1str"}];
kongregate.mtx.purchaseItems(items, onPurchaseResult);

// The purchase callback
function onPurchaseResult(result:Object){
  trace("Purchase success:" + result.success);
}

The second call shows how to attach a string of metadata to the item instance, which you can retrieve from the server later. It is important to note that the client can change this data using a browser plugin fairly easily, so it is a good idea to obfuscate this string, as well as verify its validity as it relates to your game.


Requesting User Item Instances

The inventory of any user can be requested by using the requestUserItemList method. This function takes a username string as the first argument, but you may pass in null or a blank string to request the inventory for the current user. The second argument is a callback function to call when retrieval is complete.

requestUserItemList(username:String,callback:Function):void
  • username:String - The username to request inventory for, or null for the current player.
  • callback:Function - The callback function

The callback will be called with a single Object argument which has two fields:

  • success:Boolean - True if successful
  • data:Array - List of item instance Objects (if successful):
    • id:Number - Database ID of the item instance
    • identifier:String - Item identifier string
    • data:String - Item metadata (attached at checkout time)
    • remaining_uses:Number - Number of uses remaining

Example: Request the inventory for the current player

// Request the inventory for the current player
kongregate.mtx.requestUserItemList(null, onUserItems);

// The callback function
function onUserItems(result:Object):void{
  trace("User item list received, success: " + result.success);
  if( result.success ){
    for( var i:int = 0; i < result.data.length; i++ ){
      var item:Object = result.data[i];
      trace((i+1) + ". " + item.identifier + ", " + item.id + "," + item.data);
    }
  }
}

Displaying the Kred Purchase Dialog

You may bring up the "purchase kreds" dialog box by using the showKredPurchaseDialog method on the microtransaction services object. The only argument is the default purchase method you would like to display, which can be either "offers" to show the OfferPal Kred options, or "mobile" to show the mobile/Zong options. Any other value will simply show the default purchase dialog.

showKredPurchaseDialog(purchaseMethod:String):void
  • purchaseMethod:String - The purchase method to display. Should be "offers" or "mobile"

Example:Display the OfferPal Kred purchase dialog.

// Display a dialog informing users how to earn free Kreds.
kongregate.mtx.showKredPurchaseDialog("offers");

Handling Guest Users

Since guest users on Kongregate are not allowed to purchase items, you must decide how you want to handle them in your game. In general, whenever a guest user wants to purchase an item, it is a good idea to display a message letting them know they must sign in or register before they can purchase, and then display the sign-in lightbox. Further documentation on this process can be found here.

Kompatible

We have a server side library available that implements a few of the server side api methods.

These items can also be available for use at a future date with the server side use_item call. You can query all of a user's items with user_items call.

If we want to mark all the items as used: Or if we want to use a single item on page load:

next

Comments