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.

The C/C++ Native API

The Native API allows your Windows application to communicate with the Kongregate Client. By using this API you can query for information about the current user, and initiate purchases through our microtransaction system.

Overview

The Kongregate Client is a lightweight application which exposes an icon in the taskbar that allows users to log in to their Kongregate account, browse our library of downloadable games, and fund their account with Kreds using various methods. The API provides functionality to communicate with this client, allowing a deep integration between your game and the user's Kongregate account.

The Native API works in a very similar fashion to our AS3 API, in that you create a global Kongregate object and make various calls on it. Only a subset of the full AS3 API is supported, but where possible the names of function calls are the same.

While the API provides low level functions to determine whether or not the Kongregate Client is installed, if the user is signed in, etc. there are also higher level functions which can help speed up integration. Our goal is to both provide a low level API for developers who want to customize every aspect of integration, along with higher level functions to make things a bit easier for those who don't require quite as much customization.

Kongregate Client

In order for the API to function properly, the Kongregate Client application must be installed. If the Kongregate Client is not installed, your app should provide a link, button, or some other UI element that allows the user to download and install the app. The isClientInstalled is provided to determine whether the Kongregate Client application is installed, and the installClient function will spawn the user's default browser to allow them to download and install the Kongregate Client application. You may also use the initializeKongregateAccount function, which will automate much of this process.

Kongregate will provide a custom installer which will download the client along with your game's installer, and then pass in a -from-kongregate=true when executing the game's setup application. You can use this flag to store something in persistent storage (registry, etc) so that your game knows to enable the Kongregate API at runtime.

Callback Notifications

When initializing the Native API, you will provide a callback function for processing events generated by the API. The callback function will be run for any pending events on the thread of your choice by calling the consumeEvents function. These callbacks will notify you of events that are generated by the client application.

The consumeEvents function should be called frequently to ensure that you are notified of events in a timely manner. It is important to call this function periodically even if you don't plan on doing anything with the information, as this function also informs the Kongregate Client that your game is still active.

Platform Support

Currently, the Native API only supports Win32 applications. The SDK contains a DLL and import library for linking, along with a wrapper for Unity. The API supports both Unicode and ANSI strings, and will provide different interfaces for each depending on whether or not UNICODE is defined.

The Kongregate Client application itself requires Windows XP Service Pack 2 or higher.

Basic Example

Below is a bare bones example of how to initialize and use the native Kongregate API in C. It sets up a basic event handler function and prints the current user's username when the API is initialized.

#include <wchar.h>
#include "KongregateApi.h"

// Global kongregate object
kongregate_api *kongregate;

// Kongregate event callback system
void __stdcall kongregate_callback(kongregate_event *event, void *data) {
  switch (event->event_code) {
    case KONGREGATE_EVENT_USER_CHANGED:
      wchar_t username[20];
      kongregate->services->getUsername(username);
      printf("Kongregate API user changed, username: %s", username);
      break;
  }
}

int main() {
  // Initialize the Kongregate API (pass in the game ID)
  kongregate = KongregateInit(12345);

  // Block here to ensure the Kongregate Client is installed and the
  // user is signed into their account.
  if(!kongregate->native->initializeKongregateAccount()){
    KongregateRelease(kongregate);
    return(0);
  }

  // Set our callback function for processing events
  kongregate->native->setCallbackFunction(kongregate_callback, NULL);

  // Process Kongregate events in a loop. This is overly simplistic.
  // You would typically do this in your event loop, with a timer,
  // or a thread. The event callback will be called on the same
  // thread as ConsumeEvents.
  while(true){
    kongregate->native->consumeEvents();
  }  
  
  // Free resources and exit
  KongregateRelease(kongregate);
  return(0);
}

Getting Started

Comments