Javascript API

Kongregate's JavaScript API

The Kongregate JavaScript API allows you to extend your game to communicate with the Kongregate back-end. By utilizing our JavaScript API, you can access most of the features offered by our ActionScript API using a very similar interface.

📘
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.

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. If your application spans multiple pages/documents, please see the documentation on the Kongregate Shell for information on setting up and accessing a persistent API connection.

Using the API

Once the API is loaded, you can access it just as you would the ActionScript API. 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>