Thursday, 17 March 2016

GameSparks micro-tutorial: leaderboards and analytics for Unity games

GameSparks is an attractive BaaS (back-end-as-a-service) option. Their docs are a bit stuffy though, so I created this quick-start document and a convenient wrapper so you can get started with 4-5 lines of code.
GameSparks provide a variety of back end services including cloud storage, cloud code... The basic integration exposed here illustrates authentication, leaderboards and analytics.

The integration and sample code are designed to work with Unity 3D.


I take you through the steps for a simple setup using anonymous authentication.
"Anonymous" means that the device ID will be sent to the back-end service instead of a user name and password).
  1. Register and create a game on their portal; fetch the API key and secret under configurator > overview
  2. Download the GameSparks Unity SDK (it's a package, like in the Asset Store)
  3. Import the package (warning: moving the GameSparks folder could break something)
  4. Also import JSONObject from the Unity Asset Store, this is needed to parse some of their responses.
  5. Notice the added GameSparks menu. Now, enter your API key and secret via GameSparks > Edit Settings.
  6. Create an empty game object, you might call it GameSparksManager.
  7. Add the GameSparksUnity script to the manager. This is part of the downloaded SDK
  8. Add my quick integration script
  9. Press play!
This is how the inspector for GameSparksManager will look like:

If you've done everything correctly you should see console messages indicating a successful login. You are now ready to do the following:
  • Fetch and submit scores
  • Display leaderboards
  • Submit analytics requests.
Leaderboards and scores

For this I will defer to their lengthy introduction here but you can pretty much skip anything related to Unity and use my sample integration to get you started.

If you use HIGH_SCORE as leaderboard id (GameSparks refer to ids as "short codes") and SCORE as attribute and SUBMIT_SCORE as log event short code, you can leave the above fields (in GameSparksManager inspector, see picture) as is.

The utility I wrote, GameSparksApi, provides the following functions:

  • SubmitScore(int) to send a score to the server.
  • SubmitDisplayName(string) to submit the user's nickname displayed in leaderboards.
  • FetchPlayerRankAndScore() to fetch the rank and score; this will be assigned to playerRank and playerScore so you can have a text component display this (it will take a while to update after you call the request).
  • FetchLeaderboard()
    to likewise get an updated leaderboard with a formatted result available (after a while) in formattedLeaderboard

Customise the source if you're not happy with leaderboards format or want to handle callbacks yourself.


So called analytics requests allow you to log user actions. A typical use of this is finding how far players got into your game: Did they complete the tutorial? Did the game even load correctly? Can they go past level 1... ? And so forth.

This doesn't require back-end setup, just call the Analytics(string) function on GameSparksApi. The string indicates what user action you're logging.

Results are displayed (in your admin screens on the GameSparks website) under Configurator > Analytics > Custom

Caveat: Analytics update appear to take one hour or more to go live in admin screens.

No comments:

Post a Comment