Note: The following information is out of date. Please refer to our new API Documentation here: http://www.kongregate.com/pages/kongregate_api

Kongregate API Integration for AS3 games

Categories:

   1. Overview

   2. The component (no longer recommended)

      2a. Downloading and installing the component

      2b. Adding the component to your game’s library

      2c. Using the component API

      2d. Accessing the API

      2e. Listening for the Services

   3. Loading the API manually (this is the recommended method)

   4. Statistics

   5. Scores

   6. High score lists

   7. Player information

   8. Summary of resources

   9. FlashDevelop Users

   10. Testing your API

Documentation:

Component API Documentation

1. Overview

The Kongregate API for Flash ActionScript 3.0 games must be loaded into your game at run time in order to take advantage of statistics and score submission.

bq. You have two choices in regards to loading the API:


   ▪ Install and use the component

   ▪ Load the API yourself

The component does not contain the API but contains code meant to ease the loading and testing process.

If you wish to use the pre-packaged component, continue on to the next section. If you want to manually load the API, skip down to section 3. Each method has its pros and cons, so its up to you to decide which method to use.

Back to top

2. The Component

Note: We now strongly recommend using the manual version of loading. It provides more control and tends to be more stable. Please use that version instead.

Using the component is not necessary, since you can manually load in the API yourself. The component is meant for those who wish to ease some of the process and reduce specific complications.

To use the component, you must first download and install it. Once you have it installed, using it in subsequent projects is a lot simpler.

Back to top

2a. Downloading and installing the component

Download the Component

Download the component below to get started. You can download either the component .swc file, the .mxp package for use with the Adobe Extension Manager, or an FLA file with the component in the library. If you already have Adobe’s Extension Manager, the best choice is to downoad the .mxp.

   ▪ .MXP component installer package

   ▪ Component .SWC file

   ▪ FLA Version

If you are not familiar with component installation and dont wish to download the extension manager, the FLA version is the next easiest choice. However, installing the component properly allows you to easily add the component to your files later.

---

Install the Component

Installation depends on which file you’ve downloaded. Follow the steps below based on which file you chose:

MXP: Open the file and follow the instructions in Adobe Extension Manager.

SWC: Manually install it into your Flash Configuration/Components folder (create a folder named “Kongregate” in the Components folder first).

   1. Quit Flash.

   2. Place the SWC in the following folder on your hard disk:

       Win: C:\Program Files\Adobe\Flash CS3\language\Configuration\Components\Kongregate

       Mac: Macintosh HD:Applications:Adobe Flash CS3:Configuration:Component:Kongregate

   3. Start Flash.

Sample FLA: Open the file in Flash and copy the KongregateAPI component from the library to your game’s library.

Once the component is installed, it will show up in the components panel in Flash (Window → Components or Ctrl+F7) as “KongregateAPI”.

If it does not show up, double check the location to make sure it’s installed, then either restart Flash or select “Reload” from the panel’s menu.

Back to top

2b. Adding the component to your game’s library

Add the Component to Your Game’s Library

Once the component is installed in Flash, you must add it to your game’s library to use it. To do so, drag the component from the component panel (or the component FLA library) to the library panel.

It should now appear in your game’s library and is ready to use.

Back to top

2c. Using the component API

Comprehensive documentation is here. We recommend you use this heavily for reference as it contains detailed information on the available methods and properties, as well as sample code.

1. Import the Kongregate libraries

import com.kongregate.as3.client.KongregateAPI;

2. Add the component to the stage

You may either manually place it there, or add it with addChild(). If you try to access its services before adding it to the stage, you will get an error.

var kongregate:KongregateAPI = new KongregateAPI();

this.addChild ( kongregate );

You now have the Kongregate API integrated in your game! If you use the component, it will automatically call connect() once it realizes it has been added to the stage and finishes loading the external API. There is no need for you to call it, unless you load the API manually.

Back to top

2d. Accessing the API

Detailed Documentation

To access the API, you can either use the local reference you’ve saved earlier, or getInstance() instead. Using the getInstance() method is recommended and is required in many cases if you are accessing the API from classes other than where it was instantiated from.

1. Import the Kongregate libraries

import com.kongregate.as3.client.KongregateAPI;

2. Save a reference or access directly

As long as the com.kongregate.as3.client.KongregateAPI class is accessible, you can use getInstance() directly or save a reference, if you wish. The API is a singleton, so it will not change throughout the course of your game.

var kongregate:KongregateAPI = KongregateAPI.getInstance();

Back to top

2e. Listening for the Services

Detailed documentation

Since the AS3 API loads in from an external source, you must wait for it to load and create its services before you ask it to perform tasks. This is usually fairly quick, however calling methods immediately after adding the component to the stage may result in dead calls or errors. To accomodate this, you can add a listener and your game will be notified when the services are available.

In many cases, you wont need to use this since most API calls come long after you add the component to the stage. However, follow these steps if you need to be notified of this event:

1. Import the Kongregate libraries

import com.kongregate.as3.client.events.KongregateEvent;

2. Define a custom callback method

This can be defined as anything, anywhere. In this case, lets just call it “myMethod” and trace out a message when it fires:

function myMethod ( e:KongregateEvent ):void

{

    trace ( “Services available; myMethod() called.” );

}

3. Add an event listener pointing to your method

Note that we are using the instance “kongregate” as defined when we added the component to the stage. If you dont have a local variable reference, you can use KongregateAPI.getInstance() instead (described earlier).

kongregate.addEventListener ( KongregateEvent.COMPLETE, myMethod );

Your custom method will now be called by the component once the services are ready. You can then submit scores or statistics.

Back to top

3). Loading the API manually

Note: Previously mentioned security issues with manual loading should be resolved.

To bypass the component and load the API yourself, 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 track the API through your own means, as importing classes and accessing singletons is not available in the same manner as in the component.

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. This is the same method the component automatically uses to assist you.

Here is some sample code showing how to load the API manually. 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 debug version (“shadow” API) will load if testing locally. 

var api_url:String = paramObj.kongregate_api_path  || “http://www.kongregate.com/flash/API_AS3_Local.swf”

Security.allowDomain(api_url); // Allow the API to access this SWF
// Debug

trace ( "API path: " + api_url );
// Load the API

var request:URLRequest = new URLRequest ( api_url );

var loader:Loader = new Loader();

loader.contentLoaderInfo.addEventListener ( Event.COMPLETE, loadComplete );

loader.load ( request );

this.addChild ( loader );
// Kongregate API reference

var kongregate:*
/**

	
Called when API swf finishes loading

*/

function loadComplete ( event:Event ):void

{

	// Save Kongregate API reference

	kongregate = event.target.content;

	

	// Connect

	kongregate.services.connect();

	

	// Debug our services

	trace ( “\n” + kongregate.services );

	trace ( “\n” + kongregate.user );

	trace ( “\n” + kongregate.scores );

	trace ( “\n” + kongregate.stats );

}

Example File

Back to top

4). Statistics

---

Overview

For information on statistics, please see the post regarding using the AS2 Statistics API. It contains descriptive information regarding using statistics, most of which apply the same to the AS3 API.

---

Submitting

The statistics object is accessible as a property of the Kongregate API named “stats”. So for instance, if you saved a reference to the API as “kongregate”, you can then access the stats object as kongregate.stats.

The main method to submit statistics from the statistics class is called “submit”:

public function submit ( name:String, value:Number ):void

You must submit a name and value pair for a statistic, e.g. “Level” and 3. (Note: While ‘Number’ is accepted, the value will be converted to an integer on the server, so it would be wise to keep that in mind and stick to the use of integers).

---

Additional

Description of alternate methods are available in the comprehensive API documentation under com.kongregate.as3.client.services.IStatServices

Example File

---

Sample statistic submission:

kongregate.stats.submit ( "Coin", 1 ); 

Back to top

5). Scores

EDIT: This section is now deprecated. Please only use the Statistics method described in Section 4. Thanks!

---

Overview

For detailed information on high scores, please see the post regarding using the AS2 Score API.

---

Submitting

The high scores object is accessible as a property of the Kongregate API named “scores”. So for instance, if you saved a reference to the API as “kongregate”, you can then access the scores object as kongregate.scores.

The main method to submit high scores from the statistics class is called “submit”:

public function submit ( score:Number, mode:String = null ):void

The only required field is the score, containing the value you wish to submit.

The mode parameter is an optional value specifying the mode to submit this stat under. If no value is submitted, the last mode that was set will be used. Submitting a value for mode will change the high score mode just the same as using setMode() would. If you are worried you will get modes confused, avoid this parameter and use the setMode() method instead.

---

Modes

For detailed information on score modes, please see the section “HIGH SCORE MODES” in the AS2 Score API post.

public function setMode ( mode:String ):void

Sets the mode to be used, such as ‘Hard’, ‘Normal’, ‘Easy’, which is used for submitting and retrieving high score lists. The name of the mode is up to the developer to decide and it affects the display name used in the leaderboards (e.g. ‘HighScore-Hard)’.

Once you set the mode, any scores sent using the submit() method will be saved under that mode, unless you use the mode parameter when calling submit().

---

Additional

Description of alternate methods are available in the comprehensive API documentation under com.kongregate.as3.client.services.IHighScoreServices.

Example File

---

Sample score submission:

// Basic example, pulling our score from a variable:
kongregate.scores.submit ( myScore );  

// Example using the mode parameter 

kongregate.scores.submit ( myScore, “Hard” );  

// Example using the setMode() method: 

kongregate.scores.setMode ( “Hard” );

kongregate.scores.submit ( myScore );  

Back to top

6). High score lists

EDIT: This section is now deprecated – this portion of the API has been removed.

---

Overview

Retrieving high score lists is done through the “scores” object of the API, as discussed in section 5.

---

Retrieving

public function requestList ( callback:Function ):void

Retrieves a high score list from the server.

Parameters


   callback:Function — A method to pass the high score data back to once the server responds.

The object sent to the return method will have the following properties:

   success – Boolean. Whether the call was successful. When testing locally, this parameter will be false.

   list – Array. An ordered list of objects containing the properties username and score for each of the players on the list.

// Assuming we have a TextField named "my_txt":
function scoresCallback ( result:Object ):void
{
	my_txt.appendText("High score result, success=" + result.success );
	
	for ( var i:int = 0; i < result.list.length; i++ ){
		var position:int = i + 1;
		my_txt.appendText("\n"+position + ". " + result.list[i].username + " - " + result.list[i].score );
	}
}

// Request the list
kongregate.scores.requestList ( scoresCallback );

Detailed documentation

Back to top

7). Player information

EDIT: This functionality is no longer available in our AS3 API. It has been suspended indefinitely because no one was using it (in fact, it disappeared in March and no one even noticed until a developer asked about it in August!).

Detailed service documentation

Detailed object documentation

Back to top

8). Summary of resource links

Comprehensive component API Documentation and examples

Adobe Extension Manager

Component

   ▪ .MXP component installer package

   ▪ Component .SWC file

   ▪ FLA Version

Sample Files

   ▪ Basic Example

   ▪ High Scores

   ▪ Statistics

   ▪ Player Data

Back to top

FlashDevelop Users:

SWC usage is supported in the latest versions of FlashDevelop, so you can integrate the component into your FD projects the same as in the Flash IDE, taking advantage of the same features.

If you choose to use the component make sure you’ve patched your Flex 2 SDK with the: Flex 2.0.1 patch for Adobe Flash CS3 Professional compatibility, otherwise your builds may fail.

Back to top

Testing your API on Kongregate

[added by Phoenix00017]

So, you’ve gotten your API all hooked up and the Shadow Services look good, but will it work when you go live? Probably, but let’s make sure. Once you load up your game into Preview mode, you’ll have an opportunity to test everything out before you make it live by hitting the Publish button. In order to see the stat messages, you’ll need to be in Firefox and running the Firebug add-on. Add ?debug_level=4 to the end of your game URL and you’ll be able to see stat submission. If you want to test it out on a game, go to http://www.kongregate.com/games/jmtb02/kongregate-chat?debug_level=4. When you submit a stat, you’ll see this appear:

[Konduit] [Game→Chat]: stat.submit: {"stats":[{"name":“HighScore”,value],req.id

And shortly answered with the confirmation:

[Konduit] Kongregate Packet[admin] stat.submit: 

{"success":true,“stats”:{"1778":58},resend,req.id,msg.id

That means it’s all working. You can also tell if it’s working if the tab on the right of your game says Achievements instead of More Games. Note that you need at least one successful stat submit for that to work, and you’ll need to reload the page after the very first submission to see the new tab. Note also that when you do this with your Preview game, you’ll have “preview?debuglevel=4” at the end of the game URL.

If you see the Achievements tab, then you’re good to go.

Reserved

Reserved

How soon do you think we will see AS3 badges?

I really dont know. That depends on developers and what they decide to do. I know there are a few waiting for the API, so I’m hoping that means they’ll jump on it right away.

Way to go!! This looks promising, THANKS!!

Awesome news, cheers :)

Out of curiousity, is AS3 much more complicated than AS2? That’s what this thread makes it look like.

Some would say yes. It is much more strict and more like “real” languages, therefore much easier to do something wrong. “Inexperienced” AS2 developers often have a hard time in it (and therefore view it negatively), whereas experienced AS2 OOP programmers as well as Java and C coders have been seen to find the transition easy – and as a result tend to like it. It really depends on your experience and practices. Its definitely not the forgiving beast the AS2 is.

In answer to your question, I really dont know. That depends on developers and what they decide to do. I know there are a few waiting for the API, so I’m hoping that means they’ll jump on it right away.

Eagerly awaiting ^^ that doesn’t mean my game will be good though. lol I’m willing to treat it more as a experimental/testing application to make sure your API doesn’t fail :)