Kongregate Shell

Embedding Your Game Using the Kongregate Shell

For games that span multiple pages, or require multiple HTML documents, managing the JavaScript API can be somewhat troublesome.

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 via parent.kongregate. 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.

Note: If your game is a simple Flash, Unity, or HTML5 game that only utilizes a single page, it is unlikely you need to use this shell, and you will likely complicate things by doing so. You should just load the JavaScript API into your page and use it as instructed here.

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 src="https://cdn1.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, "contentdiv");
      }
      
      // 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