Events

Overview


The Upsight dashboard receives its data in the form of 6 separate messages: APA (Installs), PGR (Engagement/Retention), CPU (Device Information), MTU (Revenue), UCC (Attribution), and EVT (Upsight Custom Events).

Upsight Custom Events (EVT) are different from all the Acquisition/Install, Engagement, Retention, and Monetization metrics you can access on the dashboard. These events allow you to define, track, and quantify user-behaviours specific to your app. With Upsight Events, we can track almost every user action from how often an item is purchased to the number of times a user messages a friend. In addition, all of this information is presented in easy-to-understand charts that can be adjusted, filtered, and pinned to any custom dashboard.

Interface

Accessing Events


Events is located in the Report tab in the Upsight Analytics dashboard. Follow the steps below to access it:

  1. Click on "Reports" in the menu bar at the top of the dashboard.
  2. Select "Events" from the navigation table on the left. You can then select "Event Details" or "Event Timeline" from the submenu.

Events Button

Interface

Viewing Custom Events


To view these events on the dashboard graphs, we use the Event Selection portion of the Event Explorer tool found in the Events Detail section. In the Treeview, find the Event or Events that you would like to analyze in the Event Navigator and transfer the Event from Available Events table to the Selected Events table by using the double arrow buttons. We can also choose different Events from different subtypes to have a comparative analysis.

Event Explorer - Tree

We can also use the Search view instead of Tree if we know the name of the event we are looking for.

Event Explorer - Search

Alongside the Event Explorer Hierarchy option is the Pivot option. The Pivot option gives us the flexibility to consolidate a subtype and view it on its own. For example, we can view all Events that occurred for a level 1 subtype, such as Purchases, or we can view all Events that occurred for a level 4 sub-type, such as Completes.

Event Explorer Pivot

When you’ve placed all the Events you would like to view into the Selected Events table, hit Apply.

By clicking Save, the Selected Events will be saved into a bundle. Once saved as a Bundled Events, you will be able to select the bundle to view these Events in a graph instead of having to select each Event individually.

Apply and Save Buttons

Interface

Deleting a Custom Event


Upsight will never delete any of the data you send to us. Therefore, there is no delete option for Custom Events.

In the case where there are old events, incorrect events, or events you simply don’t want to see on your dashboard, use the Manage Events feature, located on the lower right section of the Event Explorer tool and next to the Save and Apply buttons.

Save and Apply Buttons

In the Manage Events widget, uncheck the custom events that you do not want to see on your dashboard. Click Save to keep your new events settings. Also, we will still be collecting data for the events you’ve unchecked, so simply check the box again if you would like to view the events in the future.

Manage Events Widget

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.

Best Practices

Parameters


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:

st1st2st3n
friends_requestfacebookunited_statessent
friends_requestunited_statesfacebooksent
friends_requestunited_statesfacebookreceived
friends_requestfacebook(blank)sent
friends_requestunited_states(blank)sent
(blank)(blank)(blank)(blank)

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

NameParameterRequiredDescriptionExample
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 _.

Best Practices

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.

Best Practices

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.

Understanding Results

Events


The Upsight Events module is broken down into two sections:

  • Event Details
  • Event Timeline

Event Details

The Event Details give you an in-depth view into how often any custom event occurs within your app. This view shows a total count of events triggered. You will also be able to view the percentage of Events per Unique user and the percentage of Event Distribution for the selected time range.

Note Even if instrumented in your apps’ code, Events will not display on the dashboard until a user triggers the actual in-app event.

Event Timeline

The Event Timeline lets you compare changes in Upsight events over time, session length, and use. In this section, we can view 3 charts:

  • Percentage Event Distribution Timeline
  • Total Event Distribution Timeline (Normalized)
  • Total Event Distribution Timeline

This section is extremely helpful in seeing the percentage breakdown of a group of similar events triggered within the selected time frame. For example, it can help answer questions such as "What main menu option was chosen most last week?" or "What purchase package generated the largest total value this month?".

Note In this section, you can change the x-axis by session, time since install, time on app, and level. The Level is equal to the integer passed to Upsight in the l parameter.

Understanding Results

Funnels


In addition to the Events module, Upsight has the Funnels module that also uses Upsight Events to populate its charts. But instead of viewing events as counts, Funnels show how many users triggered the event. For example, the Funnel can show 10 users, but those 10 users could have triggered the specific event over 100 times each during the selected time period. There are two types of Funnels - enforced and unenforced.

For additional information on Funnel setup, please see the funnel section.

Enforced Funnel

The enforced funnel will allow you to analyze a series of events in a logical path analysis, not to be confused with user path analysis. In order for a user to appear in one of the funnel steps, the user must have completed the previous steps of the funnel in no particular order. With funnels, you will see the number of users who started with the first event and how many of those users reached the final event of your funnel.

Note A user does NOT have to complete the selected events in order. For example, a user can reach event D by completing the events as A, B, C, D or C, B, A, D.

Unenforced Funnel

The unenforced funnel view will allow you to analyze user behaviour when a user is given multiple choices after an initial event. It’s a powerful tool that unveils the most popular path users take within your app. For example, unenforced funnels can help determine the most popular item of your in-app store or what section of your app users travel to most from the main menu screen.

Understanding Results

Building Custom Events


  1. Build out which primary folders (st1) you would like to organize your custom events by. This is based on how you would like to slice and dice your data.
  2. Within each st1 folder, add additional levels of hierarchy with st2 folders and/or st3 folders or skip straight to the unique events without using secondary or tertiary folders This depends on how you would like to organize and view your events.
  3. Add additional information you would like tracked to each custom event. Whether it will pull in data into the value and/or level parameters as well as anything you would like to be passed in the json parameter.
  4. Integrate your custom events code into your app code with help from the Upsight Integration docs.
  5. Start building custom dashboard charts using either a count or a value of any and all the custom events once the app is live and events have been fired.

Optional Once all custom events have been organized using the template, open the Event Designer tool under the Help section of the Analytics dashboard. By adding your Custom Events into the Event Designer, you are able to generate the code needed to implement your custom events into your app code without having to write the code from scratch. Be sure to also check the box “Include as a funnel step” if you plan to use the event in the funnels tab of the dashboard. Checking this box will automatically add funnel steps to your dashboard. This step is to be completed prior to Integrating your custom events code into your app (step 4).

FAQ


Can I filter the charts in Event Details? Can I apply two filters there like I can in other parts of the dashboard?

Event details can be filtered like other charts in the dashboard provided that there is only one data set selected. If charts are showing multiple data sets, filters will not work. However, if there is only one data set, multiple saved filters will work just like in other parts of the dashboard.

Can I look at these charts in a custom dashboard?

For any of the charts that have a “pin” button in the top right corner, simply click the pin button to pin the chart to a custom dashboard.

Can I filter the charts in Event Timeline?

Charts in the Event Timeline can be filtered, however, unlike in other parts of the dashboard it is not possible to add multiple filters.

What is the difference between the “Total Event Distribution Timeline” and the “Total Event Distribution Timeline (Normalized)” charts?

The normalized distribution is the total count divided by the size of the buckets so that the various columns can be compared on an “apples to apples” comparison since the chart progresses by including multiple sessions as numbers increase in order to view a greater amount of data.

What is the “Percentage Event Distribution Timeline?"

The percentage event distribution allows you to visualize events that are happening at each stage as a percentage of the total events that occur at that stage, whether it’s by level, session or time since install. This allows customers to better understand what behaviors users are practicing as they progress through the game or app.

Can I look at the Day 1 retention for all user who have triggered a particular custom event?

No, custom events cannot be cohorted back to a particular install date. In order to get this information, you need to run a query in Upsight Data Mine.

What's the difference between plotting events by value versus plotting by count in the Event Timeline?

If you want to track the total value of monetization or another quantity based purchases to see how much an in-app good (e.g. coins, health, etc.) is being purchased at various different stages of a game, then it might be useful to look at the value parameter rather than just the count.

What is Bundled Events? Why would I use that?

Bundled events are a set of saved events. By saving new bundles you can easily access all the events that you want to look up at once and easily switch between different groups of events that you want to evaluate.

What is the difference between "time on site" and "time since install" under filters in the Event Timeline?

Time since install is the total elapsed time since an install message was sent. Time on site only counts the amount of time spent in the application and/or site (calculated using PGR and EVT messages).

How often is data processed for custom events?

The data is processed hourly and you will see updated data on your custom events on an hourly basis.

Can I get custom event data from your processed data API?

Yes, please see the Processed Data API Custom Events section for more information.