Kongregate Developers

Handling Guests in Kongregate Games

Since guests are not allowed to access many different parts of the API, each developer must decide how they want to treat them. This document will go over how to detect when a user converts from a guest to a registered user in-page, which can happen without your game being reloaded. This documentation is meant to be supplimental to all other API documentation, and it assumes you have a general knowledge of how our API works, and are interested in improving the experience for guests who play your game.

You can determine if the user is a guest initially by calling the isGuest() function on the Kongregate API services object:

kongregate.services.isGuest()

Testing guest functionality

In order to test your game as a guest while it is still in the preview state, you must append a special guest_access_key parameter to your game URL. The link to your game which includes this key can be found on the same page as your API key as described in the REST API intro.

Guest to user conversion

The AS2 or AS3 client API must be used in order to detect when a user signs in. There are two different methods possible for detecting the change: listening for an event and manual polling.

User sign-in event

When a user signs in using the welcome box or the link from chat, your application will receive an event (if you have registered for it) and you can process it however you like. Once the user is signed in, they will be able to save data, submit statistics, etc.

Integration

Once the Kongregate client API has successfully loaded into your application, you may register an event listener to let you know when a player converts from a guest to a registered user, which can happen without the page being reloaded:

kongregate.services.addEventListener("login", onKongregateInPageLogin);

function onKongregateInPageLogin(event:Event){
  var user_id:Number = kongregate.services.getUserId();
  var username:String = kongregate.services.getUsername();
  var token:String = kongregate.services.getGameAuthToken();
}

Manual polling

While less efficient, this is can be the simplest method for catching the username/user_id change, as you can do it on your own terms, and handle the change when you are ready.

You can check manually for the username change by calling the getUsername function on the kongregate.services object, and detecting the change. If the user starts out as a guest, and they sign-in, the function will return their new username, and you can retrieve their game_auth_token and user_id using the getGameAuthToken and getUserId functions.

AS2 integration

Unfortunately, no official API is currently available for AS2, but the following code template (while a bit dirty) should suffice:

// Check to see if the user is a guest initially
var services = _global.kongregate.services;
var isGuest:Boolean = services.isGuest();

// Register an event listener if the user is a guest, otherwise we can skip it
if( isGuest ){
  services.addMessageHandler({handleMessage:myMessageHandler});
}

// This function handles internal Kongregate API messages, we use it to listen
// for the sign-in message so we can be notified when a user converts from a
// guest to a user. 
function myMessageHandler(msg):Void{
    // Make sure to only handle the "user.info" message
  if( msg.getOpcode() == "user.info"){
    // If we started as a guest and aren't anymore, a sign-in occured
    if( isGuest && !services.isGuest() ){
      // Don't process this message more than once
      isGuest = false;

      // At this point services.getUsername() will contain the new username,
      // services.getUserId() will contain the player's Kongregate user_id,
      // and services.getGameAuthToken() will contain the new auth_token
    }
  }
}

Showing the registration lightbox

You can use the Kongregate API to display a sign-in/register lightbox to the user. This functionality comes in handy for upselling the user to create a Kongregate account, for example if they want to purchase an item.

This will show as an overlay, exactly as if they had clicked the "sign-in" or "register" link in the chat UI:

kongregate.services.showRegistrationBox();

If the user successfully signs in, or registers an account, you will receive the login event as described above which contains their new username and game_auth_token.

When possible, especially on guest landing pages prior to loading a game, please use the Kongregate registration button provided below:

Comments