Kartridge Unity/.NET API Documentation
Kongregate.KartridgeBindings Class Reference

This class includes low-level methods for utilizing the native Kartridge C API. More...

Classes

class  Item
 This structure holds information about an in-game item. More...
 
class  ItemInstance
 This structure holds information about an item instance in the user's inventory. More...
 

Public Member Functions

delegate void EventDelegate (string eventName, string eventPayload)
 Delegate type used for handling Kongregate API events. More...
 
delegate void KongregateEventListener (string eventName, string eventPayload)
 
delegate void ItemInstanceDelegate (bool success, ItemInstance instance)
 Delegate used to handle the result from item-instance related asynchronous calls. More...
 

Static Public Member Functions

static bool KongregateAPI_RestartWithKartridgeIfNeeded (uint gameId)
 Checks to see if the game was launched from Kartridge, and requests Kartridge launch the game if not. More...
 
static bool KongregateAPI_Initialize (string settingsJson)
 Initialize the Kongregate API. More...
 
static void KongregateAPI_Shutdown ()
 Shuts down the Kongregate API after it has been initialized. More...
 
static void KongregateAPI_Update ()
 Updates the internal state of the Kongregate API. More...
 
static bool KongregateAPI_IsReady ()
 
static bool KongregateAPI_IsConnected ()
 
static void KongregateAPI_SetEventCallback (EventDelegate listener)
 Sets the event callback delegate to listen for API events. More...
 
static void KongregateAPI_SetEventListener (KongregateEventListener listener)
 
static string KongregateServices_GetUsername ()
 
static uint KongregateServices_GetUserId ()
 
static string KongregateServices_GetGameAuthToken ()
 
static void KongregateStats_Submit (string statisticName, long value)
 Submit a statistic with the given name and value. More...
 
static bool KongregateLibrary_IsGameOwned (uint gameId)
 Checks if the current user owns the game/DLC with the given game ID. More...
 
static bool KongregateLibrary_IsGameInstalled (uint gameId)
 Checks if the given game ID or additional DLC with additional files is installed on the system. More...
 
static Item [] KongregateIAP_GetItems ()
 Returns a list of KartridgeBindings.Item objects representing items defined for the game. More...
 
static ItemInstance [] KongregateIAP_GetItemInstances ()
 Returns a list of KartridgeBindings.ItemInstance objects representing items owned by the current user. More...
 
static bool KongregateIAP_ConsumeItemInstance (ulong instanceId, ItemInstanceDelegate callback)
 Attempts to consume the item instance with the given ID and call the callback when the operation is complete. More...
 
static bool KongregateIAP_PurchaseItem (string identifier, bool consume, ItemInstanceDelegate callback)
 Initiates the purchase flow for the predefined item with the given identifier. More...
 
static bool KongregateIAP_PurchaseDynamicItem (string orderInfo, ItemInstanceDelegate callback)
 Initiates the dynamic purchase flow with the given order info string. More...
 
static void KongregateIAP_RequestItemInstances ()
 Requests a fresh list of item instances from the server. More...
 

Detailed Description

This class includes low-level methods for utilizing the native Kartridge C API.

Member Function Documentation

§ EventDelegate()

delegate void Kongregate.KartridgeBindings.EventDelegate ( string  eventName,
string  eventPayload 
)

Delegate type used for handling Kongregate API events.

This delegate will be called from KartridgeBindings.KongregateAPI_Update when events are processed.

Parameters
eventNameThe name of the event
eventPayloadA string containing a JSON object with event parameters

§ ItemInstanceDelegate()

delegate void Kongregate.KartridgeBindings.ItemInstanceDelegate ( bool  success,
ItemInstance  instance 
)

Delegate used to handle the result from item-instance related asynchronous calls.

Parameters
successA flag indicating whether or not the asynchronous operation completed successfully
instanceThe item instance that was being consumed, purchased, etc.
See also
KartridgeBindings.KongregateIAP_ConsumeItemInstance
KartridgeBindings.KongregateIAP_PurchaseItem

§ KongregateAPI_Initialize()

static bool Kongregate.KartridgeBindings.KongregateAPI_Initialize ( string  settingsJson)
static

Initialize the Kongregate API.

You must call this before most other API methods. If this method returns false, it can be because the game was not launched via Kartridge or because Kartridge is not installed, and all further API calls will be stubbed out.

This method will use the game ID passed in from Kartridge, or the one present in the kong_gameid.txt file in the working directory the game was launched from if present. The kong_gameid.txt file should only be used for testing, and you should not ship it with your game.

Once the API is initialized, calls to KongregateAPI_Update will start triggering the various API events.

Parameters
settingsJsonAn optional string representation of a JSON object containing API settings. Can be null to use all defaults.
Returns
true if the API was successfully initialized, which means your game ID was successfully detected. If this method returns false, it means the game was not launched from Kartridge or the kong_gameid.txt file is not present.
See also
KongregateAPI_RestartWithKartridgeIfNeeded

§ KongregateAPI_IsConnected()

static bool Kongregate.KartridgeBindings.KongregateAPI_IsConnected ( )
static
Returns
true if the API is connected to the Kongregate application. You can use this method to determine if the Kartridge application is running or not.

§ KongregateAPI_IsReady()

static bool Kongregate.KartridgeBindings.KongregateAPI_IsReady ( )
static
Returns
true if the API has been fully initialized and has successfully communicated with the Kartridge application for the first time. Will always return true after KartridgeConstants.KONGREGATE_EVENT_READY has been fired.
See also
KartridgeConstants.KONGREGATE_EVENT_READY

§ KongregateAPI_RestartWithKartridgeIfNeeded()

static bool Kongregate.KartridgeBindings.KongregateAPI_RestartWithKartridgeIfNeeded ( uint  gameId)
static

Checks to see if the game was launched from Kartridge, and requests Kartridge launch the game if not.

If you have a kong_gameid.txt file present with your game ID in it, this will always return false. The kong_gameid.txt should not be packaged with your release build. If this method returns true, you should exit your game as soon as possible, and not initialize the API, as that means that the Kartridge application will attempt to launch a duplicate copy of your game.

This method is optional but suggested if your game depends on Kartridge API functionality. You should call it immediately before KongregateAPI_Initialize.

The kong_gameid.txt should go into the root folder of your Unity project in order to have it work properly within the editor.

Parameters
gameIdThe Kongregate game ID for your game
Returns
true if the game will be re-launched via Kartridge, or false if not.
See also
KongregateAPI_Initialize

§ KongregateAPI_SetEventCallback()

static void Kongregate.KartridgeBindings.KongregateAPI_SetEventCallback ( EventDelegate  listener)
inlinestatic

Sets the event callback delegate to listen for API events.

Parameters
listenerThe EventDelegate delegate that will be called when an event notification is fired.

It is very important that your delegate catches all exceptions thrown, and does not propagate them to the unmanaged caller, as it is not equipped to handle them. For more information, see the Mono documentation

The events will be fired during calls to KongregateAPI_Update after KongregateAPI_Initialize is called.

§ KongregateAPI_SetEventListener()

static void Kongregate.KartridgeBindings.KongregateAPI_SetEventListener ( KongregateEventListener  listener)
inlinestatic

§ KongregateAPI_Shutdown()

static void Kongregate.KartridgeBindings.KongregateAPI_Shutdown ( )
static

Shuts down the Kongregate API after it has been initialized.

After this method is called, you must call KongregateAPI_Initialize again for the API to function.

§ KongregateAPI_Update()

static void Kongregate.KartridgeBindings.KongregateAPI_Update ( )
static

Updates the internal state of the Kongregate API.

Must be called periodically to maintain a connection to the Kongregate application and process events. Typically you would call this every frame or once every few frames.

This call can mutate the state of the API (username, user ID, etc), and it is not thread safe. You should always call all API functions from the same thread, or use an external synchronization mechanism.

§ KongregateEventListener()

delegate void Kongregate.KartridgeBindings.KongregateEventListener ( string  eventName,
string  eventPayload 
)

§ KongregateIAP_ConsumeItemInstance()

static bool Kongregate.KartridgeBindings.KongregateIAP_ConsumeItemInstance ( ulong  instanceId,
ItemInstanceDelegate  callback 
)
inlinestatic

Attempts to consume the item instance with the given ID and call the callback when the operation is complete.

If the operation is successful the item will be removed from the user's inventory and a KartridgeConstants.KONGREGATE_EVENT_ITEM_INSTANCES event will be generated.

Parameters
instanceIdThe ID of the item instance that you wish to use
callbackThe callback method which will be called when the operation is completed or has failed.
Returns
True if the parameters are valid, or false if not. If false, your callback will NOT be called.
See also
KartridgeConstants.KONGREGATE_EVENT_ITEM_INSTANCES
ItemInstanceCallback
ItemInstance
KongregateIAP_PurchaseItem
KongregateIAP_GetItemInstances

§ KongregateIAP_GetItemInstances()

static ItemInstance [] Kongregate.KartridgeBindings.KongregateIAP_GetItemInstances ( )
inlinestatic

Returns a list of KartridgeBindings.ItemInstance objects representing items owned by the current user.

This should be used after KartridgeConstants.KONGREGATE_EVENT_ITEM_INSTANCES is fired. The KartridgeConstants.KONGREGATE_EVENT_ITEM_INSTANCES event will be fired when the user is changed or their inventory changes.

Returns
The list of items in the current user's inventory
See also
KartridgeConstants.KONGREGATE_EVENT_ITEM_INSTANCES
KartridgeBindings.ItemInstance
KongregateIAP_ConsumeItemInstance
KongregateIAP_PurchaseItem

§ KongregateIAP_GetItems()

static Item [] Kongregate.KartridgeBindings.KongregateIAP_GetItems ( )
inlinestatic

Returns a list of KartridgeBindings.Item objects representing items defined for the game.

This should be used after KartridgeConstants.KONGREGATE_EVENT_ITEMS is fired.

Returns
The list of items defined for the game
See also
KartridgeConstants.KONGREGATE_EVENT_ITEMS

§ KongregateIAP_PurchaseDynamicItem()

static bool Kongregate.KartridgeBindings.KongregateIAP_PurchaseDynamicItem ( string  orderInfo,
ItemInstanceDelegate  callback 
)
inlinestatic

Initiates the dynamic purchase flow with the given order info string.

The order_info string will be passed to the back-end server you specify in the API callback URL field. For more information, see the documentation for the dynamic purchase API: https://docs.kongregate.com/docs/api-dynamic-purchasing

This will attempt to switch focus to the Kartridge app, which may not work properly if your game is not in the foreground. In general, if the user has to click or otherwise interact with your game in order to trigger this function then the focus switch should work fine.

Parameters
orderInfoThe order_info string that will be passed to your server for processing.
callbackThe callback method which will be called when the operation is completed or has failed
Returns
True if the parameters are valid, or false if not. If false, your callback will NOT be called.
See also
ItemInstanceCallback

§ KongregateIAP_PurchaseItem()

static bool Kongregate.KartridgeBindings.KongregateIAP_PurchaseItem ( string  identifier,
bool  consume,
ItemInstanceDelegate  callback 
)
inlinestatic

Initiates the purchase flow for the predefined item with the given identifier.

This will attempt to switch focus to the Kartridge app, which may not work properly if your game is not in the foreground. In general, if the user has to click or otherwise interact with your game in order to trigger this function then the focus switch should work fine.

Parameters
identifierThe identifier that you set up for the item that you wish to be purchased (case sensitive)
consumeIf this flag is set and the item is consumable, it will be automatically consumed. This should be used if you are not planning on using/consuming the item instance manually via your game server (or if your game does not have a server). This flag has no effect for non-consumable items
callbackThe callback method which will be called when the operation is completed or has failed.
Returns
True if the parameters are valid, or false if not. If false, your callback will NOT be called.
See also
ItemInstanceCallback
ItemInstance
KongregateIAP_GetItemInstances
KongregateIAP_ConsumeItemInstance

§ KongregateIAP_RequestItemInstances()

static void Kongregate.KartridgeBindings.KongregateIAP_RequestItemInstances ( )
static

Requests a fresh list of item instances from the server.

The KartridgeConstants.KONGREGATE_EVENT_ITEM_INSTANCES event will be fired when the list is received. This method does not typically need to be used, but can be useful in hybrid client/server applications.

See also
KartridgeConstants.KONGREGATE_EVENT_ITEM_INSTANCES
KongregateIAP_GetItemInstance

§ KongregateLibrary_IsGameInstalled()

static bool Kongregate.KartridgeBindings.KongregateLibrary_IsGameInstalled ( uint  gameId)
static

Checks if the given game ID or additional DLC with additional files is installed on the system.

This can return true even if the current user does not own the given game, as it could belong to a different user. This means that typically for DLC with additional files you will want to use this combined with KongregateLibrary_IsGameOwned for a full ownership/installation check. The KartridgeConstants.KONGREGATE_EVENT_LIBRARY event will be fired when the list of owned/installed games is first available or when it is modified. This will always return false if KartridgeConstants.KONGREGATE_EVENT_LIBRARY has not yet been fired or for DLC that does not have additional files since there is nothing to install in that case.

Parameters
gameIdThe game ID to check
Returns
true if the given game ID is installed on the system, false if not. Always returns false for DLC that does not have additional files.
See also
KongregateLibrary_IsGameOwned
KartridgeConstants.KONGREGATE_EVENT_LIBRARY

§ KongregateLibrary_IsGameOwned()

static bool Kongregate.KartridgeBindings.KongregateLibrary_IsGameOwned ( uint  gameId)
static

Checks if the current user owns the game/DLC with the given game ID.

If the game ID given is not published by the developer of the current game ID, this will return false. The KartridgeConstants.KONGREGATE_EVENT_LIBRARY event will be fired when the list of owned/installed games is first available or when it is modified. This method will always return false if KartridgeConstants.KONGREGATE_EVENT_LIBRARY has not been fired yet.

Parameters
gameIdThe game ID to check
Returns
true if the current user owns the given game
See also
KartridgeBindings.KongregateLibrary_IsGameInstalled
KartridgeConstants.KONGREGATE_EVENT_LIBRARY

§ KongregateServices_GetGameAuthToken()

static string Kongregate.KartridgeBindings.KongregateServices_GetGameAuthToken ( )
inlinestatic
Returns
the game authorization token for the active user for your game. Use the Kongregate REST API from your server to validate the user.

Will return an empty string if the user is a guest or the key has not been fetched yet.

See also
KartridgeConstants.KONGREGATE_EVENT_AUTH_TOKEN

§ KongregateServices_GetUserId()

static uint Kongregate.KartridgeBindings.KongregateServices_GetUserId ( )
static
Returns
the user ID for the active user. Result is not valid until KartridgeConstants.KONGREGATE_EVENT_USER has been fired. Will return 0 for guest users.
See also
KartridgeConstants.KONGREGATE_EVENT_USER

§ KongregateServices_GetUsername()

static string Kongregate.KartridgeBindings.KongregateServices_GetUsername ( )
inlinestatic
Returns
the username for the active user within Kartridge. Result is not valid until KartridgeConstants.KONGREGATE_EVENT_USER has been fired. Will return an empty string if the user information has not yet been fetched, and "Guest" for guest users.
See also
KartridgeConstants.KONGREGATE_EVENT_USER

§ KongregateStats_Submit()

static void Kongregate.KartridgeBindings.KongregateStats_Submit ( string  statisticName,
long  value 
)
static

Submit a statistic with the given name and value.

Parameters
statisticNameThe name (not ID) that you chose for the statistic (must match exactly)
valueThe value to submit