How to Use Analytics

Automatic Events

By default, the DarkMatter library will automatically track the First Launch, Session Start, and Session End events. All events send a specifically named set of parameters as follows:

Table 1. Parameters attached to every event.

The non-coloured cells are automatically tracked and sent by the library. The coloured cells are parameters the client game sends into the library though its public methods.

Adding and Sending Custom Events

Custom events can specify their own name (n), categories (st1, st2, st3), value (v), and custom data (cp). The only required value is n, the rest can be null. The event name and categories are strings. It is recommended to keep them short. The value parameter is also a string. The custom data is in the format of an array of strings.

Purchase Events

Proper tracking of monetization events are critical to monitoring the success of an app.

The key event that we use for tracking monetization is sent with the SendPurchaseEvent method. Every successful purchase should send one and only one of these events. Do not send one on a restored product.

The event method takes the product ID, the price in US Dollars, the time in milliseconds that the transaction took, and the transaction ID. One use of the time parameter is that transactions that complete near instantly are most likely fake and can be removed from some analytic reports. Keep a timestamp from when the user clicked to buy an IAP product and compare it to when you get the success callback.

Another important piece of information that is useful in detecting fraudulent purchases is the Transaction ID. On iOS, this can be obtained from the iTunes Receipt. Please include the Transaction ID in a purchase successful event. You can also specify custom parameters on this event.

API Documentation

AnalyticsAPI Class Reference

Public Member Functions

void 	SetABGroup (int groupID)
 
void 	UserID (string userID)
 
void 	SendAnalyticsEvent (string eventName, string category, string subcategory1, string subcategory2, string value, params string[] customParameters)

void 	SendPurchaseEvent (string productID, float usdPrice, string transactionTimeInMillis, string transactionID, params string[] customParameters)

Public Attributes

EventManager eventManager

string flurryAppKey

bool logEvents

Properties

static AnalyticsAPI Instance [get]

Member Function Documentation

 void SendAnalyticsEvent	(string eventName,
 string category,
 string subcategory1,
 string subcategory2,
 string value,
 params string[] customParameters 
 )

Creates and sends a new Analytics event with the given n, st1, st2, st3, v, and custom parameters respectively.

Parameters

eventName - The analytic shortname.

category - st1 shortname

subcategory1 - st2 shortname

subcategory2 - st3 shortname

value - A data value for certain events.

customParameters - Additional event parameters.

void SendPurchaseEvent	(string productID,
float usdPrice,
string transactionTimeInMillis,
string transactionID,
params string[] customParameters 
)		

Creates and sends a new In-App Purchase event with itemName, productID, and usdPrice as the n, st1, and v parameters respectively.

Parameters

itemName - The English title of the product.

productID - The unique product ID that the store uses.

usdPrice - The price of the product on the store in US dollars.

transactionTimeInMillis - The time in milliseconds from when the user clicked on the product to buy it to when it was successful. It is sent in the custom parameters.

transactionID - The unique identifier for the transaction.

customParameters - Contains any other custom parameters you wish to send.

Examples

Send Analytics Event:
AnalyticsAPI.Instance.SendAnalyticsEvent("lup", "PROG", "LEVEL_UP", "Floor B12", playerInfo.level, playerInfo.sessionCounter.ToString());

Send Purchase Event:
TimeSpan timeDiff = DateTime.UtcNow.Subtract(purchaseInitiatedTime);
AnalyticsAPI.Instance.SendPurchaseEvent("Mega Gold Pack", "com.company.megagoldpack", 49.99f, ((int)timeDiff.TotalMilliseconds).ToString());

. . .

Restricted Keywords and Recommendations

The name of the event (‘n’) must be unique for the game, otherwise it becomes difficult to distinguish events. Do not use any of the event names tracked by the library (fl, sess, esess, and iap). st1, st2, st3, v, and up to 10 custom parameters are completely up to you to use. We recommend using the categories to help separate an event into a finite amount of groups, or to specify a kind of type to the event. We recommend using v as the primary data column, and use the custom parameters if you need more.

For events that change a particular statistic of the game and/or player, we recommend using v to store the current value of the stat after the change, and a custom parameter for the amount of change. For example, on a currency update event, use v to store the player’s total currency after the event (5500) and the first custom parameter to be the delta (-500).

The custom parameters are stored in the order they are entered. Keep a table of what each index of your custom parameters means.

When thinking of data to send on an event, keep it localized to the event itself. You’ll more easily introduce bugs if you need to reach to every corner of your code base to gather the information needed. Favour sending more events than less events with more custom parameters. Concern yourself mainly with getting the data entered into the library and not about how to get the data out of the database.

Debugging Analytic Events

The Analytics game object in your scene also has a checkbox for turning on additional logging of events. This can be used to verify that events are being tracked and sent to the server correctly. Logs should start appearing for every event added, as well as when the server responds. Here’s an example of what the logs should look like.

DarkMatter.Analytics.EventManager:: Successfully sent event.

ANALYTIC

{"token":"trui5ar3a7fa92af2h8hovriv1d34jjg","user":{"mid":"8a3383423fe79abdb1a518a28f732ddd41976125","api":"2.0.5.0","pid":"99","did":"EDE50A44-C78C-4716-BA10-A99C69938892","os":"iPhone OS 8.1.3","d":"iPhone7,2","a":"mag","ver":"1.0","c":"CA","lg":"English","sid":"a37d7ff5-648e-4409-a3fb-f223296cd2d4","tz":"-04:00"},"events":[{"ts":"1441983954","tig":"534","n":"esess","v":"49.72"}]}

 Response:

{"result":"success"}



DarkMatter.Analytics.EventManager:: Successfully sent event.

ANALYTIC

{"token":"trui5ar3a7fa92af2h8hovriv1d34jjg","user":{"mid":"8a3383423fe79abdb1a518a28f732ddd41976125","api":"2.0.5.0","pid":"99","did":"EDE50A44-C78C-4716-BA10-A99C69938892","os":"iPhone OS 8.1.3","d":"iPhone7,2","a":"mag","ver":"2.0","c":"CA","lg":"English","sid":"925e7354-7b59-40b0-9033-502c17cefc80","tz":"-04:00"},"events":[{"ts":"1441989606","tig":"534","n":"sess","st1":"LAUNCH"}]}