Custom Event Design

When designing metrics the core task involved is the design of the underlying data. This task is not only how the data is being transformed in the data visualizations and aggregated data, but also how to design the data streams that gear up all of them. In this article we will focus on how to design events and what are the related best practices.

In Omniata all data is received in REST format (Representational State Transfer). Below is an example of a REST formatted event.


The events are sent to Omniata either through SDK or with a server-to-server integration. With proper integration, Omniata SDKs ensure that events are send correctly to Omniata. With server-to-server integration, more considerations need to taken to ensure high data quality.

Event Structure

Omniata has three main events that are needed to power the platform. These are:

  • om_load
  • om_reveneu
  • om_user

om_load is send when the app is opened or comes to foreground. It is used tracking users sessions and when the user was activity and country information based on user IP address. This event gears up all standard engagement and retention metrics.

om_revenue is send when an in-app purchase has been made. The event indicates the amount of purchase and the currency used. This event gears up all monetization metrics.

om_user is an optional event that focuses on demographic information. The information passed in this event includes country (if needed to be reset), gender, and date of birth.

As standard events are described in detail elsewhere, let’s turns our attention to custom events specific to your app. The structure of a custom event is similar to the standard event. The following parameters are needed for ANY type of event:

  • api
  • uid
  • om_event_type

The om_event_type indicates which event is being send. For example, this could be you custom event ‘action’. All of the other parameters can be freely defined to match your exact use cases. The remainder of this article will focus on best practices in designing custom events and the related parameters and their values.

Custom Event Examples

To start off consider the following event as a good example of event design:


Why is this a good example? Each parameter allows you to focus individually on one theme. You can analyze different actions taken, slice it by the target of the action, assess the average cost of taking the action, and evaluate what unit of in-app currency was used. If needed you can combine any other parameter together to provide even more insights. Having several parameters with unique values allows you to flexibly model your data.

Now consider the following event:


Why is this a bad example? There are several design flaws here. First, the name of the event is unclear and would most likely require a separate background document to reveal its actual function. Having informative naming convention will be very helpful especially if you have several people working with Omniata. Second, the action parameter value consists of several values. Fitting everything into a single value makes it difficult to assess each of them separately as this will require advanced data modeling with Lua. The best practice is to split the value into different values with new parameter names. You can always combine them again and with much more flexibility. Third, assigning a boolean value to a parameter that could easily be a value on it’s own. This approach will make your events very long, and a more efficient way is to assign (in this case) ‘gold_coin’ as a value for parameter ‘cost_type’. Fourth, it is easy to forget the right order for parameter name and parameter value. It should be parameter_name=parameter_value; not the other way around.

Check List for Custom Event Design

Above we covered some good and bad examples. In the following, we aim to provide a more comprehensive list of aspects to consider. These are drawn from working with a wide array of customers with specific use cases.

Order and naming

  • First the parameter name, then the value (parameter_name=parameter_value)
  • Use informative parameter names (helpful when you have many users)
  • Remember that parameters and their values are case sensitivity

Event frequency and length

  • Optimize event frequency per user
    • Start with Omniata standard events (the ‘om_’ events)
    • Then add core custom events of the app
    • Finally add events that you find useful
  • Consider the length of the event (Omniata hard limit for event length is 1900 characters)
  • Consider the length of the parameter value (Omniata hard limit for parameter values is 255 characters)

Custom User Attributes

Remember to use custom user attributes (modeled through Custom User Fields). By using custom user attributes there is no need for sending same parameters with every event. For example, if you aim to visualize revenue per user level, you can send an event that sets the level value (… om_event_type=user_level, current_level=4 …). This way you do not need to send level information with every event, which optimizes your events to a great degree. More information on custom user attributes can be found here.

Custom Event Design Process

We are often asked to about tips on designing custom events. There is no single best practice for doing that, so the following approaches are only alternative perspective on event design. (Also check this blog).

One can think of every custom event as a sentence. There is a user involved (represented by ‘uid’ parameter) making a specific action (event type ‘action’), which in this case is building (action type ‘build’) a house (action target ‘house’). The cost of this was 500 (‘action_cost’) and it was paid in gold coins (‘cost_type’). The key is to think of the sentence in small fragments. This will lead to situation where you have several options for flexible data modeling.

Of course you can start from the other way around where you think of the required data visualizations and the use cases needed to be covered. Doing the design from this perspective requires careful design of metrics to be covered and design of parameter based data fields. This will then be translated to requirements for the events.

Both approaches are valid, and complementary. Both will typically lead to same outcomes.

Integrating Custom Events

Integrating new custom events follows the process of integrating any other event. You should use the Event Console in the panel to add the new events and parameters to the data model. You can find more instructions here.

This article was last updated on October 28, 2015 21:19. If you didn't find your answer here, search for another article or contact our support to get in touch.