Javascript API
Kongregate's JavaScript API
The Kongregate JavaScript API allows you to extend your game to communicate with the Kongregate back-end.
Note
Unity games should use JavaScript to access the API. For more information see this link..
Loading the API
In order to load the Kongregate API object, you need to include a script tag which loads our JavaScript source file. The script tag should be placed inside the head section of your document.
<script src='https://cdn1.kongregate.com/javascripts/kongregate_api.js'></script>
Initializing the API
The JavaScript API automatically creates a global variable named kongregateAPI. You can use this object to initialize the Kongregate API services with the loadAPI and the getAPI functions:
Example: Load the API, and set up a global reference to the API object named kongregate function once initialized. You must wait for the API to initialized before accesses the API.
kongregateAPI.loadAPI(function(){
window.kongregate = kongregateAPI.getAPI();
// You can now access the Kongregate API with:
// kongregate.services.getUsername(), etc
// Proceed with loading your game...
});
As you can see, once the callback function is called, you can create a reference to the Kongregate API object using the getAPI function. This will allow you to access the various services described in the rest of the documentation on this site.
Note
The API should only be loaded/initialized once per Kongregate game page load.
Using the API
Once the API is loaded it is available for use. For the most part, the interfaces, classes, and methods have the same names and signatures. If a method is unavailable to the JavaScript API, it will be noted in the documentation.
These examples assume the loadAPI function has already completed, and there is a global kongregate variable available.
Example: Submit a statistic named "Score" with a value of 1000.
kongregate.stats.submit('Score', 1000);
Example: Register a listener for when a user signs in to their Kongregate account.
kongregate.services.addEventListener('login', function(){
var username = kongregate.services.getUsername();
console.log('Kongregate username changed to: ' + username);
});
Putting it all together
The following HTML page loads and initializes the JavaScript API, and displays some information about the current Kongregate user. If the user is a guest, it allows them to sign in or register, and updates itself afterward. If you host this file on your server and set it up as an iframe game on Kongregate you can use it as a starting point for API integration.
Example: Basic usage of the JavaScript API
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns='http://www.w3.org/1999/xhtml'>
<head>
<title>Kongregate Javascript API example</title>
<script src='https://ajax.googleapis.com/ajax/libs/jquery/2.2.0/jquery.min.js'>
</script>
<script src='https://cdn1.kongregate.com/javascripts/kongregate_api.js'>
</script>
</head>
<body style='background-color:white'>
<span id='init'>Initializing...</span>
<div id='content' style='display:none'>
<div>Kongregate API Loaded!</div>
<div id='username'></div>
<div id='user_id'></div>
<button id='login' style='display:none'
onclick='kongregate.services.showRegistrationBox()'>
Sign in/register
</button>
</div>
<script type='text/javascript'>
function updateFields() {
$('#init').hide();
$('#content').show();
$('#username').text('Username: ' + kongregate.services.getUsername());
$('#user_id').text('User ID: ' + kongregate.services.getUserId());
if(kongregate.services.isGuest()) {
$('#login').show();
} else {
$('#login').hide();
}
}
kongregateAPI.loadAPI(function(){
window.kongregate = kongregateAPI.getAPI();
updateFields();
kongregate.services.addEventListener('login', function(){
updateFields();
});
});
</script>
</body>
</html>
Note
This example will only function on Kongregate.com which you can preview in the sandbox environment under preview.
Updated about 1 year ago