Game Analytics 101

bchong

This is a post by Ben Chong, an aspiring iOS game developer living in Indiana.

Learn how to add analytics into your Cocos2D games!

Learn how to add analytics into your Cocos2D games!

Hi folks! In this tutorial, I’m going to show you how you can easily integrate analytics into your Cocos2D games. By the end of this post, you’ll know how to use analytics to see and understand how players are interacting with your games, in real-time!

Please note that this tutorial begins where the How To Make A Simple iPhone Game with Cocos2D tutorial series left off. I highly recommend that you complete this tutorial series first, or have equivalent knowledge.

If you haven’t been through that series yet, which showed you how to make a game about turrets and ninjas shooting monsters, here are some handy links to Part 1, Part 2, and Part 3.

I love making games, and every day I’m learning something new about Cocos2D. It’s amazing to see the games that people have made with Cocos2D, and in this tutorial I aim help you guys make even better ones – through the power of analytics!

Let’s get started!

Getting Started: Introducing Analytics

Analytics say: this is probably too hard!

Analytics say: this is probably too hard!

Long before the era of the iPhone and iPad, we played very simple games. Remember Prince of Persia, Contra and Super Mario on the console?

Those were the “good old days,” when developers wrote game programs on really old machines, and let their friends test them before release. If the game was terrible, there was no turning back for developers. They wouldn’t know until it was too late, and by that time they had to close shop.

Fast forward to 2011. The game design landscape has changed radically. Because iOS devices are so inseparable from the Internet, it’s possible to gather data about player behavior WHILE they are playing our games, and issue updates on the fly.

As an aspiring iOS developer, you could, for example, release a game to a small amount of users, test their responses, then use that data to improve your game.

Hmm… interesting. But why should you care? There are many reasons. Here are a few:

  • If you know where your players are getting stuck, you can change the difficulty so more players can continue playing.
  • If you know where players die too easily, you can redesign the level to prevent that from happening.
  • If you know that some game items are too expensive, you can change the prices so more players can afford them.

As you can see, it’s all a matter of “knowing” how players are interacting with your game, and responding accordingly.

The buzz word for all this is “analytics.”

Game Analytics & How it Works

Game analytics is simply the use of data generated by players to better understand players’ behavior in the context of a game, allowing calculated improvements to be made to the game.

We use the term metric to describe what is being tracked. A metric could be anything: a button being clicked, a level completion trigger being fired, or a 2d coordinate point where a player gets killed.

The image below is a simple representation of how game analytics typically works these days.

Relationship between our Cocos2D game, the analytics server and its client

By now your head is probably spinning, filled with questions like:

  • How do I even “get” the data from my players?
  • Do I have to build my own system?
  • What if the player goes offline?
  • Where do I even start?

Fear not, we’re living in one of the best periods in human history. We have all the resources we need to start. The last I recounted, there are a handful of analytics services out there (Flurry, GamesAnalytics, Playtomic, and others). All of them are free to sign up and use.

For this tutorial, we are going with Playtomic, because i’ve been using it for 3 months already and i’m most comfortable with it. In interest of full disclosure, I am also a developer’s advocate at Playtomic. Feel free to try out others and share your experiences in the comments section.

Initializing the Components

First off, download the source code for the rotating turret game.

Set up the project to the point where you can run the game. If you don’t know how to do this, refer to Part 1, Part 2 and Part 3 of the original tutorial series.

Now let’s set up the analytics client. Sign up with Playtomic for free. In the Playtomic dashboard, click “Add New Game.”

How to add a game

Give your game a name (any will do), choose iOS/Objective C for the API, and choose iPhone/iPod for the Platform.

Choosing a name, API and Platform

Choosing a name, API and Platform

Click on “Create Game.” Once the game has been created, you will be given a SWFID, GUID and API Key.

Now you have the SWFID, GUID and API key

Hooray, you’ve set up the analytics client! Have a chocolate.

Integrating Playtomic into Your Game

Now let’s get your game talking to Playtomic. The following is taken verbatim from Playtomic’s iOS documentation (I’ve added images to help):

Setting up the iOS API

Add these frameworks to your game by clicking the project, then selecting the target -> build phases -> expanding Link Binary with Libraries.

  • libz.1.2.3.dylib (for iOS 4.x)
  • libz.1.2.5.dylib (for iOS 5.x)
  • CFNetwork.framework
  • MobileCoreServices.framework
  • SystemConfiguration.framework

Example of adding libz.1.2.3.dylib to your project

Download the Playtomic iOS API, or visit this page.

Unzip the file, drag and drop the entire Playtomic subfolder into your iOS project.

The Playtomic folder now resides in our project

Initialize the API

Add the following line to the top of HelloWorldScene.m:

#import "Playtomic.h"

Go ahead and build the project to make sure that all the files are included correctly.

Next we want to initialize Playtomic at the start of the application. Inside the applicationDidFinishLaunching method in Cocos2DAppDelegate.m , insert the following:

[[Playtomic alloc] initWithGameId:SWFID andGUID:@"GUID" andAPIKey:@"APIKey"]; 
[[Playtomic Log] view];

Be sure to replace the SWFID, GUID, and APIKey with what you got when you created your game entry in Playtomic.

Congratulations, we’ve got our game talking to the analytics server! Have another chocolate ;]

What to Track?

This question requires a bit of thought. Since we can track basically anything in the game, it would be wise to prioritize what matters.

As a game developer, I want to know if the player is having the best experience possible. In this case, I want to know if my players are able to complete the levels. If everyone stumbles at the first level, that means it’s too difficult.

Here’s some things we might want to track for this game:

Basic metrics

  • Player wins/losses: Recorded as an increasing counter. This helps us see how many wins/losses occur – if players are losing too much, might be too hard!
  • Level starts & completes: Also recorded as increasing counters. This helps us know if players actually make it to the various levels and complete them. This is different from wins/losses, because a player might just quit the game upon seeing a “You lose” message, and not complete the level or start a new one.

More advanced stuff

  • Where monsters escape: You can use Playtonic to record the 2d coordinate points where the monsters escape past the screen. It would be displayed as a heatmap, allowing us to see where most players fail to kill the monsters.
  • Dynamic tweaking: Using variables stored on the Playtomic server (called GameVars), we can dynamically change the speed of the monster and/or the speed of our projectiles without recompiling our game. This is a huge advantage for game developers who have shipped a game to the App Store, but don’t want to wait for days to push a new update.

In this tutorial, we’re just going to focus on the basic metric tracking. We may cover the more advanced stuff in a future tutorial, if there’s enough time & interest!

Code for Basic Metric-Trackers

To track player wins, open Cocos2DSimpleGameAppDelegate.m
and import Playtomic.h at the top of the file:

#import "Playtomic.h"

Then add the following line of code to the bottom of the loadWinScene method:

// Track level win (as custom metric)
[[Playtomic Log] customMetricName:@"YouWin" andGroup:nil andUnique:NO];

As you can see, logging an integer count metric is as simple as this single line of code, specifying the name of the metric!

Similarly, to track player losses, add the following line of code to the bottom of the loadGameOverScene method:

// Track level loss (as custom metric)
[[Playtomic Log] customMetricName:@"YouLose" andGroup:nil andUnique:NO];

Next to track level completes, add the following code to the top of the levelComplete method:

// Track level restart
[[Playtomic Log] levelCounterMetricName:@"LevelComplete" andLevelNumber:_curLevelIndex andUnique:NO];

Finally let’s track level starts. A good place to do this is in the method where the game displays a “Get ready” screen for a few seconds when the level begins.

Open up NewLevelScene.m, and import Playtomic.h at the top of the file:

#import "Playtomic.h"

Then inside the init method for the NewLevelLayer add the following line of code:

// Track level win (as custom metric)
[[Playtomic Log] customMetricName:@"GetReady" andGroup:nil andUnique:NO];

Time to Play!

Give the game a couple of spins in the emulator. Then log into your Playtomic dashboard, click on the game you added, and look at the Level Metrics and Counter Metrics. Voila, your data is there!

Some live metrics from the dashboard

Here’s the link to the live stats of the game (using my own SWFID, GUID and API Key). I made it public so everyone can have a look at it.

Take your time, explore your own data and try to understand what causes it. Look at the different game metrics that you chose to track.

Where to Go From Here?

Hooray! You just acquired the “analytics” mindset of designing games. Keep this with you as you design future games. Playtomic’s iOS documentation explains itself well: read it and you’ll understand very quickly how to implement all the other cool features.

Feel free to download the entire project here, or check out my Github repo. Be sure to replace the SWFID, GUID and API_KEY with your own. If you haven’t got your own, refer to the “Initializing the Components” part of this tutorial to learn how to set up Playtomic.

Note that in my version, I also modified the game rule: upon killing 5 monsters, you progress to the next level.

For further experimentation, have a look at this popular open source game made with Cocos2D. I integrated some cool stuff, like 2d heatmaps and game variables. Download the entire project and look under the hood.

The project will help you understand:

  • My analytics mindset.
  • How to set up some of the more advanced stuff.

Note: be sure to use your own SWFID, GUID and API KEY.

Hope to see you in my next tutorial. In the meantime, join in the forum discussion below. And have a final chocolate :]


This is a post by Ben Chong, an aspiring iOS game developer living in Indiana.

User Comments

10 Comments

  • Nice Tutorial!
    I'm going to try it!

    Thanks
    redtoasty
  • Thank you for the tutorial. I had a spot of a challenge when I imported the sdk and there were duplicate main's to link to... all the rest seemed to be fine.

    My question:
    What are the strengths and weaknesses between the analytics sdks/packages? Perhaps specifically Flurry versus Playtomic? Note: i've used flurry and its great for more business analytics (sessions, what type of devices...). I think I'll add an API for crash reporting (Flurry has a method for handling...)

    But my MAIN question goes back to is what are the strengths and weaknesses of each package?

    Note: I find TestFlight another awesome service for Ad Hoc testing. Although this isn't analytics - a terrific way to get testing going!

    Thanks very much for the tutorial!
    sketchy
  • Good stuff. I wasn't even aware of this. Thanks! :D
    Cal
  • sketchy wrote:Thank you for the tutorial. I had a spot of a challenge when I imported the sdk and there were duplicate main's to link to... all the rest seemed to be fine.

    My question:
    What are the strengths and weaknesses between the analytics sdks/packages? Perhaps specifically Flurry versus Playtomic? Note: i've used flurry and its great for more business analytics (sessions, what type of devices...). I think I'll add an API for crash reporting (Flurry has a method for handling...)

    But my MAIN question goes back to is what are the strengths and weaknesses of each package?

    Note: I find TestFlight another awesome service for Ad Hoc testing. Although this isn't analytics - a terrific way to get testing going!

    Thanks very much for the tutorial!


    thanks for testing! I can only comment from the perspective of Playtomic - our main strength is we cater specifically to game analytics. Any event can be tracked, plus we've got advanced features such as heatmaps, level sharing, leaderboards, data exports and more.

    Two things are coming in the next few weeks:

      An awesome dashboard which includes time-based comparison, sticky notes, and error logging

      We're rolling out social game analytics, which includes virality,retention (cohorts) analysis, etc
    bazookaBen
  • Very cool. I have been using Flurry analytics for a non-game app but I did not know about Playtomic. It will definitely be in my upcoming iOS game!
    Swindler
  • can't get the installation to work. A lot of error messages.
    esael
  • I did the work to integrate Playtomic and then realized that the company seems pretty unstable right now. There are a lot of complaints about servers being down and the owner even has a notice on their website that they've had to cut the staff way down. It's too bad because I think they have a good product, but I'm going to stick with Flurry. :)
    Swindler
  • Speaking about Flurry, I was logging some events using Flurry. When I tried to see the data in the control panel back at Flurry, some of the events are registered as "null". Anyone has any idea what happened??
    duracellrabbid
  • Just wanted to mention that TestFlight now offers free analytics as well as their beta testing (it's called TestFlight Live).
    https://testflightapp.com/sdk/live/

    And also another option for free analytics and tracking is Apsalar.
    http://apsalar.com/
    jsherk
  • Should an app ask the player if it is allowed to send analytical data? Or is it acceptable to just do it behind the players back?
    Since this is something that requires an internet connection and sends user data (even if it is just purely game-based and maybe anonymized) to another 3rd party service.
    xbaalx

Other Items of Interest

Ray's Monthly Newsletter

Sign up to receive a monthly newsletter with my favorite dev links, and receive a free epic-length tutorial as a bonus!

Advertise with Us!

Hang Out With Us!

Every month, we have a free live Tech Talk - come hang out with us!


Coming up in May: Procedural Level Generation in Games with Kim Pedersen.

Sign Up - May

Coming up in June: WWDC Keynote - Podcasters React! with the podcasting team.

Sign Up - June

Vote For Our Next Book!

Help us choose the topic for our next book we write! (Choose up to three topics.)

    Loading ... Loading ...

Our Books

Our Team

Tutorial Team

  • Marcelo Fabri

... 55 total!

Editorial Team

... 22 total!

Code Team

  • Orta Therox

... 1 total!

Translation Team

  • Victor Grushevskiy
  • Jiyeon Seo

... 38 total!

Subject Matter Experts

  • Richard Casey

... 4 total!