Leaderboards have long been a staple of many games, driving the competitive spirit while often, back in the day, forcing people to get creative with the limited three spaces they had to come up with a name that was both witty and inevitabely borderline inappropriate. A basic leaderboard is quite simple to create as the only info being stored typically is a user name and the score and doesn’t require complex management- ” Bob” could hold all the slots for the top 10 scores for example.

Typically, two server side calls are all that is needed to store and retrieve leaderboard information : one to get the top scores and names, and a second to save a score entry. In the past, I might have picked my favorite server side language (likely PHP just because it would have been quick and dirty ) , created a database, and then write a few services / logic to retrieve and save the data. Then I could have called that service from my HTML/JS application.

I’m going to show you how to take advantage of Azure Mobile Services using JavaScript to create a quick leaderboard api with a cloud backend, without needing to write any server side code. You can write your client side or application logic that will consume the services in almost anything your little heart desires including Objective-C or Java, but for this tutorial I am going to show you how to do this in JS.

Getting things up and running in Windows Azure

First things first, we need to head over to the Azure portal to get signed up if you do not already have an account. If you don’t have an account, you can sign up for a free month trial here. Once you have an account, go to https://manage.windowsazure.com to manage your Azure subscription. Once you are in you will see the Mobile Services option listed on the navigation on the left.

Step 1 - Click the Mobile Services button.

Once you have clicked the Mobile Services button, you will see a listing of any mobile services you might have already created. We want to start from scratch here, so go ahead and click the “NEW” button located on the bottom gray nav.

Step 2 : Click the “New” button on the bottom navigation, select Compute > Mobile Services > Create

Let’s give this Mobile Service a name. For this example, I am going to use “testleaderboard”, which means that the start of the REST API endpoint for this service will be https://testleaderboard.azure-mobile.net” . We will need to set the database that this Mobile Service will use. If you haven’t created a database yet, you can create a new database for it to use and select where the database should be located from the available locations. Remember to keep track of your database credientials. Otherwise, if you are like me and already have a database created, you can use that if you wish, as long as you know your administration credientials. Finally, we can choose a backend type with the two choices being JavaScript and .Net. I have chosen JavaScript – which means that if we ever needed to write any server side logic, we can do it in JavaScript.

Step 3: Name your Mobile Service and select your database.

After choosing a name and selecting a database, we will have to enter in the database credientials. Under the database dropdrop, you will have a few different options : use and existing one, create a new one or create a new database server. In my case, I already had a database created, so I will use that one.

Step 4: Select database and enter database admin credientials.

 

Once you have your database selected, your Mobile Service will be created. You should be able to see it in list with its creation progress being reported back to you. Once it is created, select it from the list. We now need to think about the data that we want to store and access.

Step 5 : Select the Data tab on the top horizontal navigation

 

We can create a table to store the data and add whatever columns we think we may need. For this example, I am going to create a table called ” highscore” and add in a few columns.

Step 6: Select Create a New Table

We need to name this table and set its permissions for the various CRUD operations. For this example, I am just going to allow insert, update, delete and read to happen with an application key. We will need to find the application key as we will need to use that with every api call that we make. Don’t worry about the application key quite yet, we’ll get to that in just a bit. Let’s add a few columns to the table first.

Step 7: Select the table and then select “Columns” from the top horizontal navigation.

 

To add a new column, select the “Add Column” button from the bottom navigation. I am adding two columns : one called “user_name” with data type of String, and another called “score” with data type of Number.

Step 8: Select “Add New Column” from the bottom navigation and add a column called “user_name” with data type string, and a second column called “score” with a data type of Number.

 

We now have a table called “highscore” for our Mobile Service and we added two columns called “user_name” and “score” to the already existing columns in the table. Now we need to only do a few more things before we can start using this service. First, let’s go get our application key.

Step 9 : Select “Manage Keys” from the bottom navigation

We will need to record the application key. Copy the top application key.

Step 8: Copy the Application Key and Record for later use

 

Now that we have our application key, we just need to take a look at cross-origin resource sharing – and adding in any host names to the list of accepted domains. By default, localhost is already added, but if you have a special mapping you want to add, you can do that now. To add a domain, select the Mobile Service from the left ( you might have to click the back button in the top left here to get to it ) and then select “Configure” from the top horizontal navigation.

Step 10: Add your domain to the list

Now to the Code

We now have a basic leaderboard api set up and ready to use. We can insert entries that have a user name and a score associated with them, or we can retrieve what is in the database.

I have written a simple example that is in Github that shows you both how to use the SDK or just the REST API to access and save data. Let’s focus on using the SDK first. You can, of course, get a sample application or code for most of the languages you may want to use to consume a Mobile Service ( objective-c, java, html/js etc ), but I just bypassed the sample application to get right into the code.

Step 11: Include the JS SDK by adding it to the HTML page via a script tag

There is an sdk you can use and it does most of the hard work for you. To use the SDK, you need to include this line:

<script src=”http://ajax.aspnetcdn.com/ajax/mobileservices/MobileServices.Web-1.1.3.min.js”></script>

Once you have included that js, we can start using the SDK. Now note, if you are going to use this in your web-based game, including the script as above is fine. If you are using this and planning to build a Windows 8 or Windows Phone app, you will want to download that file and load it locally to avoid security restrictions. From the main.js file in my github example, you can see how to need to instantiate and configure the sdk with both the endpoint to our service , and the application key. The endpoint to the service will something like “https://your_service_name.azure-mobile.net/” and the application key will be what you recorded previously.

Step 11: Configure SDK with Mobile Service Endpoint and Application Key

 

Once we have instantiated the SDK and configured it, we can use it to make service calls. As making a service call is a synchronous process, the SDK returns a promise object so that you can handle all stages and results of that process, including errors and when its done.

Step 12: Get the top 10 entries in the leaderboard and order by the score

To get data from the service, you need to tell the client which table to use first :client.getTable(‘highscore”). We can tell the client to order by descending using the field “score” as we want the top score at the top, and then we then can tell it only to take 10 records from this query. When the process is done, we can then handle the results anyway we want : in this case, I just added them to an unordered list.

Step 13: Save an entry and handle the response

To save an entry, we again need to tell the client which table to select ( client.getTable(‘highscore’) ) and then we tell it to insert a data object with those columns set. If this operation runs succesfully, we again poll to get the latest top entries and display that to refresh what is happening on the view.

You can also use the Mobile Services like a REST API, which I have also included in github example. It does require you to set a few headers, alter the end point since the SDK was handling some of that logic for you, and format things in a specific way. Feel free to check out the example, where I used a basic jQuery $.ajax call to show you how to get and save data.

Now, if you needed to create a more complex api, you can take a look at the Custom API option for Mobile Services, where you can customize your calls and server side logic if needed. Straightfoward api needs like a basic leaderboard, however, can be quickly created this way without having to write a lick of server side code.