Analytics Manager: Haxe & OpenFL

This week I want to talk about a very useful and simple tool I made for collecting gameplay information and basic (anonymous) information from devices where players play. You can fork and use the extension from github. I haven’t tested this with the new version of OpenFL and haxe but it should work, if for any reason doesn’t work please let me know.

How to Use it: Client Side

First of all you have to instantiate the AnalyticsManager class:

var analyticsManager : AnalyticsManager;
var analyticsDB : String = "DataBase"; //You should write the name of the database you created to store the data
analyticsManager = AnalyticsManager.InitInstance(analyticsDB);

There is a class called AnalyticsData, you just create a new class and make it extend from this class.

class AnaTest extends AnalyticsData
{
   public function new()
   {
      super();
      //These are just test values, you can use parameters here
      this.AddValue("par1", "val1");
      this.AddValue("par2", 65);
      this.AddValue("par3", 42.028);
   }
}

The class above is just a sample, you can add parameters to the constructor and pass different values to it depending on the case.

After you create a custom class to pass store whatevergameplay data you want to store, you need to call the AnalyticsManager and create a new instance with the data you want to send.

var url : String = "URLToMyServer"; //You have to create a script on the server side
var table : String = "TableName"
AnalyticsManager.SendDataToServer(url,table,new AnaTest());

The data is automatically converted to JSON so you can just parse that on the server side and store it. This default behavior can be changed as well but I have to implement it.

How to Use it: Server Side

I add a sample of a very simple script in PHP to take the data sent fromthe server and do something with it. Of course you can write your own script usign whatever language you prefer.

$table = $_POST["table"];
//Get the data and decode from JSON
$json = urldecode($_POST["data"]);
$array = json_decode($json);

foreach($array as $key => $val)
//Do whatever you want with the attributes

echo "success"; //this tells the client everything is ok

Please notice that this probably needs some security, just to protect your data from bad people, you know. Be careful with the way you send the data.

With these few steps you should be able to use the extension and store some interesting data from gameplay and then improve your game.

How is the Extension Structured

There are three different base classes, each one with a clear purpose for this extension: AnalyticsData, AnalyticsLoader and AnalyticsManager.

AnalyticsData

This is an abstraction of the data you want to send to the database. Basically this class stores pairs of values: (Key,Value) to be passed to the server and then eventually stored in a table which contains columns of the same names of those keys.

class AnalyticsData
{
   private var values : Map;
   public function new()
   {
      values = new Map();
   }

   private function AddValue(key : String, value : Dynamic) : Void
   {
      values.set(key, value);
   }

   public function ToString() : String
   {
      var data : String;
      data = "";
      for (k in values.keys())
      {
         data += k + "=" + values.get(k);
         data += "&";
      }

      return data.substring(0, data.length - 1);
   }

   public function ToJSON() : String
   {
      return Json.stringify(values);
   }
}

Use the AddValue function to include more pairs (key,value) to the instance of this class and before sending it to the server, use ToJSON or ToString to be sent as parameter in a long string.

AnalyticsLoader

This class has common event functions such as onComplete and onIOError, in order to send data to the server, a loader is needed. Once the data is successfully sent or an error occurs, this class manages that response.

class AnalyticsLoader extends URLLoader
{
   private var onComplete : Dynamic -> Void;
   private var onIOError : Dynamic -> Void;

   public function new(?request:URLRequest,?onComplete : Dynamic -> Void,onIOError : Dynamic -> Void)
   {
      super(request);
      this.onComplete = onComplete;
      this.onIOError = onIOError;
      if(onComplete != null)
         addEventListener(Event.COMPLETE, onComplete);

      if(onIOError != null)
         addEventListener(IOErrorEvent.IO_ERROR, onIOError);
   }

   public function Clean() : Void
   {
      if (onComplete != null)
      {
         if (hasEventListener(Event.COMPLETE))
            removeEventListener(Event.COMPLETE,onComplete);
      }

      if (onIOError != null)
      {
         if (hasEventListener(IOErrorEvent.IO_ERROR))
         removeEventListener(IOErrorEvent.IO_ERROR,onIOError);
      }
   }
}

Calling the Clean function will remove all the handlers from this class.

AnalyticsManager

This is the core class of the extension, handling calls and managing the data internally without the hassle of doing the same process again and again. This class is a singleton, that’s why can only be instanciated from the available methods: first InitInstance and GetInstance if you need to use it.

class AnalyticsManager
{
   /*
   * Analytics manager instance.
   */
   private static var instance : AnalyticsManager;
   private static var loaders : Array;
   private static var database : String;
   public static function InitInstance(database : String = ""): AnalyticsManager
   {
      if (instance == null)
         instance = new AnalyticsManager(database);

      return instance;
   }

   /*
   * Creates and returns a analyrics manager instance if it's not created yet.
   * Returns the current instance of this class if it already exists.
   */
   public static function GetInstance(): AnalyticsManager
   {
      if ( instance == null )
         throw "The Analytics Manager is not initialized. Use function 'InitInstance'";

      return instance;
   }

   /*
   * Constructor
   */
   private function new(db : String = "")
   {
      loaders = new Array();
      database = db;
   }

   public static function SendDataToServer(url : String,table : String, anaData : AnalyticsData,onComplete : Dynamic -> Void = 
   null,onIOError : Dynamic -> Void = null, db : String = "")
   {
      var request : URLRequest;
      var loader : AnalyticsLoader;
      var variables : URLVariables;
      var databaseName : String;

      databaseName = db != "" ? db : database;
      request = new URLRequest(url);
      //I also decided to do every request through POST method, if needed could be change in the future
      request.method = URLRequestMethod.POST;
      //I decided to use only JSON, we could change this in the future
      request.data = "database=" + databaseName + "&table=" + table + "&data=" + anaData.ToJSON();
      trace(request.data);
      loader = new AnalyticsLoader(request,onComplete,onIOError);

      loaders.push(loader);
   }

   public static function Clean() : Void
   {
      for (l in loaders)
        l.Clean();
   }
}

An array of all the loaders is kept here for easy cleaning whenever the programmers needs to do it. This class also stores the name of the database (in the server side), currently this extension only handles one database per game.

The SendDataToServer function creates a loader and with it sends the data to the server and let the loader handle whatever response comes from it.

Wrapping Up

In addition to the three base classes I explained here, there is a BasicData class which contains general information you might be interested in storing from the player’s device. This information is anonymous so the privacy of that user is protected in any case.

This was the post for today, a very simple way to collect and store gameplay information to improve your creations. If you have questions or comments, just let me know.

 

---