Kongregate's Javascript API

The Kongregate Javascript API allows you to extend your game to communicate with the Kongregate back-end. By including our Javascript API, you can access most of the features offered by our Actionscript API.

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 tag of your document. 

<script src='http://www.kongregate.com/javascripts/kongregate_api.js'></script>

The Kongregate API Object

The Javascript API automatically creates a global variable named kongregateAPI. You can use this object to load the Kongregate API services with the loadAPI() and the getAPI() functions:

loadAPI(callback)
  • callback:Function - Function to call when the API is available

Example: Load the API, and call the onComplete function when loading is done.

// Load the API
var kongregate;
kongregateAPI.loadAPI(onComplete);

// Callback function
function onComplete(){
  // Set the global kongregate API object
  kongregate = kongregateAPI.getAPI();
}

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. It is important to make this call only once per Kongregate game page load. If you reload the document containing this call, or call it from multiple pages, things will break. In order to work around this, consider using a game shell as described below.

Using the API

Once the API is loaded, you can access it just as you would the Actionscript API. One thing to be aware of is that the API can only be loaded once. If your application spans across multiple pages, it is best to make a shell page (in the same domain) that loads the kongregate API, and then have all your other pages load in an IFRAME. The children can then access the already-connected Kongregate API Object by using parent.kongregate

Embedding Your Game Using the Kongregate Shell

For your convenience, Kongregate provides a simple HTML shell (right click and save-as) you can customize which will properly load and initialize the Javascript API. The shell uses the embedFrame method of the kongregateAPI object to properly embed your game into a sub-frame. Your game can then act normally, while still always having access to the Kongregate API through the parent. In order to use the shell, you must simply host it on your domain, and modify the embedFrame call to point to the proper location on your server.

embedFrame(path,elementID)
  • path:String - Path to load into the frame
  • elementID:String - The id of the element to insert the iframe into

Example:Embed a game iframe into the element named "contentdiv".

// Pass the user_id and game_auth_token parameters through for authentication.
var params = "kongregate_user_id=" + kongregate.services.getUserId() + 
                   "&kongregate_game_auth_token=" + kongregate.services.getGameAuthToken();

// Embed the kongregate-game.php file into the element named "contentdiv"
kongregateAPI.embedFrame("kongregate-game.php?" + params, "contentdiv");

Note that the shell will not work properly unless it is embedded into a Kongregate game page. In order to test, you should modify your game settings and set the Iframe URL to the location of the shell file on your server.

The contents of the example shell file can be found below. As you can see, it simply sets a placeholder div element and calls the embedFrame function once the API has been properly initialized. This ensures that the API is only loaded once, and that anything you do within your iframe is sandboxed properly so that the connection is not broken.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Kongregate Game Shell</title>
    
    <!-- Load the Kongregate Javascript API -->
    <script type="text/javascript" src="http://www.kongregate.com/javascripts/kongregate_api.js"></script>
    
    <!-- Give the shell no border/scroll bars and match the Kongregate background color.
         If your game needs scrollbars, you might need to modify these styles -->
    <style type="text/css">
      html{border: none; overflow: hidden; background-color: #333; height: 100%;}
      body{border: none; background-color: #333;margin:0; padding:0;}
    </style>
  </head>

  <body>
    <script type="text/javascript">
      // Called when the API is finished loading
      function onLoadCompleted(){
        // Get a global reference to the kongregate API. This way, pages included in the
        // iframe can access it by using "parent.kongregate"
        kongregate = kongregateAPI.getAPI();
        
        // Embed the game into the "contentdiv" div, which is defined below. You can also
        // manually create your own iframe, this function is just for convenience. 
        // This example also passes along the kongregate user_id and game_auth_token so 
        // that the page can use them for authentication.
        var params = "kongregate_user_id=" + kongregate.services.getUserId() + 
                   "&kongregate_game_auth_token=" + kongregate.services.getGameAuthToken();
        kongregateAPI.embedFrame("game.html?" + params);
      }
      
      // Begin the process of loading the Kongregate API:
      kongregateAPI.loadAPI(onLoadCompleted);
    </script>
    
    <!-- The div that the game will be placed into. Make sure to set the width and height properly -->
    <div id="contentdiv" style="top:0px; left:0px; width:700px; height:500px; borders:none;">
      <!-- You can manually put your game iframe in here instead of calling embedFrame above if you wish -->
    </div>
  </body>
</html>

Example

You can find an example implementation which demonstrates how to use the shell to load the API, as well as how to call API functions from Javascript here

API Documentation: