Kongregate Developers

Kreds (Virtual Goods) API

The Kreds API allows users to purchase virtual items in your game using Kongregate's kreds currency. The API includes both client and server-side components. The client API initiates purchases and can also check the user's inventory, which is useful for single-player game unlocks like map packs and advanced features. For games that have consumable items and currency sales, the server-side API enables the game to "use" an item in the player's Kongregate inventory.

Setup

The item management tools are accessible by adding /items to the end of your game URL, for example:

On the /items page you will be able to add and modify the items that you will be selling in your game. "Items" is a generic term used on our end and can really apply to map packs, premium currency bundles, in-game upgrades, etc. Items have the following attributes:

• Identifier - This is an internal identifier that your game will reference the item with.
• Name - The name of the item, which will be displayed to the player when making a purchase.
• Description - A description for the item that will also be displayed to the player.
• Initial Uses - The number of times an item can be used. Perpetual unlocks should be set to 0 (unlimited). One time use items, like premium currency, should be set to 1. If you have multi-use items, they will track remaining uses and decrement each time you call the use_item function.
• Price - This is the price, in kreds, of the item.

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

Requesting a Purchase

You may bring up the "purchase items" dialog box by using the purchaseItems method on the microtransaction services object. The dialog box will handle the transaction, including helping the user buy more kreds if needed. While the dialog box will return a success/fail to the game, these results should always be verified with a separate (server-side if possible) API call.

Requesting User Item Instances

The inventory of any user can be requested by using the requestUserItemList method on the client side, or the /user_items.json method on the server side. Checking the existence of an item in the user's inventory can be used client-side to track game unlocks. On the server side, this method should always be used to confirm that a purchase was fully successful prior to giving credit for the purchase to the user.

Using an Item

If you have a consumable item, or anything that is intended to only be credited once, you will need to "use" the item to make sure the status of the item is tracked on our servers. You can use an item with the /use_item.json server-side call. Using an item decrements its "remaining uses" count on the Kongregate servers. If it is decremented to 0 it will be removed. Items that have a starting number of uses set to 0 (unlimited) cannot be used in this manner.

Testing purchases

The game's developer account (that is, the one you used to create/upload the game) can make free test purchases in that game. All purchases will cost 0 kreds, but will go through the full process and be functional for testing. If you need additional test accounts, let us know the Kongregate usernames and we can give them access and some kreds to test with.

Requesting a List of Available Items

If you are programmatically generating purchase lists within your game it may be useful to get a list of items available for purchase from Kongregate. The /items.json call will allow you to get this list, as well as tags associated with the items so you can filter out the irrelevant ones.

Displaying a "Free Kreds" Dialog

Some games have "earn" or "free" buttons to help players without access to a credit card make purchases in the game. You can bring up the purchase dialog and focus it on either mobile payments or offers to help your players find a payment method that may work better for them. You can do this using the showKredPurchaseDialog method. The only argument is the default purchase method you would like to display, which can be either "offers" to show the free/offer kred options, or "mobile" to show the SMS options. Any other value will simply show the default purchase dialog.

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 in Guest Handling.

Kompatible

If you're using the Kompatible library, these are the transaction functions that are built in to it.

If we want to get a list of items available for sale:

kompatible:
$itemlist = $kompatible->getGameItems();

If we want to get the user's item inventory:

kompatible:
$data = $kompatible->getKredsInventory();

If we want to mark all the items as used:

kompatible:
$kompatible->updateInventory();

Or if we want to use a single item on page load:

kompatible:
$kompatible->useKredItem($itemData);

next next