Clay.io is a hub for HTML5 games that provides both a marketplace and API. This guide will explain how to integrate features like high scores and achievements into your game.
For the purposes of this tutorial, I will be using the demo game, "Space Blaster".
Signing Up
The first step towards using the Clay.io API is to signup for Clay.io and create a game key to work with.
You can signup for Clay.io here: http://clay.io/join
Once that's completed, head over to the developers' page and click "Upgrade Account to Developer".
You'll be asked to specify your developer name (For example: "Vigil Games"), Unique Key/URL Location (your developer page will be accessible at clay.io/developer/TheKeyYouMake), URL (if you have a website) and Bio (a short description about your, or your game studio).
Next up, you have to add your game (you don't have to upload the files just yet, but we need a record of your game). You can do that here.
Subdomain is where your game will be located on Clay.io (if you pick "mygame", you'll be able to access it from http://mygame.clay.io)
Price leave this at 0.00 unless you plan on charging for your game, if so, set the price you wish to charge
Zip File skip this for now - this is for completed games that are being uploaded, since we're implementing the API first, there is no need to do that yet.
Now you're ready to get started
Installing the plugin
You can download the Clay.io Construct 2 plugin here (you'll also find further documentation on that page)
Once downloaded, extract the zip file, and copy the "clay" folder into your Construct 2 install plugin folder (often: C:\Program Files\Construct 2\exporters\html5\plugins)
Next, open up your Construct 2 project, right click inside the layout tab, and "Insert new object". Clay.io will show up as an option in the "Web" section.
In the properties panel, put in the API key (what you entered for the subdomain earlier, this is also accessible from the settings for your game).
Having debug mode means any achievements you earn will not show up in the Clay.io feed, and high scores aren't posted to the live data for your leaderboard. Just be sure to disable this when you publish your game if you choose to enable it during development.
Leaderboards
The first step in adding high scores to your game is to go to the developers' page, click "Leaderboards" then click "Add a Leaderboard".
You'll see something like this:
The Name field will show in the header of the leaderboard in your game like so:
The Type field has two options: "Default" and "Incrementing". Default is your typical high score system where a user can have, for example, 7 different high scores posted (since they played 7 times) - each is individual. With incrementing, each time a new score is posted, it is added to that player's previous score. An example of when this can be used is to get a cumulative number of wins.
Once you hit the "Add Leaderboard" button, you'll see a success message like: "Your leaderboard was successfully added with ID: 26" (with a different number than 26 - you'll need this ID in the next step).
Next, in your Construct 2 project under "Events", attach the following action to whichever event condition you would like to post a high score following (in Space Blaster, this happens when the player's health hits 0, and the game is over). Select the action: "Clayio -> Post Leaderboard Score).
Player Name can be left blank. If it's blank Clay.io will ask the user for their name (or if they're logged into Clay.io, it will use that account). If you specify a name variable, Clay.io will use that instead to associate the score with.
Player Score is going to be the variable/expression that the score is stored in. In the case of Space Blaster, that's "score".
Leaderboard ID is what was returned in the above step - for this game, it was 26.
That's all it takes to get high scores to point, but now we'll want to show the leaderboard. For some games it makes sense to show the leaderboard after every score is posted, for others, you might want to bind it to a key press. For this tutorial, we're going to have it show each time a score is posted.
Create a new event with the condition "Clayio -> Leaderboard Score Posted". Next, add an action to that event: "Clayio -> Show Leaderboard"
Leaderboard ID again is what was shown after adding your leaderboard on Clay.io (26 for this game, yours will be different)
Time Frame lets you narrow down how far back you would like to grab results from/ You can show the high scores from the past 30 days, 7 days, and 24 hours (as well as all-time).
High Score can be individual or cumulative. If it's cumulative, and a user has posted 3 high scores: 15, 25 and 11 -- 1 listing of 51 will show for them rather than the 3 separate scores.
Scores From lets you narrow down who to display the high scores from. You can have it select from 1) Everyone who has played the game, 2) Just the person viewing, or 3) Just the friends of the person viewing (they'll need to be logged into Clay.io so we can tell who their friends are).
That's it! Your leaderboard is setup and good to go.
Achievements
For this example, we're going to award an achievement for the first time a player kills an enemy in Space Blaster.
First up, you'll need to create the achievement in the Clay.io Developers' Area. Click "Achievements" for your game, then "Add an Achievement".
For reference, the achievement will show up like this:
Title will show up in the achievement header
Description will show up in the achievement content area
Clay.io bronze points are similar to Xbox Live GamerScore - they're a measure of credibility a player on Clay.io has. You can give out up to 100 points per game
Icon is an optional 50x50 icon you can upload that will show up to the left of the description when an achievement is awarded.
Once you hit "Add Achievement", you will be given a success message with the newly created achievement's ID. You'll need this for the next step (in this case it's 125).
In your Construct 2 project, find a condition when you'd like to award an achievement. For this tutorial, that's when an enemy dies.
For the action, select "Clayio -> "Award Achievement".
Achievement ID is what we got after adding the achievement on Clay.io (125 in this case)
That's it! When an enemy dies, players will be awarded an achievement.
Screenshots
Construct 2 already lets you take screenshots, but once the screenshot is taken, you can't post to Facebook, or have a link to the screenshot. The Clay.io plugin will upload screenshots your players take to our server, and give you a link to use.
To achieve this, first tie the "System -> Snapshot canvas" action to an event (for this tutorial, I used the the "S" keydown for the condition)
Next, create an event with the condition of: "System -> On Canvas Snapshot", and the action: "Clayio -> Post Screenshot to Clay.io".
It will ask you for a "Screenshot Data URL" - use the expressions window, and select "System -> CanvasSnapshot"
Once you hit done, you're good to go - the screenshot will be posted to a player's Clay.io account (if they're logged in, otherwise it will ask them to login). Details on posting to Facebook are at the end of this tutorial.
Posting to Facebook and Twitter
The processes for posting to Facebook, Twitter and the Clay.io stream are all virtually identical, so to refrain from being repetitive, I will just explain posting to Facebook.
Create an event with whatever condition you'd like to start the posting process (for this tutorial I chose the "F" keydown).
Next, set the action to "Clayio -> Post to Facebook Wall".
Message is the content of the post that will be made to Facebook
Link is an optional URL you specify that will show up with the Facebook post
Picture is an optional image URL you specify that will be associated with the post
Screenshots Posted to Facebook
To tie together the previous two features listed, let's have screenshots be posted to Facebook.
First, follow the steps under the "Screenshots" section above. Once that's done, create another event with the condition: "Clayio -> Screenshot Posted". Now set the action to: "Clayio -> Post to Facebook Wall".
This time, we'll do exactly what we did last time, only, we'll use the expression: "Clayio -> ScreenshotSrc" in the Picture field.
Voila, we're done!
For an example of a game using the API, see Word Wars.
This tutorial doesn't cover everything the plugin does, so be sure to read over the official documentation.