Kontagent Documentation

Understanding Events and Subtypes

Important: The following sections detail important information everyone (both developers and non-developers) must be familiar with before diving into instrumentation. We recommend your team sits down together to clearly define and structure the events you wish to track before instrumentation is started.

To utilize our APIs and libraries, you'll need to understand what events are, how they are structured in Kontagent, and how you can organize them into a logical taxonomy.

Events

Users perform actions within your application, game, or website. These actions, which we call Standard Events, can be a common across any number of applications or websites, or a Custom Event that is specific to your application. As no one application is the same, Custom Events are a powerful way for you to define and track actions that make sense to you.

You’ll want to track events that are important and meaningful to your website or application. With Kontagent, you can use our APIs or libraries to track events for the most commonly performed user actions, or Custom Events for actions unique to you. Both types of events automatically include a timestamp of when the event occurred.

Standard Events may consist of:

  • a UID of the user who performed the event
  • a Unique Tracking Tag to correlate related events
  • a series of parameters that may be included to further define the event
  • a hierarchical category structure

Custom Events may consist of:

  • a name describing the event
  • a UID of the user who performed the event
  • a series of parameters that may be included to further define the event
  • a hierarchical category structure

Subtypes

You can develop a taxonomy by classifying and categorizing events by creating hierarchical categories for each event; this system places events into a series of hierarchical levels (called subtypes) to make them easier for you to identify and organize.

In Kontagent, events are composed of two components: 1) an event name, and 2) up to three hierarchical categories: subtype1, subtype2, and subtype3. Collectively, any unique combination of an event name and subtypes are referred to as an Event Type.

A simple example is an event of a user making an in-game purchase, where the user purchases a basic package of Facebook credits:

  • Subtype 1: monetization
  • Subtype 2: facebook_credits
  • Subtype 3: basic_package
  • Event Name: purchase

A more complex example of an event taxonomy is shown in the following diagram, with 3 different event types:

Although each Event Type shares a subtype1, they are unique due to unique subtype2, subtype3, and event name properties. This classification system is effectively a hierarchical tree structure. In the Kontagent system, the data would be defined as the following:

  • Event Type 1
  • Subtype 1: monetization
  • Subtype 2: facebook_credits
  • Subtype 3: basic_package
  • Event Name: purchase

  • Event Type 2
  • Subtype 1: monetization
  • Subtype 2: facebook_credits
  • Subtype 3: premium_package
  • Event Name: purchase

  • Event Type 3
  • Subtype 1: monetization
  • Subtype 2: buy_coins
  • Event Name: buy_basic

Use Cases To Avoid

As subtypes exist in a hierarchical structure, subtype levels must not be skipped when creating the subtype hierarchy. For example, there should not be an instance where Subtype 1 is empty and Subtype 2 is defined, or where Subtype 1 and Subtype 3 are defined and Subtype 2 is empty. Each previous subtype level must be defined before defining a subsequent subtype level. Failure to do so will cause malformed event data to be sent from your application.

Examples of malformed subtype hierarchies:

  • Subtype 2: empty
  • Subtype 3: Level 2

  • Subtype 1: empty
  • Subtype 2: Level 1

Inserting UID Into Subtypes

If you pass unique UIDs into subtypes, this will create a huge number of unique events and hamper your ability to get meaningful data from our system. While our system is constructed to handle massive event volumes, do not use user UIDs as a subtype.

Inserting Non-Dependent Strings Into Subtypes

  • Subtype 1: Color
  • Subtype 2: Garment

In this use case, if 100 different colors with 100 different garments were inserted, you will essentially create 10,000 different events! This will certainly hamper your ability to get any sort of insight. Remember, maintain event and subtype hierarchy at all times, and do not treat subtypes as independent variables.

← System Overview Previous Next Understanding Kontagent Application Instances →