![Subscribe to [Kongregate API] AS2 Integration](http://cdn2.kongregate.com/images/feed-icon.png?1295399767){kind=icon}
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.
OVERVIEW
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
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.
TASKS
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.
CHALLENGES
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.
IMPLEMENTATION
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:
_root.kongregateServices.connect();
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.
