Handling Guests

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 Server Side HTTP documentation.

Guest to user conversion

There are two different methods possible for detecting when a user signs into their account while playing your game: 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() {
  var user_id = kongregate.services.getUserId();
  var username = kongregate.services.getUsername();
  var token = kongregate.services.getGameAuthToken();
}

Manual polling

While slightly 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 isGuest 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 true, and you can retrieve their game_auth_token and user_id using the getGameAuthToken and getUserId functions.

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 up-selling the user to create a Kongregate account, for example if they want to purchase an item.

This will show a registration 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 either of these Kongregate registration button provided below:

Download