This is a post by Ben Chong, an aspiring iOS game developer living in Indiana.
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.
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
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.
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.
Now let’s set up the analytics client. Sign up with Playtomic for free. In the Playtomic dashboard, click “Add New Game.”
Give your game a name (any will do), choose iOS/Objective C for the API, and choose iPhone/iPod for the Platform.
Click on “Create Game.” Once the game has been created, you will be given a 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)
Unzip the file, drag and drop the entire Playtomic subfolder into your iOS project.
Initialize the API
Add the following line to the top of HelloWorldScene.m:
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:
- 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:
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:
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!
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.