Kartridge In-App Purchasing

The Kartridge In-App Purchasing (IAP) API allows you to sell permanent or consumable items to players for use in your game. The API supports both server-side and client-only approaches for purchasing and consuming items.

Please note: Prior to integrating your game with the Kartridge SDK and IAP systems, please submit your game to [e-mail] for evaluation.

IAP-related API methods all begin with the following prefix: KongregateIAP

Note: The Kartridge IAP API is very similar to Kongregate's Virtual Goods API. Uploaders familiar with the Kongregate.com APIs should feel right at home in Kartridge!

Terminology

• Item - A developer-defined item that can be purchased/owned by a player. Items have names, descriptions, prices, and identifiers. The item identifier is a string that is used to reference the item for purchases, etc.
• Item instance - An instance of an item that is owned by a player. Each player has their own "inventory" of item instances that can be enumerated/managed via the API.
• Consumable item - A single-use item that can be consumed and will no longer belong to the player afterward. Commonly used for in-game currency packs or temporary power-ups. For example, you might have a consumable item named gold-pack-100 which can award the player 100 in-game gold upon consumption.
• Static item - An item that is set up in the Kartridge interface ahead of time with predefined names, prices, identifiers, etc. Static items can be imported/exported via CSV files, which can make bulk updates easier.
• Dynamic item - An item that is defined at purchase time via our Dynamic Purchasing API. This allows you to manage items entirely on your game server and allow per-player discounts among other things. Dynamic items require that your game has a server that can communicate with the Kongregate back-end.

Note: Dynamic items are always consumable, and are automatically consumed when the order is confirmed, so they will never show up in a player's inventory -- it is the responsibility of your game server to ensure the player is granted the appropriate items on your back-end during the purchase flow.

Setup

In order to start selling items in your game, you must first obtain the required permission via the Kartridge application. You can accomplish this by editing your game in the Kartridge publishing flow and selecting the toggle for "Enable In-App Purchasing API". This will grant you permission to use the API, but you will need to reach out to our games team via [e-mail] for approval prior to publishing.

Once you have permission, you need to determine whether you will be using the static or dynamic purchasing functionality. If you have a game server and would prefer not to set up items beforehand in Kartridge then dynamic items may be a better choice.

Static Items

For games that do not have a server component or use a relatively small and constant list of items, static items may be the best option. If you are using static items, you can manage them by clicking the "manage" button for your game in the "In-App Purchases" section of the publishing flow inside Kartridge. This will allow you to create and edit item definitions for your game.

Dynamic Items

Dynamic item setups are best used in games that rely heavily on a server or by developers who would prefer to not set up items before their game is published in Kartridge.

If you are using the dynamic purchasing API or if you want to use our server-to-server API callback mechanism to notify your server of inventory invalidations, then you can set up your API callback URL by clicking "manage" in the "In-App Purchases" section for your game in Kartridge.

Enumerating Items and Item Instances

The Kartridge API provides methods for enumerating both items and item instances:

As the API is initialized, you should receive the following events:  

• KONGREGATE_EVENT_ITEMS 
• KONGREGATE_EVENT_ITEM_INSTANCES 

These events indicate that the lists of items and instances are available.

The KONGREGATE_EVENT_ITEM_INSTANCES event will be fired again in the event that the user or their inventory changes due to purchasing/consuming an item. An updated list of item instances can also be requested using the KongregateIAP_RequestItemInstances method. This is generally only needed for specific hybrid client/server applications.

Once the items/instances are received you can enumerate them using the KongregateIAP_GetItem* family of methods. Depending on the language you are using these will either return an array or you may need to pass an index in and manually loop through. Your game can behave differently (unlocking certain functionality, for example) based on what item instances are in the user's inventory.

If you are consuming items on the client due to not having a server component, it is generally a best practice to loop through all unconsumed item instances and consume them using KongregateIAP_ConsumeItemInstance when the KONGREGATE_EVENT_ITEM_INSTANCES event is received. This would not be necessary if using the auto-consume functionality when purchasing.

If you are using static consumable items with a game server, check for unconsumed items using the server API when the player starts the game or logs in to ensure no purchases have fallen through the cracks.

Purchasing Items

Purchases are always initiated via an API call from your game client (KongregateIAP_PurchaseItem or KongregateIAP_PurchaseDynamicItem) which will transfer focus over to Kartridge and display a dialog that guides the player through the rest of the process. Your game client will receive a callback via the API informing you of success or failure along with information about the item instance that was purchased.

For static item purchases, pass in the string identifier for the item that you wish to purchase. This must match the identifier that you set up exactly for the item to be found. If the item is consumable you may optionally set the auto-consume flag to true when making the method call to have the item consumed for you on purchase.

For dynamic purchases, pass in an order info string. This can be anything you like, and it will be forwarded to your game server as described in the Dynamic Purchasing API documentation. Your server can then determine what item the order info string represents for the given user and generate the appropriate response to finish the purchase flow.

Testing

Once you have implemented the In-App Purchasing API, you can test a local build from the Kartridge publishing flow in the "Test Your Game" section. Once your game has launched and the API has been initialized, you should see messages similar to the following in the test log output:

retrieve game items for game ID 294286
retrieve inventory for [username]

These log messages should correspond with your game receiving KONGREGATE_EVENT_ITEMS and KONGREGATE_EVENT_ITEM_INSTANCES events from the API.

Testing Purchases

A successful purchase of a potion will look similar to the following:

handling item checkout for potion
item checkout for user ID 765 game ID 294286 successful

Which will result in your callback method being called with a true success flag and the item instance that was purchased.

If you then attempt to purchase an item with identifier potion and close the dialog before completing the flow, you will see messages like the following:

handling item checkout for potion
item checkout failed!

This should correspond to your callback method being called with false for the success flag.

If you attempt to purchase an identifier that does not exist it will result in an error, and you will get a callback with a falsesuccess flag.

Note - Purchases for developers and power users assigned to your game are free to allow for easier testing.

Publishing

Before you initially publish your game with IAP functionality, our team needs to review and do a QA pass on it to ensure everything is functioning properly. You can request this by sending an email to [e-mail]. Once approved, you will be able to publish your game and will not require subsequent approval.