Statistics & High Scores

Sending Statistics

Any event in your game can be submitted to Kongregate as a score. This allows you to use Kongregate's leaderboards, and if the game qualifies we can use those stats to make put achievements on the game. In general, we recommend having 3 - 5 statistics in your game to track.

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 multiply the time by 1000 when submitting to our server. So 1.542 seconds would need to be submitted as 1542 milliseconds.

🚧

Gotcha Alert

The maximum value of a stat is BIG_INT (9.223 x 10¹⁸). If you have a game with ludicrously-large numbers (cough idle games cough), we recommend taking a log of your number (and then perhaps multiply by 1000) to make them work with scoreboards.

Statistics should generally be submitted to the system at the time that they change (like leveling up) or a fairly frequent checkpoints (level/battle completed). Additionally, major stats should be submitted once on each session start. This way if there is an error or glitch during something like a level up a player can refresh the page to force the stat to resubmit.

Types

• Max: The value on the server will be replaced if the new value is higher, for example a high score, battles won, user level, etc.
• 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. That said, it is more susceptible to error due to connection problems and failed submissions, so we recommend this only if the game or your server doesn't track stats that can be submitted as "max" or "min" stats.
• 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.

In most cases, the best choices for stats to submit are progress-based stats. Things like player level, quests completed, towns captured, matches won, high score on a level, units collected, fastest time on a track, etc. that increase as the player continues in the game. Submit these as numerical stats (i.e. send us the level, not just a "1" when the player hits level 20) and we'll have the most flexibility when working to design badges for your game.

Initialized Statistic

For social/MMO games, and games with high system requirements or large downloads, we recommend submitting a stat to us called "initialized" or "loaded" that sends a "1" each time the game loads successfully. This must be done very early, generally at the title screen or no later than character selection/creation (if that happens first thing) - it cannot be post-tutorial or after the first level. We can use this stat to ensure that ratings for the game are by people who meet the game's minimum system requirements, which will help give you a more accurate rating. Let us know if you have set up a statistic like this so we can set it up as a filter. This service is currently only available for virtual-goods-enabled games.

📘

Note

As this may modify the game's rating, any games using this service will be excluded from the monthly contests.

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: www.kongregate.com/games/my-username/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.

Submitting statistics

You can use either the Client or Server API to submit statistics to the server:

• Statistics Client API
• Statistics Server API

Retrieving statistics

• High Scores Server API

Testing statistic submissions

You can see statistic submissions go through in a Javascript console (Chrome, Firebug, etc.) if you add ?debug_level=4 to the game's URL. The exact syntax changes depending on whether you're using client or server stats, but you should see them submit either way.

Some helpful integration tips from Greg (creator of badges)

Here are some general tips you can follow to reduce the chances that I’ll whine to you over email about changing something.

1. Please add a “max” stat that’s something like “GameComplete 1” that submits when your game is completed.

This is a no-brainer stat that allows me to add a badge for simply completing your game. The stats API is the same as our high scores API, but not everything has to be a "high score" -- you can simply submit binary conditions for whether or not something has been accomplished.

2. Connect to our servers as soon as the game is loaded.

If you do not connect to our servers, you cannot send any data! It's a very common mistake for developers to skip this crucial first step.

3. RESUBMIT ALL DATA RETROACTIVELY ON GAME LOAD!!

This point cannot be emphasized enough! You need to submit all data to us twice: first, when the specific event actually occurs, and then again when the game is reloaded.

This is because if players have already completed the badge task before the badge is created, or they complete the required task during a connection blip, then we will have no way of awarding the badge. Just keep resubmitting old data to us! Don't worry about our servers -- they can handle it! If there is a technical reason why you cannot resubmit old data on game load, you can instead resubmit this data at some other infinitely recurring interval (eg, completing a level again, accessing a menu screen, dying, etc.).