Kreds & Virtual Goods

Edit - changed Apps@ to BD@

🚧

Approval required

If you are selling in-app purchases you will need to submit your game to [email protected] for QA testing and approval prior to publishing the game. You will be able to test the API before this, it only prevents launching without approval.

❗️

Edge case: already live games

If your game is already live and you now want to add in-app purchases you will need to contact us before you are able to test out the API functionality.

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" (decrement the count of) 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 currently using Facebook's Payments API to use this setup.

Quick Function Reference

Client Functions:

• 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

REST Functions:

• Items - List - Requests a list of all available items
• Items - User - Request a user's inventory
• Items - Consume - Consumes a user's limited-use item

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 Purchasing 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, or the game is client-only, 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:

http://www.kongregate.com/games/YourName/YourGame/items

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 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 the item is consumed.
• Price - The price of the item in Kreds.

📘

Note

The Image attribute for these items is largely deprecated and very optional. It's probably not worth setting them up at this point.

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

📘

Note

If using the JavaScript API via Unity, make sure to read the Unity API documentation about how to handle callbacks to ensure you can receive the results of your purchase and inventory operations.

Item Purchase Flow

When a player wants to purchase an item in your game, it should go through these steps to complete it.

Requesting a Purchase

To begin a transaction, call the purchaseItems or purchaseItemsRemote method on the mtx 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/Consuming 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 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 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 Handling Guests.