Warning: This version (v1) of the API will be deprecated on May 1st 2015


When designing our Analytics API the goal was to make a tool that was simple, and easily expandable. Its simplicity lies in the fact that if you include the Clay.io script, we'll automatically start tracking some important statistics.

Even if the only thing you do is insert the Clay.io script code, we'll track your daily plays (views) for the game.

The more you choose to integrate the rest of our API, the more use you'll get out of our Analytics module. We track most other API features -- any time an achievement is earned, a screenshot is taken, or a post is made to Facebook, a stat is logged (and for many more API interactions).

To access your statistics, click the "View Stats" link for the game you wish to view on the Developers Page. You'll see a page like the image below detailing the stats for your game.

All statistics are tracked on a per-site basis - this means you can see where your game is being played. You are even able to "normalize" one metric by another. Selecting "Achievements" as the primariy statistic, and "Views" as the normalizing metric will generate a graph of "Number of Achievements per View", categorized by each source your game was played from.

Statistics that show up as "Other" are direct visits to your game - visits without a referrer.

Key-Value Statistics

If you would like to specify your own custom statistic to log, say, number of times someone talks to a certain NPC in your game, you can do so with the following:

// Where name is an identifier for this stat
Clay.Stats.logStat( { name: 'talkedToNPC', quantity: 1 } );

Level-Based Statistics

This primarily applies to games with distinct levels - it can be used in a game without levels, but works best in a level-based game. By notifying Clay.io when a level begins and ends (and whether or not it was a success), we output the dropouts, time spent, and attempts for each level.

// Start a level
Clay.Stats.level( { action: 'start', level: 'levelName' } );

// Level Failure
Clay.Stats.level( { action: 'fail', level: 'levelName' } );

// Level Success
Clay.Stats.level( { action: 'pass', level: 'levelName' } );

Dropouts will help you determine which levels need to be improved, whether that's making them easier or more fun. If a player plays levels 1, 2, 3 and 4 - but never finishes 5, that's considered a dropout for level 5.

Time spent returns the average amount of time spent by players on each level. Depending on the type of game, too much time spent on one level could be a good or bad thing.

Attempts is how many total attempts have been made on each level. With this metric, you are able to determine which levels may be a bit too difficult.

Provide Feedback

We take customer support, and the quality of our developer tools and documentation very seriously. We want to hear how you think we can improve our documentation! Let us know if anything is missing, or unclear on this documentation page, and we'll get that fixed!