Kartridge C API Documentation
kongregate.h File Reference

The C interface for the Kartridge library. More...

Data Structures

struct  KongItem
 This structure holds information about an in-game item. More...
 
struct  KongItemInstance
 This structure holds information about an item instance in the user's inventory. More...
 

Typedefs

typedef struct KongItem KongItem
 This structure holds information about an in-game item. More...
 
typedef struct KongItemInstance KongItemInstance
 This structure holds information about an item instance in the user's inventory. More...
 
typedef uint32_t KONG_ASYNC_CALLBACK_ID
 Integer type that represents a kongregate asynchronous callback ID. More...
 
typedef void(* kongregate_event_listener) (const char *const event_name, const char *const event_payload)
 This callback type has been deprecated in favor of kong_event_cb. More...
 
typedef void(* kong_event_cb) (void *context, const char *const event_name, const char *const event_payload)
 Function pointer type used for handling Kongregate API events. More...
 
typedef void(* kong_item_instance_cb) (void *context, KONG_ASYNC_CALLBACK_ID callback_id, bool success, const KongItemInstance &instance)
 Function pointer type used for returning the result of asynchronous item instance related calls. More...
 

Functions

bool KongregateAPI_RestartWithKartridgeIfNeeded (uint32_t game_id)
 Checks to see if the game was launched from Kartridge, and requests Kartridge launch the game if not. More...
 
bool KongregateAPI_Initialize (const char *settings_json)
 Initialize the Kongregate API. More...
 
void KongregateAPI_Shutdown ()
 Shuts down the Kongregate API after it has been initialized. More...
 
void KongregateAPI_Update ()
 Updates the internal state of the Kongregate API. More...
 
bool KongregateAPI_IsConnected ()
 
bool KongregateAPI_IsReady ()
 
KONG_DEPRECATED void KongregateAPI_SetEventListener (kongregate_event_listener listener)
 This method is deprecated, use KongregateAPI_SetEventCallback instead. More...
 
void KongregateAPI_SetEventCallback (kong_event_cb callback, void *context)
 Sets the event callback function pointer to listen for API events. More...
 
const char * KongregateServices_GetUsername ()
 
uint32_t KongregateServices_GetUserId ()
 
const char * KongregateServices_GetGameAuthToken ()
 
void KongregateStats_Submit (const char *statistic_name, int64_t value)
 Submit a statistic with the given name and value. More...
 
bool KongregateLibrary_IsGameOwned (uint32_t game_id)
 Checks if the current user owns the game/DLC with the given game ID. More...
 
bool KongregateLibrary_IsGameInstalled (uint32_t game_id)
 Checks if the given game ID or additional DLC with additional files is installed on the system. More...
 
KongItem KongregateIAP_GetItem (uint32_t index)
 Returns the KongItem at the given index. More...
 
KongItemInstance KongregateIAP_GetItemInstance (uint32_t index)
 Returns the KongItemInstance at the given index. More...
 
KONG_ASYNC_CALLBACK_ID KongregateIAP_ConsumeItemInstance (uint64_t id, kong_item_instance_cb callback, void *context)
 Attempts to consume the item instance with the given ID and call the callback when the operation is complete. More...
 
KONG_ASYNC_CALLBACK_ID KongregateIAP_PurchaseItem (const char *identifier, bool consume, kong_item_instance_cb callback, void *context)
 Initiates the purchase flow for the predefined item with the given identifier. More...
 
KONG_ASYNC_CALLBACK_ID KongregateIAP_PurchaseDynamicItem (const char *order_info, kong_item_instance_cb callback, void *context)
 Initiates the dynamic purchase flow with the given order info string. More...
 
void KongregateIAP_RequestItemInstances ()
 Requests a fresh list of item instances from the server. More...
 

Variables

const char *const KONGREGATE_EVENT_READY
 Event broadcast when the API has been fully initialized and it has successfully communicated with the Kartridge application for the first time. More...
 
const char *const KONGREGATE_EVENT_USER
 Event broadcast once user information is available. More...
 
const char *const KONGREGATE_EVENT_AUTH_TOKEN
 Event broadcast when the Kongregate authentication token is received or changed. More...
 
const char *const KONGREGATE_EVENT_LIBRARY
 Event broadcast when the list of currently owned or installed games has been received or updated. More...
 
const char *const KONGREGATE_EVENT_ITEMS
 Event broadcast when the list of items for the game is available, this will be fired after the API is initialized. More...
 
const char *const KONGREGATE_EVENT_ITEM_INSTANCES
 Event broadcast when the list of item instances owned by the user changes. More...
 
const char *const KONGREGATE_EVENT_CONNECTED
 Event broadcast when the API has connected to the Kartridge application process. More...
 
const char *const KONGREGATE_EVENT_DISCONNECTED
 Event broadcast when the API has disconnected from the Kartridge application process. More...
 
const char *const KONGREGATE_EVENT_SHUTDOWN
 Event broadcast when the API is shutting down. More...
 
const char *const KONGREGATE_EMPTY_EVENT_PAYLOAD
 An empty JSON event payload. More...
 
const char *const KONGREGATE_EMPTY_STRING
 An empty NULL-terminated string. More...
 
const char *const KONGREGATE_GUEST_USERNAME
 Username representing a guest user - "Guest". More...
 

Detailed Description

The C interface for the Kartridge library.

This file includes methods for interacting with the Kartridge application. All methods use the cdecl calling convention and are not thread safe.

Boolean values are one byte, and need to be marshaled accordingly when wrapped using a different language or framework.

String types are null-terminated character arrays encoded as UTF-8. Strings returned from API methods are valid only until the next call to KongregateAPI_Update.

Variables that are passed in as callback parameters are only valid during that function call, so you will need to make a copy if you need to retain them.

Typedef Documentation

§ KONG_ASYNC_CALLBACK_ID

typedef uint32_t KONG_ASYNC_CALLBACK_ID

Integer type that represents a kongregate asynchronous callback ID.

§ kong_event_cb

typedef void( * kong_event_cb) (void *context, const char *const event_name, const char *const event_payload)

Function pointer type used for handling Kongregate API events.

The callback should use the cdecl calling convention. This callback will be called from KongregateAPI_Update when events are processed. The string arguments are only valid until the callback function exits. You can pass an optional context pointer into methods that accept this type of callback and it will be passed along when the callback is called, so be sure to not free/delete the pointer before then or you may cause your application to crash.

Parameters
contextThe optional context data that was passed in when the event callback was set
event_nameThe name of the event as a NULL-terminated string
event_payloadA NULL-terminated string containing a JSON object with event parameters
See also
KongregateAPI_Update
KongregateAPI_SetEventCallback

§ kong_item_instance_cb

typedef void(* kong_item_instance_cb) (void *context, KONG_ASYNC_CALLBACK_ID callback_id, bool success, const KongItemInstance &instance)

Function pointer type used for returning the result of asynchronous item instance related calls.

The callback should use the cdecl calling convention. This callback will be called from KongregateAPI_Update when events are processed. API methods will use this callback type to notify you when an asynchronous operation has completed. You can pass an optional context pointer into methods that accept this type of callback and it will be passed along when the callback is called, so be sure to not free/delete the pointer before then or you may cause your application to crash.

Parameters
contextThe optional context data that was passed in when the asynchronous method was originally called
idThe asynchronous request ID returned from the method that started the asynchronous request
successA flag indicating whether or not the asynchronous operation completed successfully
instanceThe item instance that was being consumed, purchased, etc.
See also
KongregateAPI_Update
KongregateIAP_ConsumeItemInstance
KongregateIAP_PurchaseItem

§ KongItem

typedef struct KongItem KongItem

This structure holds information about an in-game item.

§ KongItemInstance

This structure holds information about an item instance in the user's inventory.

§ kongregate_event_listener

typedef void( * kongregate_event_listener) (const char *const event_name, const char *const event_payload)

This callback type has been deprecated in favor of kong_event_cb.

Deprecated:
Use kong_event_cb instead
Parameters
event_nameThe name of the event as a NULL-terminated string
event_payloadA NULL-terminated string containing a JSON object with event parameters
See also
KongregateAPI_Update
KongregateAPI_SetEventCallback

Function Documentation

§ KongregateAPI_Initialize()

bool KongregateAPI_Initialize ( const char *  settings_json)

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
settings_jsonAn 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()

bool KongregateAPI_IsConnected ( )
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()

bool KongregateAPI_IsReady ( )
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 KONGREGATE_EVENT_READY has been fired.
See also
KONGREGATE_EVENT_READY

§ KongregateAPI_RestartWithKartridgeIfNeeded()

bool KongregateAPI_RestartWithKartridgeIfNeeded ( uint32_t  game_id)

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.

Parameters
game_idThe 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()

void KongregateAPI_SetEventCallback ( kong_event_cb  callback,
void *  context 
)

Sets the event callback function pointer to listen for API events.

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

Parameters
callbackThe function that will be called when an event notification is fired
contextOptional data to pass along to the callback when it is called
See also
kong_event_cb
KongregateAPI_Update

§ KongregateAPI_SetEventListener()

KONG_DEPRECATED void KongregateAPI_SetEventListener ( kongregate_event_listener  listener)

This method is deprecated, use KongregateAPI_SetEventCallback instead.

Deprecated:
Use KongregateAPI_SetEventCallback instead.
Parameters
listenerThe function that will be called when an event notification is fired
See also
KongregateAPI_SetEventCallback

§ KongregateAPI_Shutdown()

void KongregateAPI_Shutdown ( )

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()

void KongregateAPI_Update ( )

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.

Additionally, strings returned from the various API functions are only guaranteed to be valid until the next call to KongregateAPI_Update, which means you should make a copy of the string if you need it for a longer amount of time.

§ KongregateIAP_ConsumeItemInstance()

KONG_ASYNC_CALLBACK_ID KongregateIAP_ConsumeItemInstance ( uint64_t  id,
kong_item_instance_cb  callback,
void *  context 
)

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 KONGREGATE_EVENT_ITEM_INSTANCES event will be generated.

Parameters
idThe ID of the item instance that you wish to consume
callbackThe callback method which will be called when the operation is completed or has failed.
contextOptional data to pass along to the callback when it is called
Returns
The asynchronous request ID that will be passed into the provided callback method. Will return 0 to indicate invalid parameters or state, in which case your callback will NOT be called
See also
kong_item_instance_cb
KongItemInstance
KongregateIAP_GetItemInstance
KongregateIAP_PurchaseItem

§ KongregateIAP_GetItem()

KongItem KongregateIAP_GetItem ( uint32_t  index)

Returns the KongItem at the given index.

This should be used after KONGREGATE_EVENT_ITEMS is fired. You should start at index 0, and keep iterating until you receive an item with a zero id property, which means you have reached the end of the list.

Parameters
indexThe index of the item to retrieve (0 based)
See also
KONGREGATE_EVENT_ITEMS

§ KongregateIAP_GetItemInstance()

KongItemInstance KongregateIAP_GetItemInstance ( uint32_t  index)

Returns the KongItemInstance at the given index.

This should be used after KONGREGATE_EVENT_ITEM_INSTANCES is fired. You should start at index 0, and keep iterating until you receive an item with a zero id property, which means you have reached the end of the list. The KONGREGATE_EVENT_ITEM_INSTANCES event will be fired when the user is changed or their inventory changes.

Parameters
indexThe index of the item to retrieve (0 based)
See also
KONGREGATE_EVENT_ITEM_INSTANCES
KongItemInstance
KongregateIAP_ConsumeItemInstance
KongregateIAP_PurchaseItem

§ KongregateIAP_PurchaseDynamicItem()

KONG_ASYNC_CALLBACK_ID KongregateIAP_PurchaseDynamicItem ( const char *  order_info,
kong_item_instance_cb  callback,
void *  context 
)

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
order_infoThe 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
contextOptional data to pass along to the callback when it is called
Returns
The asynchronous request ID that will be passed into the provided callback method. Will return 0 to indicate invalid parameters or state, in which case your callback will NOT be called
See also
kong_item_instance_cb

§ KongregateIAP_PurchaseItem()

KONG_ASYNC_CALLBACK_ID KongregateIAP_PurchaseItem ( const char *  identifier,
bool  consume,
kong_item_instance_cb  callback,
void *  context 
)

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

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

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
contextOptional data to pass along to the callback when it is called
Returns
The asynchronous request ID that will be passed into the provided callback method. Will return 0 to indicate invalid parameters or state, in which case your callback will NOT be called
See also
kong_item_instance_cb
KongItemInstance
KongregateIAP_GetItemInstance
KongregateIAP_ConsumeItemInstance

§ KongregateIAP_RequestItemInstances()

void KongregateIAP_RequestItemInstances ( )

Requests a fresh list of item instances from the server.

The 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
KONGREGATE_EVENT_ITEM_INSTANCES
KongregateIAP_GetItemInstance

§ KongregateLibrary_IsGameInstalled()

bool KongregateLibrary_IsGameInstalled ( uint32_t  game_id)

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 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 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
game_idThe 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
KONGREGATE_EVENT_LIBRARY

§ KongregateLibrary_IsGameOwned()

bool KongregateLibrary_IsGameOwned ( uint32_t  game_id)

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 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 KONGREGATE_EVENT_LIBRARY has not been fired yet.

Parameters
game_idThe game ID to check
Returns
true if the current user owns the given game
See also
KongregateLibrary_IsGameInstalled
KONGREGATE_EVENT_LIBRARY

§ KongregateServices_GetGameAuthToken()

const char* KongregateServices_GetGameAuthToken ( )
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.

As with all strings returned from the API, this pointer can be deallocated after the next call to KongregateAPI_Update, so it is important to make a copy if you need it.

See also
KONGREGATE_EVENT_AUTH_TOKEN

§ KongregateServices_GetUserId()

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

§ KongregateServices_GetUsername()

const char* KongregateServices_GetUsername ( )
Returns
the username for the active user within Kartridge. Result is not valid until 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
KONGREGATE_EVENT_USER

§ KongregateStats_Submit()

void KongregateStats_Submit ( const char *  statistic_name,
int64_t  value 
)

Submit a statistic with the given name and value.

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

Variable Documentation

§ KONGREGATE_EMPTY_EVENT_PAYLOAD

const char* const KONGREGATE_EMPTY_EVENT_PAYLOAD

An empty JSON event payload.

§ KONGREGATE_EMPTY_STRING

const char* const KONGREGATE_EMPTY_STRING

An empty NULL-terminated string.

§ KONGREGATE_EVENT_AUTH_TOKEN

const char* const KONGREGATE_EVENT_AUTH_TOKEN

Event broadcast when the Kongregate authentication token is received or changed.

If your game uses the token, it should authenticate with your server when this event is fired. This event can be fired if either the user or token changes. It will follow the KONGREGATE_EVENT_USER event if the user has changed as well. In general, if your application needs to use auth tokens, you can just listen for this event and ignore KONGREGATE_EVENT_USER.

See also
KongregateServices_GetGameAuthToken
KONGREGATE_EVENT_USER

§ KONGREGATE_EVENT_CONNECTED

const char* const KONGREGATE_EVENT_CONNECTED

Event broadcast when the API has connected to the Kartridge application process.

This event is for advanced usage and can typically be ignored.

See also
KONGREGATE_EVENT_DISCONNECTED

§ KONGREGATE_EVENT_DISCONNECTED

const char* const KONGREGATE_EVENT_DISCONNECTED

Event broadcast when the API has disconnected from the Kartridge application process.

This event is for advanced usage and can typically be ignored.

See also
KONGREGATE_EVENT_CONNECTED

§ KONGREGATE_EVENT_ITEM_INSTANCES

const char* const KONGREGATE_EVENT_ITEM_INSTANCES

Event broadcast when the list of item instances owned by the user changes.

This will happen when the API is initialized, when the current user purchases or consumes an item, or when the user changes. This event will be always be fired after KONGREGATE_EVENT_USER. When this event is fired it is good practice to enumerate the items and consume any unconsumed items since it is possible that items may have been awarded outside of the game via badges, customer services tools, etc. This event will not be fired if the game has not enabled the IAP API in the publishing settings.

See also
KongregateIAP_GetItemInstance
KongregateIAP_ConsumeItemInstance
KongregateIAP_PurchaseItem
KONGREGATE_EVENT_USER

§ KONGREGATE_EVENT_ITEMS

const char* const KONGREGATE_EVENT_ITEMS

Event broadcast when the list of items for the game is available, this will be fired after the API is initialized.

Once this event is fired you may call KongregateIAP_GetItem to enumerate the items defined for the current game. This event will not be fired if the game has not enabled the IAP API in the publishing settings.

See also
KongregateIAP_GetItem

§ KONGREGATE_EVENT_LIBRARY

const char* const KONGREGATE_EVENT_LIBRARY

Event broadcast when the list of currently owned or installed games has been received or updated.

This will happen when the API is initialized, when the current user purchases a game, or when the user changes. This event will be always be fired after KONGREGATE_EVENT_USER.

See also
KongregateLibrary_IsGameOwned
KongregateLibrary_IsGameInstalled
KONGREGATE_EVENT_USER

§ KONGREGATE_EVENT_READY

const char* const KONGREGATE_EVENT_READY

Event broadcast when the API has been fully initialized and it has successfully communicated with the Kartridge application for the first time.

After this event is fired, KongregateAPI_IsReady will return true.

Generally, you will want to wait for KONGREGATE_EVENT_USER or KONGREGATE_EVENT_AUTH_TOKEN if you need information about the current user.

See also
KongregateAPI_IsReady
KONGREGATE_EVENT_USER
KONGREGATE_EVENT_AUTH_TOKEN

§ KONGREGATE_EVENT_SHUTDOWN

const char* const KONGREGATE_EVENT_SHUTDOWN

Event broadcast when the API is shutting down.

This event is for advanced usage and can typically be ignored.

§ KONGREGATE_EVENT_USER

const char* const KONGREGATE_EVENT_USER

Event broadcast once user information is available.

Before this event is broadcast for the first time, users will be treated as guests. Once this event is received, the user ID and username returned will match the user that is logged into Kartridge (if any).

This event will be fired again any time the user signs out or signs in with a different Kongregate account, so you should handle it accordingly.

The game authentication token may not be available when this event is fired. If you need the authentication token, you should wait for the KONGREGATE_EVENT_AUTH_TOKEN event instead.

See also
KongregateServices_GetUsername
KongregateServices_GetUserId
KONGREGATE_EVENT_AUTH_TOKEN

§ KONGREGATE_GUEST_USERNAME

const char* const KONGREGATE_GUEST_USERNAME

Username representing a guest user - "Guest".