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:
Updated 8 months ago