Packagecom.kongregate.as3.client
Classpublic class KongregateAPI
InheritanceKongregateAPI Inheritance flash.display.Sprite

The component bootstrap class that loads and connects to the Kongregate API. It contains barebones code, mostly relating to loading in the API swf.

This class is the primary channel through which a developer can access Kongregate services. It is not necessary to use the bootstrap component, however by doing so a developer can avoid manually writing the code needed to load the API into their game, as well as take advantage of data typing and warnings.

To use the component, it must first be added to the stage; either by dragging and dropping it manually from the library, or by instantiating it with new KongregateAPI() and the DisplayObject.addChild() method. Once the component has been added to the stage, it will automatically load and connect to Kongregate's API; there is no need to call connect() as in the AS2 API. Further access of the API can be gained either by using a local reference you created when you added it to the stage, or by using the static KongregateAPI.getInstance() method throughout any of your other classes. Examing the methods and properties below for more information.

Attempting to instantiate the component or add it to the stage more than once will thrown an error; however it will not interrupt a previously created singleton.

Note: The API will not load when testing in a local development environment. Instead, empty shadow services will load in their place, preventing errors from being thrown and giving you feedback through the trace window. The full services will load once you upload the game to Kongregate.

Author: Jacob Correia
Forums: http://www.kongregate.com/forums
© 2006-2007 Kongregate


Public Properties
 PropertyDefined by
  connected : Boolean
[read-only] Indicates whether or not the kongregate services are connected.
KongregateAPI
  loaded : Boolean
[read-only] Indicates whether or not the external Kongregate API services have loaded from the site and are available for developer access.
KongregateAPI
  scores : IHighScoreServices
[read-only] Returns a reference to the Scores service, through which a developer may submit and retrieve high scores from Kongregate.
KongregateAPI
  stats : IStatServices
[read-only] Returns a reference to the Statistics service, through which a developer may submit statistics to Kongregate.
KongregateAPI
  user : IUserServices
[read-only] Returns a reference to the user information service, through which a developer may retrieve a generic description of the current player.
KongregateAPI
Public Methods
 MethodDefined by
  
KongregateAPI()
Used to instantiate the Kongregate API, before using addChild() to place it on the stage.
KongregateAPI
  
getInstance():KongregateAPI
[static] Returns the previous instantiation of the KongregateAPI component.
KongregateAPI
Property detail
connectedproperty
connected:Boolean  [read-only]

Indicates whether or not the kongregate services are connected. This differs from the loaded property, in that connected will return true if shadow services (for local testing) have loaded, whereas loaded will only return true if the live services are functioning. These two flags can be used to tell your game whether testing services or live services have loaded.

Implementation
    public function get connected():Boolean

See also

loaded
KongregateEvent.COMPLETE
loadedproperty 
loaded:Boolean  [read-only]

Indicates whether or not the external Kongregate API services have loaded from the site and are available for developer access.

It is not necessary to use this in most cases, particularly since you can create an event listener that fires once the services are available. This will return false if you are testing locally and only the local shadow services have loaded.

Implementation
    public function get loaded():Boolean

See also

connected
KongregateEvent.COMPLETE
scoresproperty 
scores:IHighScoreServices  [read-only]

Returns a reference to the Scores service, through which a developer may submit and retrieve high scores from Kongregate. If tested locally, a shadow of the Scores service for debugging is returned instead.

Implementation
    public function get scores():IHighScoreServices

Example

Using a predefined reference to KongregateAPI:
  import com.kongregate.as3.client.KongregateAPI;
  var kongregate:KongregateAPI = KongregateAPI.getInstance();
  kongregate.scores.submit ( myScore );

Abbreviated example:
  import com.kongregate.as3.client.KongregateAPI;
  KongregateAPI.getInstance().scores.submit ( myScore );

statsproperty 
stats:IStatServices  [read-only]

Returns a reference to the Statistics service, through which a developer may submit statistics to Kongregate. If tested locally, a shadow of the Statistics service for debugging is returned instead.

Implementation
    public function get stats():IStatServices

Example 
  import com.kongregate.as3.client.KongregateAPI;
  var kongregate:KongregateAPI = KongregateAPI.getInstance();
  kongregate.stats.submit ( "Coin", 1 );

userproperty 
user:IUserServices  [read-only]

Returns a reference to the user information service, through which a developer may retrieve a generic description of the current player. If tested locally, a shadow of the User service for debugging is returned instead.

Implementation
    public function get user():IUserServices

Example 
import com.kongregate.as3.client.KongregateAPI;
  
function onUserInfo ( playerData:Object ):void
{
   trace ( "isGuest: "+ playerData.isGuest );
}
  
KongregateAPI.getInstance().user.getPlayerInfo ( onUserInfo );

Constructor detail
KongregateAPI()constructor
public function KongregateAPI()

Used to instantiate the Kongregate API, before using addChild() to place it on the stage. The KongregateAPI constructor should only be called if the component has not been manually placed on the game stage, or called previously.

It is not crucial that the component stay on stage indefinitely, since it only needs to be on stage during initilization.


Throws
— flash.errors.IllegalOperationError — KongregateAPI can only be added to the stage or called with new KongregateAPI() once during the course of your game. Further access should be attempted through use of the static getInstance() method, or local variable/stage references to the previously instantiated instance.

See also

KongregateAPI.getInstance()

Example 
import com.kongregate.as3.client.KongregateAPI;
var kongregate:KongregateAPI = new KongregateAPI();
this.addChild ( kongregate );

import flash.errors.IllegalOperationError;
import com.kongregate.as3.client.KongregateAPI;
  
var kongregate:KongregateAPI;
  
try {
   kongregate = new KongregateAPI();
   this.addChild ( kongregate );
}
catch ( error:IllegalOperationError ){
   trace( error );
   kongregate = KongregateAPI.getInstance();
}
  
trace( kongregate ); // [object KongregateAPI]

Method detail
getInstance()method
public static function getInstance():KongregateAPI

Returns the previous instantiation of the KongregateAPI component. This is the primary means of accessing the API throughout your game. You can call this only after the component has been insitialized, otherwise an error will be thrown.

Returns
KongregateAPI — The KongregateAPI singleton

Throws
— IllegalOperationError — Calling this method will fail if the component has not been previously added to the stage.

See also

KongregateAPI()

Example 
import com.kongregate.as3.client.KongregateAPI;
var kongregate:KongregateAPI = KongregateAPI.getInstance();