API Events Overview

The Kongregate API will fire various events to the hosting application. Here’s a description of each event that is fired. The API provides constants for each of these events, their string names are used here for portability. The API’s support registering a listener for the events or to manually poll for new events.

KONG_API_EVENT_READY

Broadcast when the API is initialized and ready to use. Unless otherwise specified, it is not safe to call other functions until this event is fired. The initialization process is generally on the order of a couple seconds, and doesn't depend on any network requests, just disk I/O. Once you've received this event you can request information about the current Kongregate user.

KONG_API_EVENT_USER_CHANGED

This event is generated when the Kongregate user ID changes. Each game will handle this scenario differently. If your game does not have a server component you may simply need to update some UI at this point. If you have a server and are using our Authentication API then you will likely be more interested in the KONG_API_EVENT_GAME_AUTH_TOKEN_CHANGED event, which always follows this one.

KONG_API_EVENT_GAME_AUTH_TOKEN_CHANGED

Broadcast when the user's game authentication token has changed. This can be due to the user changing, or their authentication token changing. This means you should re-authenticate with our server if using the Authentication API. Otherwise, you can ignore this event.

KONG_API_EVENT_LOGIN_COMPLETE

Broadcast when a user login, either with an existing user or by registering a new user, in the Kongregate Panel. This event will always follow KONG_API_EVENT_USER_CHANGED and KONG_API_EVENT_GAME_AUTH_TOKEN_CHANGED. You may the preceding two events w/o this event, if a user changes outside of your game.

KONG_API_EVENT_OPENING_KONGREGATE

Broadcast when the Kongregate panel is about to be opened. You can use this as an opportunity to pause your game, mute sound, etc.

KONG_API_EVENT_CLOSED_KONGREGATE

Broadcast when the Kongregate panel has closed. You should resume gameplay, unmute sound, etc.

KONG_API_EVENT_USER_INVENTORY

Broadcast when the user's inventory is received after a call to requestUserItemList. At this point you can call hasItem to determine if the Kongregate user has a given item in their inventory.

KONG_API_EVENT_SERVICE_UNAVAILABLE

Broadcast when Kongregate is unavailable. This may be due to network connectivity or Kongregate may be down for maintence.

Using an Event Listener

The preferred method for listening for API events is to use an event listener.

Your event listener will be called on the Main/UI thread, so you should be sure to not perform any I/O in your callback.

The listener should be a global object that is registered as soon as possible after the API is initialized so you can start receiving events.

Objective-C / iOS

// register a selector to handle API events
[[KongregateAPI instance] setApiEventListener:self selector:@selector(onKongregateApiEvent:)];
...

-(void)onKongregateApiEvent:(NSString *)event {
    NSLog(@"GOT EVENT FROM API: %@", event);
    if ([event isEqualToString:KONGREGATE_EVENT_READY]) {
      // API is Ready
    }
}

Java / Android

KongregateAPI api = APIBootstrap.getInstance();
api.addEventListener(new KongregateEventListener() {
  @Override
  public void onEvent(String event) {
    if (KongregateEvent.READY.equals(event)) {
      // API is Ready
    }
  }
});

C# / Unity

KongregateAPI api = KongregateAPI.GetAPI();
api.SetEventListener("Kongregate", "HandleKongregateEvent");
...

void HandleKongregateEvent(string eventName) {
  switch(eventName) {
    case KongregateAPI.KONGREGATE_EVENT_READY:
      // API is Ready
  }
}

Manual Polling

If setting up an event listener is not feasible in your environment, then you can also poll manually for events using the pollEvents method on the main API object. This method will return an array of pending event strings that you can iterate through and process manually.

Objective-C / iOS

// Setup a timer to poll through new events every 2 seconds. If calls
// the same onKongregateApiEvent selector used in the listener example.
static dispatch_queue_t _kongregateEventPollQueue = dispatch_queue_create("Kongregate Event Poll", DISPATCH_QUEUE_SERIAL);
_kongregateEventPollTimer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, _kongregateEventPollQueue);
dispatch_source_set_timer(_kongregateEventPollTimer, dispatch_time(DISPATCH_TIME_NOW, 2ull * NSEC_PER_SEC),
  2ull * NSEC_PER_SEC, 2ull * NSEC_PER_SEC);
  dispatch_source_set_event_handler(_kongregateEventPollTimer, ^{
    for (NSString* event in [[KongregateAPI instance] pollEvents]) {
      dispatch_async(dispatch_get_main_queue(), ^{
        [self onKongregateApiEvent:event];
      });
    }
  });
dispatch_resume(_kongregateEventPollTimer);

Java / Andriod

// Setup a timer to poll through new events every 2 seconds. If calls
// the same handleEvent method used in the listener example.
final Activity main = this;
Timer timer = new Timer();
timer.schedule(new TimerTask() {
  @Override
  public void run() {
    main.runOnUiThread(new Runnable() {
    @Override
    public void run() {
      for (String event : mAPI.pollEvents()) {
        handleEvent(event);
      }
    }
   });
  }
}, 0, 2000);

C# / Unity

Not Supported. Use the listener method.