Best Practices

Well Structured Events

When constructing your Upsight Events, keep in mind what options a user can choose, and what insights you can glean from tracking that specific user action. Is it a point in your app that can determine engagement? Will measuring this event aid in further app development? Will tracking these events increase monetization or retention? Keeping these business requirements in mind while creating Custom Events will help you ask the right questions, and ultimately help improve your app.


Upsight organizes events in a hierarchy with 3 separate subtypes (st1, st2, and st3) and a name (n). There are 3 separate subtypes and a name within the hierarchy. This method allows us to store and organize data in an efficient and logical manner that is quick and easy to interpret. An example would be:

  • Event Hierarchy: st1 > st2 > st3 > n (st4)
  • Example Hierarchy: Purchase > Buy > Small_Bundle > Complete

Each Upsight Event is referred to as a unique custom event type. A unique custom event type can be populated with just the n parameter. This means that the st1, st2, and the st3 are not necessary in order to create a unique custom event type. A good example is to create a custom event called “app_opened.”. This event would just track a user opening the app, and no st1, st2, or st3 is needed.

However, if you have two Custom Events with the same n parameter but different st1, st2, or st3 parameters, these will be counted as two unique custom event types. The following are examples have similar structures but are all considered unique Upsight custom event types:


Note You are allowed to create up to 32,000 unique Upsight Event types, but 10,000 unique Upsight Event types is the suggested limit for an optimal dashboard experience.

Below is a description of the Upsight Event schema as listed on the Upsight Events

Subtype 1st1NoPrimary folders that will appear under All Events.friends_request
Subtype 2st2NoSecondary folders that are contained within the st1 primary folders.united_states
Subtype 3st3NoTertiary folders that contained wtihin the st2 secondary folders.facebook
NamenYesName of each unique custom event. Name is the only required parameter of a custom event. There can be multiple unique custom events with the exact same name, if they are within different st1, st2, and/or st3.sent
ValuevYesWhen a custom event has a monetary value attributed to it, the exact value without decimals can be passed. The largest number we can track is a 32 bit integer (i.e. 2147483647.300
LevellYesIf users of your app progress through different levels, you can pass the level they are on when firing the event.3
JSON DataJSONNoJSON data can be thought of as the "wildcard" data. Any information you need to pass for a custom event that is not already included in other parameters can be passed as a string in the JSON parameter. (e.e. latitude/longitude, coin balance, session number, etc.)

Note JSON data can only be accessed via Upsight's Data Mine tool, which is an Enterprise Level feature. It is still advised that you pass important information in the JSON (in case you ever turn on Data Mine in the future, your data will be there).
{"coin_balance" : "500"}

Note The event name, can be up to 31 characters long, describing the event. Valid characters are limited to a-z, A-Z, 0-9, -, and _.

Utilizing the Value Parameter

The v parameter is meant to hold a value for your Custom Event. With the v parameter, we suggest for you to structure your hierarchy with a common value type. For example, if your unique Custom Event type is an in-app purchase bundle for gems then don’t include coin credits within that specific structure.

In addition to viewing events by count, you can toggle the y-axis on the dashboard in the Event Details and Event Timeline sections to view the v parameter.

Note The v parameter will be aggregated on the y-axis.

Utilizing the Level Parameter

The l parameter is meant to hold an integer between 1 and 255. This parameter can be used to represent different video categories or coupon offerings, as well as player levels or map levels.

Additionally, you can toggle the x-axis of the Events Distribution section of the dashboard to view the charts by the l parameter. This is an important feature to keep in mind when constructing your events. Viewing a chart with the l parameter on the x-axis adds functionality and flexibility to the dashboard.