ActionScript 3 API

Kongregate's ActionScript3 API

The Kongregate ActionScript 3 (AS3) API allows you to extend your game to communicate with the Kongregate back-end.

Dynamically loading the Kongregate AS3 API

To dynamically load the AS3 API, you must retrieve the API path from the FlashVars and use a Loader object to load the SWF – as you would any other. Once you load it in, you must keep a reference to the API object through whatever means you like.

When testing locally, you will not have access to the live API. Instead, you can optionally have “shadow” services load that can assist you in validating proper interfacing with the API.

Example code

Below is some simple code that shows how to retrieve the API SWF path from the FlashVars and then load the API from Kongregate. If you are testing locally, and the FlashVars do not exist, then the "shadow" services will be loaded in instead.

Note that to access FlashVars in AS3, you must have access to the root object, either from a DisplayObject already in the display list, or a reference saved from an active DisplayObject. The means in which you handle this is your choice.

import flash.display.LoaderInfo;
import flash.display.Loader;
import flash.net.URLRequest;
import flash.events.Event;
import flash.system.Security;

// Pull the API path from the FlashVars
var paramObj:Object = LoaderInfo(root.loaderInfo).parameters;

// The API path. The "shadow" API will load if testing locally. 
var apiPath:String = paramObj.kongregate_api_path || 
  "http://cdn1.kongregate.com/flash/API_AS3_Local.swf";

// Allow the API access to this SWF
Security.allowDomain(apiPath);
Security.allowInsecureDomain(apiPath);

// Load the API
var request:URLRequest = new URLRequest(apiPath);
var loader:Loader = new Loader();
loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loadComplete);
loader.load(request);
this.addChild(loader);

// Kongregate API reference
var kongregate:*;

// This function is called when loading is complete
function loadComplete(event:Event):void
{
    // Save Kongregate API reference
    kongregate = event.target.content;

    // Connect to the back-end
    kongregate.services.connect();

    // You can now access the API via:
    // kongregate.services
    // kongregate.user
    // kongregate.scores
    // kongregate.stats
    // etc...
}

The Kongregate API Object

As you can see in the function above, we keep a reference to the "Kongregate API" object and store it in the variable named kongregate. This is the assumption that is made for the remainder of the documentation, so if you store this reference in a different way, make sure to modify the examples accordingly.

Security/Cross-domain Considerations

If you need to access the API from a SWF that is hosted on another domain, then special measures must be taken. In order for our API to be able to perform callbacks in your SWF, you must first make a call to Security.allowDomain to grant permissions.

Once the SWF which intends to use the API has a reference to it (possibly by having it passed in from a preloader hosted on Kongregate), it should make the allowDomain call on the URL for the API. This can be done programmatically as shown in the example below:

Security.allowDomain(kongregate.loaderInfo.url);

Using the AS3 API from an IFrame

If you need to access the AS3 API from a game hosted in an IFrame, you will need to pass along all the appropriate variables into your SWF. Documentation on how to do this can be found here.

Once the API is loaded, you can start using functions from the Client API in your application.