Kongregate Statistics API
Accomplishments 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, accomplishments, 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.
All statistics must be non-negative integers. So, 0, 42, and 613341 are all fine, but -5 and 1.542 won't work. If you have a carefully timed game that records milliseconds, you'll want to multiple the time by 1000 when submitting to our server. So 1.542 seconds would need to be submitted as 1542 milliseconds.
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.
An accomplishment consists of one or more tasks, and a reward. The reward can be one of various things such as a card, badge, or points. As your game reports statistics, they are checked to see if they relate to an active task. Accomplishment progress will be automatically reported to both the game page and the chat application. Once all tasks for the accomplishment are completed, the reward is given to the player, and they are notified via chat. Accomplishments 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 challenges or badges in the future.
In order to have an accomplishment 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 statistics that need to go either up or down, such as a player ranking.
Creating your statistics
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/my-game/statistics This will take you to the statistics editor page, which can only be viewed by the owner of a game. Note: You can also view the statistics editor on the edit game page.
Give each statistic a name, description, and choose it’s type. You can also select statistics you wish to show up in the leaderboards by checking the "Display in Leaderboards" option.
Once you have created all your statistics on the server, it is time to integrate the API into your game.
You can use either the Client or Server API to submit statistics to the server: