Virtual Goods API

MindJolt’s Virtual Goods API provides game developers with new monetization opportunities while offering personalization and game achievement opportunities for their players. Read our Tips for using Virtual Goods for ideas. Meet us in the community to discuss issues and ask questions.

The API calls defined below are new and an enhancement from our earlier, more basic Virtual Goods API. They aren’t yet generally available (as of April 5, 2011); they will become available in May, 2011, if not sooner. Please base future plans on the details below.

Implementing the Virtual Goods API

First, indicate that the game will use virtual goods by checking the “Use Virtual Good:” box. This is in the “Game-related Settings” of the “Game Info” screen.

Check box to enable virtual goods

In the Developer Dashboard, define the items for sale using the “Edit Game Items” screen (pictured below). Input the following information

  • Name: consumer-facing label to describe the good, ie “Unlock”, “Bomb”, “Shuffle”. Please limit this to 14 characters.
  • ItemId: string to uniquely identify this specific good.
  • Cost: number of MindJolt tokens needed to purchase the item; currently, 2,000 MindJolt tokens sell in a range between 90 cents to 1 dollar (US). We find that most goods sell for between 25 cents to $2.00. Eventually we will enforce a minimum price on items (~5 tokens).
  • Max Per Player: maximum number of this item a player is allowed to own.
  • Description: a concise summary of the value this item provides; these words may be shown when the game player hovers over the item in a shop. Limit this to 120 characters.
  • Image: if the item is a power-up, a 50×50 image is needed; if the items is an upgrade, please use a 90×90 image.
dialogue for Add New Game Item

dialogue for Add New Game Item

Utilize the following functions to implement virtual goods in your game. For most applications with multiple items for sale, MindJolt’s built-in shop will serve you well. The look is consistent with other MindJolt games and will help game players feel comfortable. If they’ve spent money with this interface before (in other games), they are more likely to do it again in your game. Additionally, as the built-in shop is enhanced, your game will benefit without additional coding on your part. (In the near term, some coding parameters of the built-in shop will change, so some flexibility will be required as we finalize the calls.) For games with special needs, or to allow purchase of a single item simply, you may create your own custom-built UI using the purchaseItem() function.

public function getItems()

// ActionScript3:
MindJoltAPI.service.getItems():Object
 
// ActionScript2:
MindJoltAPI.service.getItems():Object

Returns an object which is meant to be used as a dictionary. For each item the user has purchased, there is an entry in the dictionary with a corresponding value that is the number of that item which the user has purchased. So, for example, if you have an item “cheatMode” and the user purchased it once, then MindJoltAPI.service.getItems()["cheatMode"] == 1 will evaluate to true.

Parameters

  • none

Returns

  • Object

Notes

The dictionary returned can only be interrogated for values, it cannot be used to create/update/delete keys and values.

Example

// ActionScript 3
// Performs Virtual Goods-related activity if the user is enabled
if (MindJoltAPI.service.getItems()["cheatMode"] == 1) {
	var playerLivesLeft = -1; //lives score will never decrease to 0, ending the game
	}

public function displayUpgradeShop ()

// ActionScript3:
MindJoltAPI.service.displayUpgradeShop(onClose:Function):void
 
// ActionScript2:
MindJoltAPI.service.displayUpgradeShop(onClose:Function):Void

This is optional, and will display our built-in shop for upgrades. This will execute your onClose function, passing in a list of purchased items in itemId/count pairs. If the list is empty, then nothing was bought.>

Parameters

onClose:Function,

  • Should have the form onClose(purchasedList:Array)
  • i.e., onClose([{itemId:String,purchased:Integer}, {itemId:String, quantityPurchased:Integer},…])
  • itemId corresponds to the item the user purchased (as specified in the developer dashboard), and quantityPurchased corresponds to the quantity of that item purchased
  • Example of onClose
    function onClose(items:Array) {
  if (items != null && items.length > 0) {
    for (var i = 0; i < items.length; i += 1) {
      if (items[i].itemId == "BOMB") {
        enableBombs(items[i].quantityPurchased);
      } else if (items[i].itemId == "EXTRA_LIFE") {
        enableExtraLives(items[i].purchased);
      }
    }
  }
}

Returns

  • void

Notes

This functionality should be used for MindJolt’s built-in shop interface for upgrades. If you wish to custom-build a dialog to the player for purchase of a single specific item, see purchaseItem() below.

Example

// ActionScript 3
// show the upgrade store and have any items purchased passed back to your itemPurchased() function
MindJoltAPI.service.displayUpgradeShop(coolgame_onCloseFunc);

Result

screen shot of Purchase Upgrades

public function displayPowerUpShop()

// ActionScript3:
MindJoltAPI.service.displayPowerUpShop(onClose:Function):void
// ActionScript2:
MindJoltAPI.service.displayPowerUpShop(onClose:Function):Void

This is optional, and will display our built-in shop for power-ups/consumables. This list represents the power-ups used for that game. This will execute your onClose function, passing in a list of purchased items in itemId/count pairs. If the list is empty, then nothing was bought.

Parameters

  • onClose:Function, Should have the form onClose(purchasedList:Array), i.e.
    onClose([{itemId:String,quantityPurchased:Integer}, {itemId:String,purchased:Integer},…])
    itemId corresponds to the item the user purchased (as specified in the developer dashboard), and quantityPurchased corresponds to the quantity of that item purchased.

Returns

  • void

Notes

This functionality should be used for MindJolt’s built-in shop interface for power-ups/consumables. If you wish to custom-build a dialog to the player for purchase of a single specific item, see purchaseItem() elsewhere in the API.

Example

// ActionScript 3
// show the consumable store and have any items purcahsed passed back to your <code>itemPurchased()</code>function
<code>MindJoltAPI.service.displayShop("itemPurchased");</code>

Result

screen shot of Power-Up shop

public function getPowerUpPanel ()

// ActionScript3:
MindJoltAPI.service.getPowerUpPanel(onPowerUpClick:Function,orientation:String):MovieClip //ActionScript2:
MindJoltAPI.service.getPowerUpPanel(onPowerUpClick:Function,orientation:String):MovieClip

This is optional, and will return the side panel to display which power-ups are available in the game. This will execute your onPowerUpClick function, passing in the name of the item used with that click. If the list is empty, then no power-ups are available.

Parameters

  • onPowerUpClick:Function Should have the form onPowerUpClick(itemID:String) , i.e.
    onPowerUpClick(“bomb”)
    itemId corresponds to the item (as specified in the developer dashboard) that was clicked in the power-up panel.
  • orientation “vertical” or ”horizontal” depending on the orientation desired.

Returns

  • flash.display.MovieClip Add the MovieClip instance into a desired location in your game

Notes

This functionality should be used for MindJolt’s built-in display for power-ups/consumables.

Example

// ActionScript 3
// show the consumable panel and register if any power-ups are used
<code>MindJoltAPI.service.getPowerUpPanel(coolgame_onPowerUpClick, “vertical”); PowerUpPanel</code>

Result



public function checkItem()

// ActionScript3:
MindJoltAPI.service.checkItem(itemId:String):Boolean
 
// ActionScript2:
MindJoltAPI.service.checkItem(itemId:String):Boolean

Returns true for a specific itemId if the user has purchased that item, false otherwise. For example, if the user purchased cheatMode, then MindJoltAPI.service.checkItem("cheatMode") will evaluate to true.

Parameters

  • itemId:String the item you would like to check (as specified in the developer dashboard).

Returns

  • boolean

Notes

This function simply returns whether the user has access/purchased to at least one of the given item. To return a specific quantity, see checkItemCount() below.

Example

// ActionScript 3
// to test if the player owns running shoes, and if so make them go faster in the game
if (MindJoltAPI.service.checkItem("runningshoes")) {
	// make player run faster
	}

public function checkItemCount()

// ActionScript3:
MindJoltAPI.service.checkItemCount(itemId:String):Number
 
// ActionScript2:
MindJoltAPI.service.checkItemCount(itemId:String):Number

Used for items that can be purchased multiple times. Returns the quantity purchased of a specific item. So, if the user purchased cheatMode once, then MindJoltAPI.service.checkItemCount("cheatMode") will return 1.

Parameters

  • itemId:String the item you would like to check (as specified in the developer dashboard).

Returns

  • number

Notes

To Boolean test whether a player has access to an item, rather than return a count, see checkItem() above.

Example

// ActionScript 3
// ring a bell sound for each bell item the player owns
var bellsOwned = MindJoltAPI.service.checkItemCount("bell");
ringBellForEachItemOwned(bellsOwned);

public function purchaseItem()

// ActionScript3:
MindJoltAPI.service.purchaseItem(itemId:String,callback:Function=null):void
 
// ActionScript2:
MindJoltAPI.service.purchaseItem(itemId:String,callback:Function=null):Void

Call this method to start the purchase process when using a custom-built shopping interface.. It will popup a dialogue to the user explaining what the item is and how much it costs. It then allows the user to fund their account, if necessary, and purchase the item.

Once the user is finished with this process, your callback function will be executed with the parameters purchased:Boolean and itemId:String. If the user successfully purchased the item, the value of purchased will be true, otherwise it will be false.

itemId is an identifier that uniquely identifies an item in your game. It can be anything. Other developers are using values like "cheatMode" or "MAP_EDITOR".

In addition to integrating the API with your game, you need to tell us what the itemIds for your game are, as well as a description of each item and the relative costs for each one, which you can do through the game manager at developer.mindjolt.com.

Parameters

  • itemId:String the item you would like to present to the player for purchase (as specified in the developer dashboard).
  • callback:Function (optional) Should have the signature callback(purchased:Boolean,itemId:String). purchased is passed TRUE if the user successfully purchases an item. itemId corresponds to the item the user purchased (as specified in the developer dashboard).

Returns

  • void

Notes

This functionality should be used if you wish to present a custom-built dialog to the player for them to purchase a specific item. If you wish to use MindJolt's own shop interface to present a range of items, then use displayShop() above.

Example

// ActionScript 3
// buy the "magicsword" item and purchase confirmation passed back to your itemPurchased() function
MindJoltAPI.service.purchaseItem("magicsword","itemPurchased");

public function isVirtualGoodsEnabled()

// ActionScript3:
MindJoltAPI.service.isVirtualGoodsEnabled():Boolean
 
// ActionScript2:
MindJoltAPI.service.isVirtualGoodsEnabled():Boolean

Checks to see if user’s account is enabled to support virtual goods. Not all accounts are, and it is important that users who do not have this functionality available are not presented with virtual goods-related activity

This is optional. Not all sites that use the MindJolt platform currently support virtual goods. If you would like your game to work on sites that do not support virtual goods, please use the following method to detect whether or not your game should be displaying virtual goods to the current player.

Parameters

  • none

Returns

  • boolean

Notes

You should only include a gameMode if you have more than one in your game. However, this does allow us to track high scores for each game mode independently.

Example

// ActionScript 3
// Performs Virtual Goods-related activity if the user is enabled
if (MindJoltAPI.service.isVirtualGoodsEnabled()) {
	// do some Virtual Goods related activity
	}

Threads in the community related to Virtual Goods: