[Kongregate API] AS3 API Integration

arcaneCoder 4482 posts

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.

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.

arcaneCoder 4482 posts

2. The Component

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.

arcaneCoder 4482 posts

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.

arcaneCoder 4482 posts

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.

arcaneCoder 4482 posts

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.

arcaneCoder 4482 posts

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();

arcaneCoder 4482 posts

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.

arcaneCoder 4482 posts

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;

// 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.api_path || "http://www.kongregate.com/flash/API_AS3_Local.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

arcaneCoder 4482 posts

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 );

arcaneCoder 4482 posts

5). Scores

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 );

arcaneCoder 4482 posts

6). High score lists

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

Detailed service documentation

arcaneCoder 4482 posts

7). Player information

Detailed object documentation

Comprehensive component API Documentation and examples

arcaneCoder 4482 posts

8). Summary of resource links

Adobe Extension Manager

Component
   ▪ .MXP component installer package
   ▪ Component .SWC file
   ▪ FLA Version

Sample Files
   ▪ Basic Example
   ▪ High Scores
   ▪ Statistics
   ▪ Player Data

arcaneCoder 4482 posts

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.

arcaneCoder 4482 posts

Reserved

arcaneCoder 4482 posts

Reserved