QuickKong - Easy Kong API Integration

54 posts

Flag Post

QuickKong on ProfusionGames.com

What is QuickKong

QuickKong is an AS3 class that will load and extract the Kongregate API for you without you even having to glance at the documentation and copy the code examples there. QuickKong hides all the brute work and makes connection to Kongregate into a single line: QuickKong.connectToKong(stage);

How do I use QuickKong

  1. Copy and Paste the Code at the end of this post into a new .as file.
    Save the .as file as QuickKong.as
  2. Connect to Kongregate as soon as possible within your game with QuickKong.connectToKong(stage);
  3. Submit scores anywhere in your game with QuickKong.stats.submit("HighScore", 9001);
  4. Access the rest of the API with QuickKong.propertyName


QuickKong.as

Direct Download Link

package
{
	/**
	 * QuickKong by UnknownGuardian. August 26th 2011.
	 * Visit http://profusiongames.com/ and http://github.com/UnknownGuardian
	 *
	 * Copyright (c) 2010 ProfusionGames
	 *    All rights reserved.
	 *
	 * Permission is hereby granted, free of charge, to any person
	 * obtaining a copy of this software and associated documentation
	 * files (the "Software"), to deal in the Software without
	 * restriction, including without limitation the rights to use,
	 * copy, modify, merge, publish, distribute, sublicense, and/or sell
	 * copies of the Software, and to permit persons to whom the
	 * Software is furnished to do so, subject to the following
	 * conditions:
	 *
	 * ^ Attribution will be given to:
	 *  	UnknownGuardian http://www.kongregate.com/accounts/UnknownGuardian
	 *
	 * ^ Redistributions of source code must retain the above copyright notice,
	 * this list of conditions and the following disclaimer in all copies or
	 * substantial portions of the Software.
	 *
	 * ^ Redistributions of source code may not add to, subtract from, or in
	 * any other way modify the above copyright notice, this list of conditions,
	 * or the following disclaimer for any reason.
	 *
	 * ^ Redistributions in binary form must reproduce the above copyright
	 * notice, this list of conditions and the following disclaimer in the
	 * documentation and/or other materials provided with the distribution.
	 *
	 * THE SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
	 * IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
	 * NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
	 * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
	 * OR COPYRIGHT HOLDERS OR CONTRIBUTORS  BE LIABLE FOR ANY CLAIM, DIRECT,
	 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
	 * OR OTHER LIABILITY,(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
	 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
	 * WHETHER AN ACTION OF IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
	 * NEGLIGENCE OR OTHERWISE) ARISING FROM, OUT OF, IN CONNECTION OR
	 * IN ANY OTHER WAY OUT OF THE USE OF OR OTHER DEALINGS WITH THIS
	 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
	 * 
	 * 
	 * 
	 * 
	 * 
	 * 
	 * English: Use, distribute, etc to this with keeping credits and copyright
	 */
	import flash.display.Loader;
	import flash.display.LoaderInfo;
	import flash.display.Stage;
	import flash.system.Security;
	import flash.events.Event;
	import flash.net.URLLoader;
	import flash.net.URLRequest;
	
	public class QuickKong
	{		
		public static var api:* = null;
		
		public static var chat:* = null;
		public static var services:* = null;
		public static var stats:* = null;
		public static var mtx:* = null;
		public static var sharedContent:* = null;
		public static var images:* = null;
		
		public static var userName:String = "";
		public static var userId:String = "";
		public static var userToken:String = "";
		public static var isGuest:Boolean = false;

		private static var connectCallback:Function = null;
		
		public function QuickKong()
		{
			throw new Error("[QuickKong] Error: Do not create an instance of this class, as it contains all static functions");				
		}
		
		/**
		 * connectToKong
		 * @description		Connects to Kongregate
		 * @param			s: The stage that the Kongregate API loader will be added too.
		 * @param			preConnectCallback: Optional param. Useful for Shared Content API.
		 */
		public static function connectToKong(s:Stage, preConnectCallback:Function=null):void
		{		
			trace("[QuickKong] connectToKong()");

			connectCallback = preConnectCallback;
			//grab the loaderinfo param
			var paramObj:Object = LoaderInfo(s.root.loaderInfo).parameters;
			
			// The API path. The "shadow" API will load if testing locally.
			var apiPath:String = paramObj.kongregate_api_path || "http://www.kongregate.com/flash/API_AS3_Local.swf";
			
			// Allow the API access to this SWF
			Security.allowDomain(apiPath);
			
			// Load the API
			var request:URLRequest = new URLRequest(apiPath);
			var loader:Loader = new Loader();
			loader.contentLoaderInfo.addEventListener(Event.COMPLETE, QuickKong.loadedAPI);
			loader.load(request);
			s.addChild(loader);
		}
		
		/**
		 * loadedAPI
		 * @description		Handles the loaded API, and extracts it
		 * @param			e: Event on load Completion
		 */
		private static function loadedAPI(e:Event):void
		{
			trace("[QuickKong] loadedAPI()");
			e.currentTarget.removeEventListener(Event.COMPLETE, QuickKong.loadedAPI);
			api = e.target.content;
			
			//preconnect callback. Use this for Shared Content API.
			if(connectCallback != null)
				connectCallback();
			
			//connect to Kongregate's API
			api.services.connect();
			
			chat = api.chat;
			services = api.services;
			stats = api.stats;
			mtx = api.mtx;
			sharedContent =  api.sharedContent;
			try	{ images = api.images; } catch (e:Error) { } //local cannot load images API
			
			//extract basic data.
			isGuest = services.isGuest();
			userName = services.getUsername();
			try	{ userId = services.getUserId(); } catch (e:Error) { } //local cannot load user id
			userToken = services.getGameAuthToken();
			
			trace("[QuickKong] Kong API Successfully loaded and extracted. Shadow Services alert should appear for local testing");
		}
	}
}


QuickKong Expanded

All the API vars have been extracted in QuickKong. You no longer have to access the kongregate variable as they have you do in the documentation before accessing stats, images, servicessharedContent, etc. Now its as easy as QuickKong.stats and QuickKong.services. A single variable access replaces the old double variable access.

 
Flag Post

QuickKong FAQ


What will the Ouput/Trace panel look like when testing locally?

The output panel should print out something like this:

[QuickKong] connectToKong()
Alert: Kongregate API shadow services loaded due to local testing. API will load when the game is uploaded.
[QuickKong] loadedAPI()
Kongregate API: IKongregateServices.connect() 
[QuickKong] Kong API Successfully loaded and extracted. Shadow Services alert should appear for local testing

However these events might not be grouped together as a trace might occur in between. When a score is submitted you should see the following trace:

Kongregate API: IStatServices.submitStat(Score,6761.260344646871)

Why is QuickKong.images null during local testing?

Due to Kongregate implementation the images part of the API is not available for local testing. To use any part of that API you will have to test online.



I can’t get QuickKong.sharedContent to work?


Did you remember to pass in a callback when you called QuickKong.connectToKong(stage, callback);? This callback will be called before the API is connected, allowing you to add load listeners. You can find some examples here


What is QuickKong.api?


QuickKong.api is comparable to the documentation’s example of the kongregate variable. If for some reason during the future the API is changed you will be able to access newly added properties through QuickKong.api. That means that QuickKong.api.services is the exact same as QuickKong.services


Games that use QuickKong


30 seconds to draw!
Speed Freak
Top Hat Ostrich in a UFO
Misfortune
Switch
Capitalism But In The Future

 
Flag Post

Looks pretty awesome. I’m gonna sticky this in hopes that it helps some people. :)

 
Flag Post

Just wanted to point out that you won’t want to use QuickKong as is if you plan on having Shared Content in your game, as you have to add the load listeners before you connect. This slightly modified version lets you pass a callback function that will be called at the appropriate time for you to addLoadListener from the appropriate place.

The new version has an optional parameter you can use.

 
Flag Post

Hmm. That could have been why my Shared Content game never worked. :)

However, the bug fix you did adds an extra layer of complication. ( The extended package I have uses callbacks like this, but I removed them for simplicity’s sake). So I’ll add an extra optional param in the original post like you suggested. Thanks.

Also added some information to the FAQ.

 
Flag Post

UG You are a hero. This was just the extra incentive I needed to get round to updating my latest game with the API. Thanks

 
Flag Post

Updated version to handle an error that I’ve never gotten when using this?

if(connectCallback)

//changed to 
if(connectCallback != null)

Because of

Function value used where type Boolean was expected. 
Possibly the parentheses () are missing after this function reference.
 
Flag Post

Fixed spelling error in license thanks to Ventero (skyboy should probably fix his too since I got it from him…)

 
Flag Post

You really saved me a bunch of time man. Thanks alot!

 
Flag Post

I am a complete novice to API’s, help me…

 
Flag Post
Originally posted by Godofpi:

I am a complete novice to API’s, help me…

If you are making games in AS3, just follow the simple instructions at the top of the page!

 
Flag Post

thank you very much for this api.

i wonder why kong does not make one like this them selfs, its a lot easier to start with then the documentations they wrote.

 
Flag Post

What is the format for distinguishing the 4 different types of statistics (max / min / add / replace)?
Would “QuickKong.stats.submit(”HighScore",highscore)" default to using max stats?
What is the format if I want to submit a min type stat such as lap times?

 
Flag Post

You don’t have to change any code to choose between max/min/add/replace. That is handled on Kong’s side with adding statistics, as seen in the picture below.

 
Flag Post

I used this in my game here http://www.kongregate.com/games/ST3ALTH15/speed-freak

 
Flag Post

I believe I missed something. FD is telling me :

(…)\QuickKong.as(130): col: 8 Error: Access of undefined property services in package api.
(…)\QuickKong.as(132): col: 15 Error: Access of undefined property chat in package api.
(…)\QuickKong.as(133): col: 19 Error: Access of undefined property services in package api.
(…)\QuickKong.as(134): col: 16 Error: Access of undefined property stats in package api.
(…)\QuickKong.as(135): col: 14 Error: Access of undefined property mtx in package api.
(…)\QuickKong.as(136): col: 25 Error: Access of undefined property sharedContent in package api.
(…)\QuickKong.as(137): col: 23 Error: Access of undefined property images in package api.

(with “api” beeing : public static var api:* = null;)

any advices ?

 
Flag Post

Can you post the code you use to initialize it? I’m going to guess that you are perhaps accessing the api before it loads or something. I’ve certainly never got this error but I’m very interested in it.

 
Flag Post

what if you use stencylworks

 
Flag Post

Im pretty new to this so forgive the noob question, but I am having problems connecting with QuickKong.connectToKong, I get an error saying QuickKong does not exist in the current context. How do I implement this?

 
Flag Post

@iLogiKBomB: Did you download it correctly? (e.g. save the file in the same folder as your project’s code). Can you post some code as well around where you put that line? That’s not a QuickKong problem, thankfully, but you did something wrong.

@Isaaconlinetwin: Nope, sorry. AS3 only.

 
Flag Post
Originally posted by Isaacsonlinetwin:

what if you use stencylworks

Stencylworks already has Kongregate tools built into it, so no need for QuickKong

 
Flag Post

I used this in my game here: http://www.kongregate.com/games/scrauler/test-cl

While playing on preview mode everything ok, but now I have published it, the game don’t show my username.

Test it and tell me if you can play or not please.

 
Flag Post

It shows my username and it even has a highscore tab, which means the API is working.

 
Flag Post

It is strange. Sometimes the game shows my username and sometimes don’t. If i refresh the webpage several times, I finally can see my username.Is a cache problem? I am going to look into this problem more time. Will this game show in the QuickKong games list?

 
Flag Post

Hey, I used QuickKong http://www.kongregate.com/games/Murdouken/capitalism-but-in-the-future-and-also-in-space here. Thanks for it, it was super useful.