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 Events

Overview

The Native API sends events to your callback function when you call consumeEvents. Below is a breakdown of the different types of events, along with their meaning. Note that you do not need to handle every event code, some are provided only for debugging/informational purposes.

Event Structure

When an event is fired, your callback function will be called, and a kongregate_event pointer will be passed in. This structure has several fields:

Event Codes

KONGREGATE_EVENT_API_CONNECTED

This event code is generated when the API first establishes communication with the Kongregate Client application. At this point the Kongregate Client will attempt to retrieve an authentication token for the user if they are signed in.

KONGREGATE_EVENT_USER_CHANGED

This event will be fired initially (even if the user is a guest) after the KONGREGATE_EVENT_API_CONNECTED event to provide you with information about the current user. If the user is not a guest, you can use the getGameAuthToken function to retrieve the token and authenticate the user.

This event will also be generated if the user signs in or out of the Kongregate Client while your game is running.

KONGREGATE_EVENT_USER_AUTH_CHANGED

This event is generated when the user's game authentication token changes during a gameplay session. This should be rare, but can happen if the user changes their password or their token is expired through other means.

KONGREGATE_EVENT_USER_INFO_UPDATE

This event is fired when the user's information changes. It will not be fired if the user ID or auth token changes, but rather if some other information such as username, avatar, points, or level is updated.

KONGREGATE_EVENT_PURCHASE_RESULT

This is fired after a purchase is requested. The result_code will be KONGREGATE_RESULT_SUCCESS if the user successfully completed the purchase, or KONGREGATE_RESULT_FAILURE if they closed the window or canceled the purchase. You can use this event as a hint to refresh the player's inventory from your game server.

KONGREGATE_EVENT_API_DISCONNECTED

This event will be fired if the API can no longer communicate with the Kongregate Client. This can happen if the user exits or uninstalls the application. While the API is disconnected, function calls will be queued and then discarded if a connection cannot automatically be re-established.

KONGREGATE_EVENT_HTTP_CONNECTION_PROBLEM

This event fires when the Kongregate Client is having trouble communicating with our servers. The client will keep retrying, but you can use this event to communicate to the user that there is a connection problem.

KONGREGATE_EVENT_API_ERROR

This event will be generated if the API is initialized incorrectly, for example passing an invalid game ID.

KONGREGATE_EVENT_CLIENT_UNINSTALLED

This event will be fired if the system detects that the Kongregate Client has been uninstalled. It is generally a good idea to inform the user that the game requires the client to function properly at this point.

KONGREGATE_EVENT_CLIENT_INSTALLED

This event will be fired if the system detects that the Kongregate Client has been installed. The game will automatically launch the client and establish a connection at this point.

Result Codes

KONGREGATE_RESULT_SUCCESS

KONGREGATE_RESULT_FAILURE

Error Codes

KONGREGATE_ERROR_NONE

KONGREGATE_ERROR_UNKNOWN

KONGREGATE_ERROR_NOT_AUTHENTICATED

KONGREGATE_ERROR_INVALID_GAME

Comments