Adding Custom Events to your Game or App

Summary: This article covers the steps necessary to add your own unlimited number of custom events to your game or app.  This is a powerful feature as it allows you to track literally any user action that you want to measure.  

*NOTE: If you are looking for the fully fledged Apmetrix API please click here. This article only covers our Apmetrix.logEvent()

Adding custom events to your game or app allows you to really see many types of user behavior and helps you answer many questions such as;

  • What are my users buying and when?
  • What's the percentage of people who actually select, abandon or complete any offer in my app?
  • How are my users using the virtual currency they purchased?  What items are they buying and are they spending their virtual currency or not?
  • How many of my users are completing the "First Time User Experience" (FTUE) / Tutorial and how long did it take them?  Is it intuitive?
  • What in-app purchases and offers are working?
  • What is the lifetime value of my users (either collectively or individually) and where did they come from?  Were they organic (app store) or did they come from other ad networks from my user acquisition campaigns?
  • Which activities are my users engaging in and for how long? 
  • Which items are being used, consumed or avoided?
  • At what point in my game or app do users purchase virtual currency or other items?


Adding these custom events allow you to really see many types of user behaviors which are critical to understand your game or apps health in order to maximize revenues and deliver a great experience.


Adding custom events to your game or app is hugely beneficial and highly encouraged as it allows you to track many types of events and actions that users and applications generate.  Our platform allows you to pass in an unlimited number of these events and track them in many different ways.  While this functionality is extremely powerful, it can also be very unwieldy if some best practices are not thought of or contemplated in advance.  While you can of course create as many dimensions as you like (up to 24 in fact), we have suggested a logical way using 4 dimensions which may make it easier to create and report on your custom data.

We have predefined several datasets which should cover most of custom events which you would want to track:


User Events:                  

This can be any event created by a user in your game or app that deals with tracking button press, finger touches related to actions that a user can do in your game or app.  See the "Suggested Taxonomy" article below for best practices when thinking about what custom events to track and logically grouping them in a way that makes sense.  You are not limited to using this structure as it's just an example.  Use this dataset when collecting this type of information.

Application Events:    

These are events generated by your game or app and are events not associated with user actions.  Use this dataset when collecting events that are related to events that are generated from the app itself, NOT for User Events as mentioned above.

Ungrouped Events:    

These are any custom events which are not covered by the User or Application events.  Use this dataset if you are tracking some data that doesn't fit into any of the other datasets.


Suggested Taxonomy for Tracking Custom Events

As a game or app can have many such custom events, it is important to logically categorize your local application variables as you would logically think such an event should be tracked.  A suggested structure (at least for the first four dimensions) would be as follows;

  • Verb – What action or event is occurring such as a user; “crashed”, “invited”, “fired”, “damaged”, "selected", "abandoned", "completed" etc.
  • Object – What action is occurring on what object such as “car”, “friend”, “house” "virtual currency", "weekend sale", etc.
  • Location – Where did such an event occur?  It is useful to think of this within the context of your game or app as each is different based on context.  For example; for an adventure game you may want to list the map or level where the event occurred.  For a racing game, perhaps the track, or for a puzzle game, the name of the puzzle or level.  Think in terms of relevant location data you’d need to know.
  • Value – This is additional information in the form of a string you may wish to pass in depending on the specific event you are tracking. For example; you may want to pass in the time for the car crashed, determine whether a condition was True or False, or any other special string you might want to filter on.
  • Numerical Value - This is additional information you may wish to pass in depending on whether or not you need to pass in a number (i.e. if you want to track currency or economy flows such as "Primary Currency at Session Start", "Primary Currency Earned", "Primary Currency Spent", "Primary Currency at Session End" ).  Please note that this field is NUMERIC and therefore can have math applied to them.

Important Notes:

Since the system defaults to treating incoming data as strings, you will need to include the “#” symbol in front of your metric data so the system recognizes it as a numerical value.

Also note that since these are literal examples, you will need to replace the parameter with the actual local game variable you wish to pass in to the platform so as to appropriately reflect your own data structure.

For iOS/Xcode functions you MUST terminate the function with a 'nil' argument to end the function call.  In addition, if any field is blank and you want to send additional data in other fields, you will need to have a @"" in the function call as iOS terminates the function when 'nil' is used in the function call.  Se examples below for syntax.



To add custom events/tags to your game or app, you need to pass in the function call listed below:

Generic Function Call:

Apmetrix.logEvent(table, dimensions);



 Predefined value for the type of event. Allowable values are UNGROUPED_TABLE, USERS_TABLE, or APPS_TABLE. *Note: Names vary by platform SDK


 Variable length comma delimited list of custom event dimensions.

*iOS Note: This list MUST be nil terminated.

Note: The platform has the ability to take in up to 25 string dimensions and 4 metric dimensions.

Following are some examples that demonstrate use of the logEvent() function using the above suggested ordering or dimensions.


EXAMPLE; Tracking in-app purchases of virtual currencies and offers by channel:

Android Example Code:

Apmetrix.logEvent(Apmetrix.CustomEvent.USERS, "User Action", "Offer", "location", "#Amount");

iOS Example Code:

[Apmetrix logEvent:USERS_TABLE andDimensions:@"User Action", @"Offer", @"location", @"#Amount", nil];



USER ACTION = "selected", "abandoned", "completed" or any action that the user did.

OFFER = "primary currency $1.99", "secondary currency 500 gems", "Weekend Sale 30% Off Offerwall" or any other item that the user selected.

LOCATION = "main menu", "level 1", "prompt screen" or any information you like on where the actual event occurred.

AMOUNT = The amount of the in-app purchase such as $1.99, $4.99 etc.  Don't forget this is a metric and requires the # sign as part of the variable.


EXAMPLE; Tracking various events for a racing game:

Android Example Code:

Apmetrix.logEvent(Apmetrix.CustomEvent.USERS,"Car Status", "Type of Race", "Track Name");

iOS Example Code:

[Apmetrix logEvent:USERS_TABLE andDimensions:@"Car Status", @"Type of Race", @"Track Name", nil];


CAR EVENTS = "started", "completed", "abandoned", "crashed" or any action that the user did during the race.

TYPE OF RACE  = "time trial", "main race", or any other type of race that the user selected.

TRACK NAME = "le mans", or any location where the actual event occurred.


EXAMPLE; Tracking various user events from social networks:

Android Example Code:

Apmetrix.logEvent(Apmetrix.CustomEvent.APPS, "Activity", "", "Social network");

iOS Example Code:

[Apmetrix logEvent:APPS_TABLE andDimensions:@"Activity", @"", @"Social network", @"", nil];


ACTIVITY = "logged in", "sent friend request", "liked", "commented" or any other action related to a users behavior.

SOCIAL NETWORK = "Facebook", "Pinterest" or any other social network where the event occurred.


EXAMPLE; Tracking various weapons, spells and other user events in an action or role playing game:

Android Example Code:

Apmetrix.logEvent(Apmetrix.CustomEvent.APPS,"User Action", "Object","Location", "#Value");

iOS Example Code:

[Apmetrix logEvent:APPS_TABLE andDimensions:@"User Action", @"Object", @"Location", @"#Value", nil];


ACTIVITY = "attacked", "threw", "bought", "sold", "talked", "healed" or any other user action performed in the game.

OBJECT = "skeleton", "weapon", "magic spell", "character" or any other object the action was performed on in the game.

LOCATION = "level 1", "dungeon", "inventory screen" or any other location you would like to track on where the event occurred.

VALUE = "damage inflicted", "amount", or any other value you wish to track along with the event - OPTIONAL (Use the # in front of the variable if a metric otherwise it will be treated as a dimension and not an numeric value.)


EXAMPLE; Tracking virtual currency flow in your game or app:

Android Example Code:

Apmetrix.logEvent(Apmetrix.CustomEvent.OTHER, "Session", "Currency Type", "", "#Currency Amount”);

iOS Example Code:

[Apmetrix logEvent:UNGROUPED_TABLE andDimensions:@"Session", @"Currency Type", @"", @"#Currency Amount”, nil];



SESSION = "start", "end" or any other action where you want to log the amount of currency you are tracking.

CURRENCY TYPE = "Primary Currency", "Secondary Virtual Currency", "Gems", "Diamonds", or any other type. 

CURRENCY AMOUNT = The actual amount your users have at the beginning or end of the session.  


Note: These are for example only and you are not limited to using this or any structure in sending custom events.  Simply replace the custom tags listed with your own game or app variables which occurred at the time of the event.  If there is no data in a particular field, type an empty string “” in the function call. Terminate the list of parameters with the word nil.

This method returns an int value to indicate the status of the function call and will equal one of the following:


Successful operation.


Function call was ignored because there was not an open session to log event data to.


Operation could not be completed due to a database or server error causing internal buffers to reach their maximum capacity.  Check the log files for information on the specific error.


Returned if the call to initWithDataset() had an invalid dataset or unifier.  


Operation could not be completed because of some other error.  Check the log files for information on the specific error.


Have more questions? Submit a request