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.
There are also two different ways to manage your inventory of purchasable items. The first is to create items manually on our web interface. This is most useful for single-player client-side games, as well as multiplayer games that have only a few items (usually in the form of packages of premium currency) that don't change price often. The other option is to use the dynamic item creation/pricing API, which uses a secure sever-side call to let Kongregate know what the item is and how much it should cost. This is useful for games with large inventories of items that are priced directly in Kreds, or games that may which to change the price of items programmatically and regularly. It also may be easier for games coming from Facebook's purchasing API to use this setup.
Quick Function Reference
purchaseItems- Requests an item for purchase
purchaseItemsRemote- Starts the dynamic purchase flow.
requestItemList- Request item definitions.
requestUserItemList- Requests list of a user's inventory of items
showKredPurchaseDialog- Opens the Kred Purchase lightbox
Setting Up Items
There are two ways to set up virtual goods items in the Kongregate backend:
Dynamic Item Setup
Dynamic item management requires secure, signed server-to-server communications. You can read details about the Dynamic Item Orders API to get that set up and running. This method is often easier for developers porting from Facebook, or if you will be making regular changes to pricing and items.
Manual Item Setup
If you will be selling only a few packs of virtual currency at consistent prices, the manual item method (described on the rest of this page) is often quicker and easier to set up. The item management tools are accessible by adding
/items to the end of your game URL, for example:
/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 have their initial uses field left blank (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
- 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
Item Purchase Flow
When a player wants to purchase an item in your game, it should go through these steps to complete it.
View a flowchart of this process here.
Requesting a Purchase
To begin a transaction, call the
purchaseItemsRemote method on the microtransaction services object to bring up the "purchase items" dialog box. 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.
After a purchase completes, you will get a client-side callback. There is also a server-side callback if you have set up your callback URL whenever the inventory is invalidated (i.e. has been changed by adding a new purchased item).
Prices for items should be listed in Kreds, not dollars, to avoid confusion and ambiguity (since Kreds get slightly cheaper when purchased in bulk). If you would like to put an icon of Kreds in the game, please feel free to use either of these images and scale them as needed or as reference.
Requesting User Item Instances
Note: This is not needed when utilizing the Dynamic Purchase API.
The inventory of any user can be requested by using the
requestUserItemList method on the client side, or the
user_items 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.
Additionally, the server should check for item instances in a player's inventory whenever a game session starts. If they are present, they should be credited and consumed (with the
use_item call described below) at that time. The reason for this is two-fold. First, it helps reduce customer support issues that may occur due to connectivity issues or bugs during a purchase since a player can refresh the game page and get the item properly credited. Additionally, if the game qualifies for promotional efforts from us one such promotion is giving away items to players on Kongregate for achieving goals, and that can only be done if we can put an item in a player's inventory outside of the normal purchase flow.
Using an Item
Note: This is not needed when utilizing the Dynamic Purchase API.
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.
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 call or requestItemList client method 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.
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:
$itemlist = $kompatible->getGameItems();
If we want to get the user's item inventory:
$data = $kompatible->getKredsInventory();
If we want to mark all the items as used:
Or if we want to use a single item on page load: