Using Playtomic Analytics In Your Flash Games


Playtomic Game Analytics and Services for Casual GamesPlaytomic is a free game analytics service I have been using in my Flash games for almost two years now. It provides a real time tracking platform not only for Flash games, but also for games made with HTML5, iOS, and Unity.

Playtomic is a great way to understand how playertesters are playing your games during the development phases of your game and then to further study how your game is being played and spread around the world once you release it.  Beyond the real time analytics tools it also offers global leaderboards, heatmaps, custom game data, and level sharing APIs.

I can’t recommend Playtomic enough as it has really had a large and beneficial impact on the way I approach my game development, playtesting, and publishing. I’m not the only one enjoying Playtomic either–over 2,000 developers are currently using the service to track over 3,000 individual games, and logging an amazing billion combined real time events per day!

Playtomic Analytics Tutorial Demo


This tutorial will focus on the basics of getting your account setup with Playtomic and getting the basics of the analytics working in your game SWF.  I’ll be using the latest Playtomic API version 3.15 for ActionScript 3.0 (though Playtomic does support ActionScript 2.0 as well.) I’ll also be using the Flash IDE to create the game project but the code I’ll be demonstrating will work basically the same if you’re not using Flash. I’ll provide the source for the demo above saved as a Flash CS4 project in case you haven’t upgraded to the latest version yet.


Register for PlaytomicRegister:

First step is to simply register your account on Playtomic. This is pretty basic and you don’t even have to wait for an email for your account to activate.



Create Game ScreenCreate First Game:

The next step is to create your first game in the system. I’m just using a ‘Test Game’ for the purposes of this tutorial.  The important part is to hit the two radio buttons. Select ‘Casual/mobile game’ for ‘Game Type’ and ‘Web’ under the ‘Flash’  platform area. Then just click the ‘Create Game’ button and the system will bring you to the game overview screen for API setup.


New Game API OverviewFirst Game API Overview:

You should now be looking at the API information for the game you just created. The most important information here is the game credentials area that lists your SWFID and GUID.  You should keep these numbers private since they are the way the API will communicate from your game to the Playtomic system.

The other important areas are the documentation and downloads areas. I’ve marked everything on the screenshot to the left that you can click to enlarge. You can get to this screen by clicking on ‘API Setup’ in the vertical nav menu at the left when you are logged in on the Playtomic website.

Download the Tutorial:

Normally you’ll click on the download link for the latest Playtomic API zip file on the Playtomic website. You’ll then extract the contents of the zip and find the folder called ‘Playtomic’ inside the folder called ‘gameapi-as3’.  You’ll want to copy the ‘Playtomic’ folder into the root folder of your game project so that the folder is at the same directory level as your FLA file.

This time though I’ve already included the latest Playtomic API within the tutorial download. At the time this tutorial was written that was version 3.15 for ActionScript 3.0.

You can download the tutorial here. I saved the FLA as a Flash CS4 FLA for people using older versions of Flash still.

Extract the tutorial zip and then open up both TestGame.fla and in the Flash IDE.

I’m only going to point out the most important parts from the source. The tutorial source file itself is heavily commented and should be fairly self-explanatory. This tutorial also assumes you know the basics of ActionScript 3.0.

In order for everything to work you are going to need to have already setup your new game on the Playtomic website from the instructions further above. If not go ahead and do that now because you’ll need your unique SWFID and GUID to plug into the config area.

// Playtomic API constants 
// SWFID from Playtomic API Setup screen
private static const PLAYTOMIC_SWFID:String = "xxxxxxxxxxxxxxxxx";

// GUID from Playtomic API Setup screen
private static const PLAYTOMIC_GUID:int = xxxx;

Before you can use the API you'll need to import the Playtomic classes. You'll see I do that near the top of the source file with the other standard Flash imports.

// import the Playtomic API 
import Playtomic.*; 

Custom Metrics

You need to init the Playtomic API as soon as possible in your game code and definitely before you call any of the Playtomic services. I usually do this with an init function of some type called during my FLA Document class constructor phase.



// Init the Playtomic API as soon as possible and
//   before you call any other Playtomic services!
private function init():void {
  // Initialize the API by logging the view
  //   this registers a 'view' on the server
  Log.View(PLAYTOMIC_GUID, PLAYTOMIC_SWFID, root.loaderInfo.loaderURL);

While we have now logged a 'view' above we want to track how many times the game will actually be played during that view session. In other words there should be more 'plays' of your game than 'views'. If not, the view to play ratio is a great indication that your game could use some improvement!

I typically track the 'play' event when my gameplay assets are being instantiated.

// Play the game
private function playGame():void {
  // Registers a 'play' event on the server. There can be multiple 'play' events per 'view'
  // do one time setup for game

Custom Metrics

Another very easy and powerful thing to do with Playtomic is to track custom counter metrics. I have included an example in the tutorial. Whenever the player clicks on the 'Credits' button on the main menu we track a 'ViewedCredits' event. You can use these events to track all sorts of handy data. I usually track common things like every time the credits are viewed, the instructions are viewed, the sound or music is toggled on or off, how many times the game is restarted or paused. Basically any handy data point you'd like to gather to start understand how players interact with your game or the menus surrounding your game.

// Listens for mouse click on credits button
private function creditsButtonClickListener(event:MouseEvent):void {
  // Track a custom metric on the server so we know a
  // player viewed the credits screen
  Log.CustomMetric("ViewedCredits"); // metric, names must be alphanumeric

Level Metrics

There are many other types of metrics you can track too. I like putting in tracking for average score so that even if players aren't submitting a score I can see how players are doing with the game. You can do this with a level average metric call. When your game doesn't have individual levels you can just feed in the string 'Game' (or whatever you want) that represents the entire game and not a specific level.

In the tutorial I track a level average metric when the player hits the 'Quit' button.

// Quit game button click listener
private function quitGameButtonClickListener(event:MouseEvent):void {
  // Track the current score as a level average metric event
  //   You can track averages for specific levels or the entire game.
  //   Here the string 'Game' represents the entire game not a 
  //   particular level string.
  Log.LevelAverageMetric("Score", "Game", score);	

That's about it! The Playtomic website documentation is pretty decent and the community forums on the site are starting to mature a bit so that you can often get help from a question posted up there before too long. Once you integrate Playtomic into your own game you'll start thinking up all kinds of great uses for it. I've used the global leaderboards and level sharing APIs and will start experimenting with the heatmaps soon. I will use this base tutorial code to write up a few followup tutorials on Playtomic soon.

Let me know if I can improve this tutorial and if you have any questions at all!


Simple AS3 Viewport Tutorial

Simple Flash AS3 Viewport Demo
Click inside and use arrow keys to move viewport

This is a little demo I made this morning as a way to get a viewport concept working for the latest game I am developing.  I’ve done a few viewport type projects in other languages but had not implemented one in Flash AS3 yet.

This demo creates 300 random balls and sets them in motion inside the world.  The world’s dimensions are four times larger than the viewport above.

You can click in the window above and use the arrow keys to move the viewport around the world.  The source files for this tutorial are available at the end of the article.

Continue reading