Analytics in Unity Flash

Introduction to Analytics

We currently have a Flash version of Fling Theory, our game made in Unity, up for bidding on FGL. Fling Theory is a puzzle game where you fling electrons, manipulate atoms, and solve puzzles. We’ve been working on it for quite some time and one of our biggest issues was making sure people followed through the tutorials without getting frustrated and leaving. This is where analytics comes in, because you can gather the data of how long people are playing, where they’re having difficulty, and where they quit your game.

Why Use Playtomic Analytics

After much searching on the web, and checking out all of the big players, I decided to go with Playtomic analytics. Why Playtomic? Well Playtomic actually works on ALL platforms that Unity exports to (PC, Mac, Android, iOS, Web, Flash). Most of the competition that you’ve heard of are geared towards only a single platform (Flurry for iOS, Google Analytics for Web, etc.) Playtomic also has a Unity API so nearly all of the work is done for you instead of jumping through hoops to get something like Google Analytics working on a specific platform.

Playtomic, Unity and Flash

Flash is one of the latest platforms that Unity supports. Since Unity code is transcoded into Action Script and at the mercy of the Flash Players’ security sandbox, there are quite a few issues that prevent a library such as Playtomic from working directly using Flash export. Luckily, Playtomic has a Flash API that conforms quite closely to the Unity Playtomic API.

The first thing you will notice when doing conversions from Unity 3.5.x to Flash is that a lot of functionality such as Hashtable aren’t supported. This will prevent Playtomic’s Unity API from compiling in your project. This is where most people give up as they do not want to rewrite an API, but as I mentioned earlier Playtomic has a Flash API, so you’re in luck! Let’s go through the conversion process.

Step 1 – Download Playtomic Unity API

First things first. You will need the Playtomic Unity API. If you visit http://www.playtomic.com you will be able to download the Playtomic Unity API as well as sign-up for a free account. I recommend downloading from the Playtomic website since the Unity Asset Store version is not as up to date.

Step 2 – Not Converting Unity Code

Start by telling Unity not to attempt to convert Playtomic’s API into Action Script code. To do this, you’ll need to open up every one of the Playtomic classes and add the attribute [NotConverted] to the class definitions. Technically, the NotConvertedAttribute comes from the UnityEngine namespace, so in some cases like the Playtomic_Responder class, you’ll need to fully qualify it since UnityEngine namespace isn’t imported:

[UnityEngine.NotConverted]
public class Playtomic_Responder

Step 3 – Downloading Playtomic Flash API

When you try to export to Flash now, you will notice the Playtomic library will not be converted to Action Script, but any code you’ve written to use the Playtomic API will now fail because Playtomic is not defined. So what you will want to do now is go to http://www.playtomic.com and download the AS3 API. Extract the AS3 API to a folder inside your Assets folder called “ActionScript”. So the final path for the files such as Log.as will then be Assets/ActionScript/Playtomic/Log.as. Anything inside an ActionScript directory is compiled with your final Unity-converted .as files, so that’s how this magic happens.

Step 4 – Ensure Unity Stops Mangling API Calls

You’ll notice when you convert now, you will end up with some errors such as Playtomic.Playtomic_Log is undefined. This is because Unity mangles names when it converts to Action Script code. What you need to do is go back to every Playtomic Unity file and add [NotRenamed] under every [NotConverted] attribute. This will ensure a Unity line like Playtomic.Log gets converted to Action Script as Playtomic.Log and not the Unity-mangled Playtomic.Playtomic_Log.

Step 5 – Ensure Unity Imports Flash API

Now you need to tell Unity to use the Flash API. To do this, every time you use a Playtomic call in a class, you need to write an import statement somewhere in the code for that class. I wrapped all my analytics calls into a custom class called CodingJarAnalytics, so I only have one class I need to do this in. In that class, I add this statement in just before my ViewGame() call:

ActionScript.Import( “Playtomic.Log” );

Unfortunately, you can’t use Playtomic.* as it does not convert properly so you will need to do a separate Import statement for each class you use. You only need one of these statements per Unity class, as the converter will move this import statement to the top of the .as file generated.

Step 6 – Write Custom ActionScript Glue Code

The final issue you will encounter is there are slight differences in the API between Flash and Unity. For instance, the Flash API uses Playtomic.Log.View as its initialization, whereas Unity uses Playtomic.Initialize. The trick here is to write your own Action Script Initialize() function which does the forwarding. First, you will need to add an Import statement for “Playtomic.Initialize” as you did for Playtomic.Log. Now, generate your own glue code. Make a file in a path named ActionScript/Playtomic/Initialize.as. Note, this path does not need to be under Assets/, it can be anywhere. I like to keep Assets/ActionScript for Flash APIs. So I’ve actually put this file under the Plugins/Playtomic folder to keep the Unity side separate. Here is the contents of the file:

package Playtomic
{
  import Playtomic.Log;
  import com.unity.UnityNative;
  import flash.display.LoaderInfo;
	
  public function Initialize(swfid:int = 0, guid:String = "", apikey:String = "") : void
  {
    Playtomic.Log.View(swfid, guid, apikey,
      UnityNative.stage.loaderInfo);
  }
}

Since you’re calling ActionScript’s View() on Unity’s Initialize(), you should also avoid calling Playtomic.Log.View() on the Unity side, as it will generate a duplicate call and give you a warning.

Conclusion – TL;DR

You are now done, and everything should just work. However, if you’re lazy and don’t want to do all of these steps manually, I’ve done them all for you! Simply download the modified Playtomic Unity API which takes care of every step except #3, which you will have to do manually. I hope this guide serves a purpose to help you convert other Action Script libraries to be compatible with Unity Flash export. Happy coding.

Leave a Comment