The Kartridge In-App Purchasing (IAP) API allows you to sell permanent or consumable items to players from your game. Items can be defined ahead of time in the Kartridge interface or dynamically at purchase time. The API supports both server-side and client-only approaches for purchasing and consuming items. The IAP related API methods all begin with the KongregateIAP prefix.
The Kartridge IAP API is quite similar to Kongregate's Virtual Goods API (the server-to-server interface is virtually identical), so if you have experience with that then you should feel right at home.
- 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
gold-pack-100which can award the player 100 in-game gold upon consumption from either the client or server. - Static item - An item that is set up in the Kartridge interface ahead of time with pre-defined 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. 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.
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 at mailto:games.team@kartridge.com for approval prior to publishing.
Once you have permission, you need to determine whenther you will be using the static or dynamic purchasing functionality. If your game does not have a server component, or you have a relatively small list of items you want to sell that does not change often then static items may be your best bet. If you have a game server and do not want to set up items beforehand in Kartridge then dynamic items may be a better choice.
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.
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.
The Kartridge API provides methods for enumerating both items and item instances. When the API is initialized you will receive KONGREGATE_EVENT_ITEMS and KONGREGATE_EVENT_ITEM_INSTANCES events which mean that the list 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 at iem. An updated list of item instances can also be requested using the KongregateIAP_RequestItemInstances method, although generally that is 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 un-consumed item instances and consume them using KongregateIAP_ConsumeItemInstance when the KONGREGATE_EVENT_ITEM_INSTANCES event is received, although this would not be necessary if using the auto-consume functionality when purchasing.
If you are using static consumable items with a game server, you should check for un-consumed items using the server API when the player starts the game or logs in to ensure no purchases have fallen through the cracks.
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, if any.
For static item purchases, you will pass in the string identifier for the item that you wish to purchase. It 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, you will 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.
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 BenV
These log messages should correspond with your game receiving KONGREGATE_EVENT_ITEMS and KONGREGATE_EVENT_ITEM_INSTANCES events from the API.
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.
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 attempt to purchase an identifier that does not exist it will result in an error, and you will get a callback with a false success flag.
Note - Purchases for developers and collaborators of your game are free to allow for easier testing.
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 games.team@kartridge.com. Once approved, you will be able to publish your game and will not require subsequent approval.