Kartridge C API Documentation
|
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... | |
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 uint32_t KONG_ASYNC_CALLBACK_ID |
Integer type that represents a kongregate asynchronous callback ID.
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.
context | The optional context data that was passed in when the event callback was set |
event_name | The name of the event as a NULL-terminated string |
event_payload | A NULL-terminated string containing a JSON object with event parameters |
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.
context | The optional context data that was passed in when the asynchronous method was originally called |
id | The asynchronous request ID returned from the method that started the asynchronous request |
success | A flag indicating whether or not the asynchronous operation completed successfully |
instance | The item instance that was being consumed, purchased, etc. |
typedef struct KongItemInstance KongItemInstance |
This structure holds information about an item instance in the user's inventory.
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.
event_name | The name of the event as a NULL-terminated string |
event_payload | A NULL-terminated string containing a JSON object with event parameters |
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.
settings_json | An optional string representation of a JSON object containing API settings. Can be NULL to use all defaults. |
bool KongregateAPI_IsConnected | ( | ) |
bool KongregateAPI_IsReady | ( | ) |
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.
game_id | The Kongregate game ID for your game |
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.
callback | The function that will be called when an event notification is fired |
context | Optional data to pass along to the callback when it is called |
KONG_DEPRECATED void KongregateAPI_SetEventListener | ( | kongregate_event_listener | listener | ) |
This method is deprecated, use KongregateAPI_SetEventCallback instead.
listener | The function that will be called when an event notification is fired |
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.
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.
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.
id | The ID of the item instance that you wish to consume |
callback | The callback method which will be called when the operation is completed or has failed. |
context | Optional data to pass along to the callback when it is called |
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.
index | The index of the item to retrieve (0 based) |
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.
index | The index of the item to retrieve (0 based) |
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.
order_info | The order_info string that will be passed to your server for processing. |
callback | The callback method which will be called when the operation is completed or has failed |
context | Optional data to pass along to the callback when it is called |
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.
identifier | The identifier that you set up for the item that you wish to be purchased (case sensitive) |
consume | If 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 |
callback | The callback method which will be called when the operation is completed or has failed |
context | Optional data to pass along to the callback when it is called |
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.
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.
game_id | The game ID to check |
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.
game_id | The game ID to check |
const char* KongregateServices_GetGameAuthToken | ( | ) |
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.
uint32_t KongregateServices_GetUserId | ( | ) |
const char* KongregateServices_GetUsername | ( | ) |
void KongregateStats_Submit | ( | const char * | statistic_name, |
int64_t | value | ||
) |
Submit a statistic with the given name and value.
statistic_name | The name (not ID) that you chose for the statistic (must match exactly) |
value | The value to submit |
const char* const KONGREGATE_EMPTY_EVENT_PAYLOAD |
An empty JSON event payload.
const char* const KONGREGATE_EMPTY_STRING |
An empty NULL-terminated string.
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.
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.
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.
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.
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.
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.
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.
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.
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.
const char* const KONGREGATE_GUEST_USERNAME |
Username representing a guest user - "Guest".