[Kongregate API] AS2 Integration (locked)

212 posts

Flag Post

Note: The following information is out of date. Please refer to our new API Documentation here: http://www.kongregate.com/developer_center/docs/kongregate-api

This was previously knows as the Statistics/Challenges API, but is now the exclusive API that should be used for AS2.

This is a simple guide on how to integrate our statistics/challenges API into a flash game. Unfortunately, we do not yet support Shockwave games.


Challenges on Kongregate are made up of one or more tasks, which are based on a single statistic each. As a developer, the only thing you have to worry about is statistics, we take care of the rest. Statistics, tasks, challenges, and their relationship will be explained below:


Statistics track events that happen over the course of your game. They can represent just about anything, be it high scores, number of monsters killed, coins collected, etc. The statistics API allows you to submit numbers to the server and have it keep track of statistical data for players on Kongregate. The philosophy is that whenever an event occurs in your game that you want to keep a record of, you simply submit it to the server. We are planning to have a statistics page for players where they can view these online, possibly with graphs to check progress over time.


A task relates a statistic with a quota. For example, if you had a “High Score” statistic for your game, a task may be to get a score of at least 100,000. Once the player reaches this score, the server would mark this task as complete. Tasks for your game will be defined by Kongregate, but suggestions are encouraged.


A challenge consists of one or more tasks, and a reward. As your game reports statistics, they are checked to see if they relate to an active challenge task. Challenge progress will be automatically reported to both the game page and the chat application. Once all tasks for the challenge are completed, the reward is given to the player, and they are notified via chat. Challenges are set up by Kongregate, and are based on the statistics you have defined for your game. If you are tracking lots of statistics, it is possible that we may use your game for multiple challenges in the future.


In order to have a challenge run on your game, it must send statistics to our servers during play. First, take some time to think about which statistics it makes sense to report. For a game like Fancy Pants, these would be things like “Total spiders killed”, “Total squiggles collected”, “KiT Trophy Found”, etc. You also need to think about the type of each of your statistics. Our system supports 4 different types of statistics:

  • Max – The value on the server will be replaced if the new value is higher, for example a high score.
  • Min – The value on the server will be replaced if the new value is lower, for example the lowest time for completing a lap.
  • Add – The new value will be added to the value stored on the server, for example total number of coins collected. This can be used for statistics which are cumulative.
  • Replace – The new value will always overwrite the value on the server, this can be useful for boolean flags such as “Found key in level 1”

After you come up with your list of statistics, you need to set them up on the server. This can be done by adding /statistics onto the URL for your game in your browser window. For example: http://www.kongregate.com/games/BenV/x/statistics This will take you to the statistics editor page, which can only be viewed by the owner of a game. Give each statistic a name, description, and choose it’s type. Once you have created all your statistics on the server, it is time to integrate the API into your flash game.

First, you will need to add a line of code that will cause your game to connect to our servers. It should be placed as early in the timeline as possible, usually on the first frame. You may copy and paste this code into your FLA or ActionScript:


After that, you can start submitting statistics! The submit function takes 2 parameters, the name of the statistic, which should exactly match the name you put into the statistics editor earlier, and the value for the statistic. Here are some examples of how to submit statistics:

_root.kongregateStats.submit(“Coins”,1); // The user collected a coin
_root.kongregateStats.submit(“MonstersKilled”,1); //The user killed a monster
_root.kongregateStats.submit(“HighScore”,398); //The user got a score of 398
_root.kongregateStats.submit(“LapTime”,60); //User finished a lap in 60 seconds

That’s it! At this point you can re-upload your game and it should be reporting statistics. Feel free to post any questions in this thread!

Supplemental tips from Greg, the badge/challenge maker!

Hey guys, I’m not a fancy, big-city programmer like Ben here, but I do make all the badges and challenges, which means I spend a lot of time dealing with the statistics that developers choose to report. Here are some general tips I have that you can follow to make my life easier, and to reduce the chances that I’ll whine to you over email and ask you to change something.

1. Please add a “max” stat that’s something like “GameComplete 1” for when your game is finished. This is a no-brainer stat that allows me to add a badge for simply completing your game.

2. The “add” type of stat is primarily a novelty. It has lots of problems when used for most badges. If you have an “add” stat for kills across games, users can simply play the game repeatedly to get ridiculously high scores. Even if you only add stats for unique completions in the game, users can simply wipe their save file in most cases. Anything that uses the “add” stat will ONLY be considered for “easy” badges. (It doesn’t hurt to add a few of these in, though, even if they won’t be used for badges — it can be sort of interesting to load up the high scores and see how many times a user has done something.)

An example of how this stat can mess things up: Mezzo Winter Edition used to report an “add” stat for completing levels that the user had not yet completed. I set up a badge requiring that “levelscompleted = 30” (30 was the total number of levels, and a “1” was sent each time a new level was completed). Unfortunately, all that was required was a single connection blip on a single level to make the badge impossible to earn. Unless, of course, the users wiped their saved data, in which case they could simply beat the same level 30 times to unlock the badge. The solution here was to simply report a “GameComplete 1” stat when level 30 was completed.

Even in games like Amberial, the “add” stat for collecting all 15 aces is NOT optimal because, again, users can exploit the system by erasing their saved data, or they can be completely screwed over if there’s a connection failure at the time of collecting any of the 15 aces (not only will they not get the badge, but they won’t be ABLE to get the badge unless they erase their data, since now that ace has already been collected, but Kongregate doesn’t know it!). The best thing to do here is to continually report to us how many aces the user CURRENTLY has. That way, even if there’s a connection failure, the user can simply come back later (or wait for the problem to clear up) in order to claim the badge. (This is what the developer does and always has done; I’m just using it as an example of how it COULD have gone horribly wrong if the “add” stat was used.)

3. Please connect in the first frame. As seen in the Johnny Rocketfingers games, it IS possible to connect at the same time that a statistic is reported, late in the game. However, this can be confusing to the user (since the light in chat will be red, even when it’s working properly), and it’s also a pain for me to test, since I have to personally beat the entire game just to see if the game is able to connect to us at all.

4. Report stats often. Or at least more than just once! Sometimes developers will include all sorts of great statistics in their games, but they’ll only report them once the game is actually completed. This makes it impossible for me to make any badge other than “finish the game,” regardless of what kind of other fun stuff is reported. Feel free to report everything at the title screen, too! That way, if I make a badge after someone has already completed the task, that person will only need to load up the game to be awarded the badge (this only works with games that use some kind of save system, obviously).

5. Separate difficulties! If your contains multiple difficulty settings, please report them separately, such as “PointsOnEasy 34907” or “GameCompletedHard 1.” If you don’t, I have to assume that the user is simply going to set the game on the easiest setting possible in order to achieve the badge, which really limits my options.

6. You must report a number. You can’t simply report the English names of areas to us that the player has completed. Obviously the statistics need to have names, but they also need to have a number associated with them, even if that number is just “1” when the area is completed.

7. I cannot do “or” conditions. When I make badges and include multiple tasks, I can only require that users complete ALL of the tasks, not just one of them. So if your game has multiple endings and you send us either a “GameEnding1 1” or “GameEnding2 1” for completion conditions, I CANNOT make a badge that is something like “complete the game with either ending.” For this, you should send something like “GameCompleteEither 1” that is sent if EITHER ending is completed. You can do additional stats that are more specific if you’d like, but please try to include general ones as well!

An example of this can be seen in the game “Fold.” The developer, Joel, is reporting a general stat for if the player completes a stage with lives remaining OR in ghost mode (ghost mode occurs if all lives have been lost, and the player continues). This is in addition to 2 other stats, which are specific to whether the player has lives remaining or if the player is in ghost mode. If Joel weren’t reporting the general stat that includes both conditions, it would be impossible for me to allow ghost mode at all, since players with lives remaining would need to commit suicide in order to complete the achievement (in other words, if I set the conditions to allow ghost mode, it would REQUIRE ghost mode). If you want an “or” condition in your statistics, you need to be the one to set it up!

8. Double-check for in-game exploits. Can your game be completed by doing the ol’ fashioned “right click: play/forward”? Can your mouse avoider game be exploited by disabling the cursor or warping it through obstacles by right-clicking? Can ridiculously high scores be achieved by doing some repetitive task for 30 minutes on the first level? Can in-game unlockables make achieving a certain task ridiculously easy? If so, please clean it up, or report the stat in such a way that makes the exploit impossible to use.

For example, “Streamline” used to have a bug in which highlighting the number of lives in the lower-left corner made the player invincible. The developer addressed this issue by causing immediate death if the player clicks anywhere on the screen (this is why clicking causes death in the Kongregate version, but not in versions on other websites).

In “Gravitee,” the final unlockable shows the player the perfect path to a hole-in-one on every course. This would trivialize the impossible badge, in which players must score really well on each hole. To address this, the developer simply doesn’t report the completion of a platinum medal (required for the impossible badge) if the player makes use of the hole-in-one displayer.

Flag Post

Awesome! :D Thanks for posting this. Now I can imagine making my next game with lots of cool statistics!

Flag Post

Judging by the code, this means that there is a standard Kongregate swf, that loads the swf that we load? Thus we need to call _root?

I will think about how this will apply to flash 9… Thanks

Flag Post

Flash 9 is not currently supported by our APIs, but should be sometime in the near future (hopefully!).

You are correct, the API is automatically loaded onto your movie’s _root timeline when the game loads. We did this so that developers wouldn’t have to download any sort of package or component to enable this functionality.

Flag Post

i asked greg about high score things and thought about something else.

greg said that it could be possible that in the next features, you could know the Highest Score ever (by Kong users) just like i do now with my own database.

Could it be possible even if the game is not on a Kong page (on a page where u can’t do _root.kongregateServices.connect();) ?

Flag Post

With the current high scores API, you have to be on the Kongregate website, so that it knows your Kongregate username, etc. We are still discussing whether or not we want to make a general/public high scores system. The advantage of scores being tied to your Kong username is that people don’t just get to type in whatever they want, so statistics are more meaningful.

It is very possible that you will be able to retrieve the high scores list while not on Kongregate, but not submit.

Flag Post

After you come up with your list of statistics, you need to set them up on the server. This can be done by adding /statistics onto the URL for your game. For example: http://www.kongregate.com/games/BenV/x/statistics Give each statistic a name, description, and choose it’s type. Once you have created all your statistics on the server, it is time to integrate the API into your flash game.

How do you accomplish this step?

Flag Post

Which step, indie? Adding the statistics? Or integrating the Flash API? It seems like they are both described in the post. Note that you don’t have to download anything or paste any of our AS into your movie – just the connect() call and then the submit() calls in the right places.

Flag Post

If I get it right, statistics are differents from highscores, depite I can create a statistics called “Score”.
But is there a highscore API that can be used ?

By the way, congratulations for this system, very clever!

Flag Post

Each game has a HighScore statistic built in, which will be future-compatible with our High Scores API. If you use this statistics to store High Scores for a player, you should be fine.

Flag Post

OK thx, definitely smart system.

Are there exemple of game showing higscores on kongregate ?

Flag Post

When do we get the ability to look up existing statistics? That would open up possibilities for saved games and maybe more interesting stuff. Or maybe you want to separate those two areas.

Flag Post

We will be adding other APIs for saved games, etc in the near future.

Flag Post

how about adding an API for outside sides to connect and do something with kongregate..not sure what exactly, but maybe display scores or something.

Flag Post

Why would you want to connect to Kongregate from a game on a different site?

Also, that makes security issues and hacking more difficult to deal with.

Flag Post

Jim: Well, I understand the ActionScript part, but when it asked me to create a folder on Kong’s server I got confused. I guess I’m not getting the part about adding /statistics to the URL of your game: How do I create folders on your server?

But, I do of course understand how the game is loaded into a container (_root level) .swf with all of the Kong API functions in it.

Flag Post

Ah! You don’t have to create a folder. He just means that to edit the statistics on your game, just go to the regular game page, and then add /statistics to the end of the URL. So for Q-Zoid it would be:


Flag Post

Oops. I guess I was overthinking it. Thanks.

Flag Post

Updated to address some of the issues we ran into with the gamma bros challenge, as well as some of the questions in this thread.

Flag Post

I just set up Kong Ball with the high score stat, but how do I view the high scores of everyone? The statistics page has the HighScore statistic and the information of when it was made, but there are no scores to be seen, and I know there should at least be one. Is there a link I’m looking over?

Flag Post

Dingo, we have not yet implemented the pages for viewing high scores, although we want to do this shortly. What you have done is enabled us to run a challenge on Kong Ball in the future based on high score. We will also provide an API for retrieving high scores in-game.

Flag Post

Ben, what about implementing this for a game that hasn’t been uploaded yet? Can you just switch the order and set up the stats after you’ve uploaded it, since the statistic page for your game won’t exist until then?

Flag Post


Flag Post

Dingo – When I took a look at Kong-ball, I noticed a problem, you appear to be calling connect() repeatedly (maybe every frame?) This function should only be called once over the lifetime of the game.

Flag Post

Ben- Yeah, I fixed the connect problem. I put the code in the first frame, not even thinking it was the preloader and was looping until play :S