Kongregate Developers

Note: This feature will not function unless we have enabled it for your game. If you would like to have this feature enabled, please contact us.

Native C/C++ API Functions

Overview

In general, Native API functions behave similarly to their counterparts in our other APIs. The Native API does not yet support all of the functionality implemented in our web API, but we are working to bridge the gap where it makes sense.

For simplicity, we will use wchar_t as the character type in this documentation. If UNICODE is not defined when including the API header file, then these functions will accept char buffers instead.

Differences from ActionScript/JavaScript API

If you are familiar with your existing APIs, you will notice that the Native API is fairly similar. This was done so that existing documentation can be reused, and to leverage the fact that many developers have experience with our web APIs. Listed below are several major differences between the APIs to watch out for:

Initialization/Cleanup

kongregate_api *KongregateInit(unsigned int gameId)
  • gameId - Your game ID
  • returns - An instance of the Kongregate API object

Creates an instance of the Kongregate API object. The API will automatically spawn a thread to manage the connection to the Kongregate Client application. If the application is installed but not running, it will be started.

void KongregateRelease(kongregate_api *api)
  • api - The pointer to the kongregate_api object

Frees resources related to the API, and destroys the API object.

Native Methods

These methods are accessible through the kongregate->native object. They are specific to the Native API, and have no similar function in our other APIs.

unsigned int initializeKongregateAccount()
  • returns - 1 if the user is now signed into their Kongregate account through the client, 0 otherwise.

This is a blocking function that wraps up many of the low-level functions described below into a single call. It will ensure the Kongregate Client is installed, prompting the user to do so if it isn't. It will the connect to the API, and prompt the user to sign in or create an account. It will return 1 once the user has completed this process, or 0 if the canceled. If this function returns 0, you should either display an error message or exit the application.

This function should be called as soon as possible after the start of your application.

unsigned int isClientInstalled()
  • returns - 1 if the Kongregate Client app is installed, 0 if not.

This function can be called to determine if the Kongregate Client is installed on the user's machine.

void installClient()

Launches a browser to the download page for the Kongregate Client using the user's default browser.

void setCallbackFunction(kongregate_callback_fn callback void *data)
  • callback - A function that accepts a kongregate_event* and void * argument.
  • data - An optional pointer to data that you would like passed to your callback function.

The provided callback will be called with pending events when the consumeEvents function is performed.

Example callback function format:

void kongregate_callback(kongregate_event *event, void *data) {
  switch(event->event_type) {
    // Handle events here
  }
}

...

// Set the handler
kongregate->native->setCallbackFunction(kongregate_callback, NULL);
void consumeEvents()

This function will process any pending events generated by the Kongregate API. It is provided to give developers control over the threading and timing of calls to their callback function. It should be called frequently to make sure events get processed quickly.

Your callback function will be fired (potentially multiple times) during the execution of this function, but the function itself will not block waiting for events. It will return immediately if there is nothing to process.

This function is guarded by a lock that ensures it can't be called from two separate threads simultaneously. If you attempt to perform multiple consumeEvents calls at once from different threads, the subsequent calls will return immediately.

Service Methods

These methods are accessible through the kongregate->services object. They are a subset of the methods available in the ActionScript API. These methods can be used for obtaining information about a user, or allowing them to sign in or register.

unsigned int getUserId()
  • returns - The user's Kongregate ID, or 0 if the user is a guest
unsigned int isGuest()
  • returns - 1 if the user is a guest (not authenticated), 0 otherwise.
void getUsername(wchar_t outUsername[20])
  • outUsername - The buffer to place the user's Kongregate username into
void getGameAuthToken(wchar_t outAuthToken[100])
  • outAuthToken - The buffer to place the user's game authentication token into

You can use the game authentication token along with the user ID to make calls to our REST API from your game server.

void showRegistrationBox()

This function will instruct the Kongregate Client to spawn a browser allowing the user to create a Kongregate account, or sign into an existing one. Your application will be notified if the request is successful.

Microtransaction Methods

These methods are accessible through the kongregate->mtx object. They are a subset of the methods available in the ActionScript API. These methods can be used for initiating purchases or funding the user's account with Kreds. Currently, only the Dynamic Item Orders API is supported for purchasing.

void purchaseItemsRemote(const wchar_t *orderInfo)
  • orderInfo - A string that will be passed to your game server to identify the items the user wishes to purchase.

This function will instruct the Kongregate Client to spawn a browser allowing the user to initiate a purchase. If the user is not logged in, they will be allowed to sign in or create an account. For more information on how this string gets passed along to your web server, please read the Dynamic Item Orders API documentation.

void showKredPurchaseDialog(const wchar_t *method)
  • method - The purchase method to use, if any. This should be either "mobile", "offers" or NULL.

This function will spawn a Kred purchase dialog to allow the user to fund their account with Kreds. The method parameter can be "mobile" to initially display mobile payment methods, "offers" to show TrialPay free Kreds offers, or NULL to spawn the default dialog.

Comments