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



Leaderboards (AKA High Scores) are a great way to add a competitive element to your game. Clay.io makes it incredibly easy to post, fetch and display high scores - with a variety of customization options to make it your own.

Creating a Leaderboard

To create a leaderboard you must first add it to the Clay.io database from the developers' area for your game here. Click "Leaderboards", then "Add a Leaderboard". Once it's added, note the ID it assigns that leaderboard.

Use the following code to instantiate a leaderboard class:

var leaderboard = new Clay.Leaderboard( { id: 1 } ); // The 1 signifies the leaderboard ID.

You can find the leaderboard ID in the developer panel after creating the leaderboard. If you would prefer to use something more memorable than a number to reference the leaderboard, you can set the "Unique Identifier" when creating your leaderboard, and use that { id: "something-unique" }.

Posting Scores

// Example score of 500
// Remember that we already instantiated leaderboard above
leaderboard.post( { score: 500 }, function( response ) {
    // Callback
    console.log( response );
} );

Click here for the format of our callback responses.

The score posting process will request a player to either login or enter their name to post their score. Alternatively, you can pass the name in the options object to bypass this.

// Remember that we already instantiated leaderboard above
var options = {
    score: 500,
    name: 'Some Name'
    // you can pass hideUI as well if you don't want the score posted notification to show
    // , hideUI: true
leaderboard.post( options, function( response ) {
    // Callback
    console.log( response );
} );

Displaying High Scores

To bring up the leaderboard, use:

// Remember that we already instantiated the leaderboard obj above
var options = { // all of these are optional
    html: "<strong>Hi</strong>", // Optional, any custom html you want to show below the name
    recent: 3600, // Optional, to limit scores to ones posted in last x seconds
    sort: 'asc', // Optional, sorting by "asc" will show the lowest scores first (ex. for fastest times)
    filter: ['day', 'month'], // Optional, Array of filters to narrow down high scores
    cumulative: false, // Optional, if set to true grabs the sum of all scores for each player
    best: false, // Optional, if set to true grabs the best score from each player
    limit: 10, // Optional, how many scores to show (0 for all). Default is 10
    self: false, // Optional, Boolean if set to true shows just the scores of the player viewing
    friends: false, // Optional, Boolean if set to true shows just the scores of the player viewing AND their Clay.io friends
    showPersonal: true // Optional, Boolean on if the player's stats (rank & high score) should show below the name. Default is false
var callback = function( response ) { // Optional
    console.log( response );
leaderboard.show( options, callback );

You can show multiple tabs of leaderboards. This will open the modal window the the current leaderboard, and tabs to any other leaderboards you specify.

var id = YOUR_LB_ID;
var leaderboard = new Clay.Leaderboard( { id: id } );
var arrayOfValues = [['row1-col1', 'row1-col2'], ['row2-col1', 'row2-col2']];
leaderboard.setTabs( { 
    tabs: [
        { title: 'Custom Tab', data: arrayOfValues, header: ['Col1 Header', 'Col2 Header'] },
        { id: ANOTHER_LB_ID }
} );
Recent Scores

If you only want to show scores from the past hour, you would use something like this:

leaderboard.show( { recent: 3600 } ); // where 3600 is # of seconds in 1 hour

To show links to filter the results by day, month, all time, etc, you specify the filter parameter with an array of filters. Each array item is either a string containing ('hour'|'day'|'week'|'month'|'all') or an object with some custom data: { title: "Filter title", recent: "integer # of seconds in the past", "...any other options you are able to specify for a leaderboard" }. Filters will show up as tabs if you don't currently have tabs set, or a select box if you do.

leaderboard.show( { filters: [
    {title: "30min, limit 10", recent: 1800, limit: 10 }
] } );
Limiting Scores

By default, the leaderboard will show the top 10 scores, to set another amount, use:

leaderboard.show( { limit: 20 } ); // shows 20 scores
leaderboard.show( { limit: 0 } ); // shows all scores

Fetching Scores

If you would rather not have the traditional Clay.io UI shown, you can fetch a JSON object of the scores using Leaderboard.fetch( options, callback ) and create your own table. All of the above filters & narrowing down results will work as well.

For example, to fetch the high scores from the past 2 hours, you would use:

// Once the results are found, this callback is called, and the results are the only argument
var myCallback = function( results )
    // Results is an array of objects
    // Each object contains an object of: 
    //    'name'
    //    'score'
    //    'me' (set to true if the score was posted by the current player)
    //    'user_id' (their Clay.io user id (integer), 0 if they aren't a member)
    console.log( results );
var leaderboard = new Clay.Leaderboard( { id: 1 } );
leaderboard.fetch( { recent: 7200 }, myCallback );

Full Documentation

Click here for the full documentation of leaderboards

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!