In our practice, we often encounter the same issue: companies collect a vast amount of analytical events, but these are often poorly documented or not documented at all. This makes it difficult to understand what and how things work, especially for newcomers.
Working with poorly organized data makes us realize the importance of proper naming and documenting of analytical events. Essentially, this is the foundation for obtaining accurate and useful data, which ultimately helps make informed business decisions and generate profit.
In this article, we will cover the 5 main principles we follow when working with events.
1. Centralized Event Documentation
Create a centralized place for documenting all events (whether it's Notion, Confluence, a Google document, or an analytics system with a built-in tracking plan) and use it as the single source of truth.
It often happens that analytical events or their changes are only described in development tasks or in documents of different product teams. Collecting everything together takes time for an analyst. An experienced specialist keeps everything in their head, but if a new employee joins, there are more questions than answers. Especially if the questions concern tasks at the intersection of several product teams' activities.
A single source of documentation allows all teams to work with it, effectively develop, and make changes. The structure can be as convenient for you or as provided by the analytics system.
Usually, we highlight three or four blocks in such a document:
- Data Policy: The rules and principles for working with events (the same as in this article). After reading this block, there should be no questions on how to create and read events. Our task here is to leave no room for imagination for the team and to standardize everything.
- Events: A list of events with a detailed description of each, so there are no discrepancies during development or analysis. Usually, we indicate the name, description, and list of parameters. You can add the status and implementation date/release number.
- Event Properties: A reference of event parameters with detailed descriptions of each parameter. Usually, we indicate the name, description, necessity, type, and possible values. More details in point 5.
- User Properties: A reference of user parameters. The principle is the same as for event parameters.
2. Consistent Notation
Choose a single naming convention (notation) and stick to it.
One of the most common issues in analytical data is naming problems of events, parameters, and their values. Different teams (iOS, Android) or different developers may choose the notation at their discretion, which can lead to incorrect results in data analysis.
For example, one team implemented an event for one platform using snake_case, while another team used camelCase.
Another example is a parameter value that has been collected over several years as choose_and_play, ChoosePlay, Choose&Play, and ChooseAndPlay. Since possible values were not specified in the documentation for developers, each implemented it as they saw fit. The analyst has to click through or include all four values in the query instead of one. Fortunately, this point is already documented, and the analyst will not miss it during work.Moreover, a lack of data by platform is easy to notice. But if it concerns parameters and their values and different developers on the same platform, it will be much more difficult to do so.
Discuss with the team which notation to choose for events, parameters, and their values. This can significantly reduce the time for both development and testing, as well as analysis.
Below are the most commonly used notations:
- all lowercase: page view
- snake_case: page_view
- camelCase: pageView
- Proper Case: Page View
- Sentence case: Page view
You can choose different notations separately for events, parameters, and parameter values.
3. Structured Event Naming
Develop a structure for event names and name events accordingly.
For an event to be easily interpreted, it must be clear how it is written. For this, the team should agree on a standardized naming structure that all participants understand and follow.
It can be said that there is no perfect solution here. Everything depends on the initial tracking task: whether you want to cover all functionalities with events or track only the main actions. This determines the degree of event detail. Simply choose an approach that will work for you in the most convenient way.
Usually, the event name is a combination of the object name, the action performed on it, and, optionally, the event category.
Objects are typically buttons, forms, fields, or other website or application objects.
Action refers to the ways users can interact with objects: click, view, swipe, create, and others. Determine the possible list of actions in advance so that when creating events, you don't have to think about it. Also, think in advance about the action time used - click or clicked.
As a rule, we work with large projects where analytical events are used for many purposes, such as testing functionalities and conducting experiments. Therefore, over time, the event catalog can grow. If you do not plan to limit yourself to just the main 10–15 events, it is better to add a category to the event name. This will help you easily identify and group events.
As a category of the event, we use the name of the website page/application screen or the name of the functional block/feature. This list can also be determined in advance and updated as the system evolves.
The order in the name is also not so important. The main thing is to define it and follow it. If it is more convenient for you to indicate the action first in the event name, you can name it that way.
Examples: Product page view, Clicked Add to cart, products_search_product_click, Basket Add discount Click
4. Clear Names
The event name should be clear, understandable, and easy to read. It should reflect the event's logic without the need to study the development task.
In addition to the previous point, it remains to be added that the event should be easy to read and understand by everyone working on the website or application, not just those who are familiar with it. Often these are marketing analysts or newcomers who are just getting into the tasks. Categories, objects, and actions should not be general. They should uniquely define the user's action.
For example, do not use names like button clicked, as this is too general a name. As you can see, we immediately have the question of where the button was clicked and what kind of button it was.
You should not use abbreviations or specialized terms that will be unclear to the team.
And to conclude this point, clarity here is preferable to brevity. Of course, this rule cannot always be observed (hello, character limit 👋), so there must be a balance between detail and abstraction.
Another example. Do not use event names like message_5_shown - it is not clear what 5 is, which message was shown and where. Instead, you could use a more descriptive event like product_out_of_stock_shown. Here we have defined the event category - the product page, the object - the Out of Stock message, and the action - the message was shown. If there can be several messages on the page, you can define one event for them - product_message_shown, and specify the message text or its code in the parameter, if it will be possible to link the message codes directory later.
5. Unified Parameter Directory
Define a list of all event and user parameters, describe them in detail, specify possible parameter values, their necessity, and type. Reuse parameters in events.
Parameters are the context in which the event occurs. They enrich user actions with information and give a more complete picture of what users are doing on the website or application. For example, knowing the number of product view events is not enough for us. We would like to know which products users view more often or add to the cart, whether they perform these actions while logged in, and whether they have a paid subscription at that moment.
Therefore, it is important to determine which parameters you want to collect with each event to make this context clear. It would be unpleasant to find out that an event has been collected for a long time, but there is not enough data to solve the task at hand.
💡 If you have event categories, then the same parameters may
be applicable to these categories. For example, if it is an
order page, the possible context of all events on this page is
the order ID, its status, and the delivery method.The parameter name, like the event name, should be easy to read and understand. As mentioned in the notation point, issues with parameters and their values sometimes arise around their naming. So make sure this rule is applied here too.
Describe the purpose of the parameter as thoroughly as possible to avoid discrepancies.
For example, a parameter description like "message - message on the product page" can be interpreted differently by different developers: one will send the message text in the parameter, another the message code or ID.
Testers and analysts often have questions about whether a parameter is mandatory. It was not specified in the development task, and it is unclear whether it is a bug if the parameter is not in the event. To avoid such questions, specify the necessity for each parameter in the directory. If possible, specify the parameter type as well.
Similarly, questions often arise about why different sets of values are logged for a parameter: in some true/false, in others yes/no, in others 1/0. Somewhere the value can be indicated in English, somewhere in another language.
Help developers and subsequently analysts by creating a list of possible parameter values, if applicable. If there are many values, indicate which directory to take them from, an example, or the format of the value. This will ease everyone's work.
Example. Describing the parameter as "order_status - order status" is often not exhaustive. Different developers can interpret it differently: one will send Delivered, another Geliefert, and both will be right. But the analyst will have to work with this.
And last but not least: reuse the same parameters in your events if they answer the same questions. Before creating a new parameter, make sure that such a parameter does not already exist.
Avoid situations where a parameter product_id is logged in one event, and product in another, but with the same product ID value.
Conclusion
By following relatively simple rules for naming and documenting events, many analytics problems can be avoided even at the design stage. Additionally, any website or application tends to change and expand. This means that new functionality will appear, which will require tracking.
The benefits of a well-built event catalog and clearly defined rules for working with it will be felt by everyone, from developers to marketing analysts. It is a single understandable source of truth for the entire team. It can be used by non-technical specialists as well. And for development and testing, it will be a detailed technical specification.
We understand that sometimes developers and testers may not pay due attention to event analytics, as the proper functioning of the website or application is a higher priority for them. Therefore, one of the tasks of analysts is to make their work as easy as possible.
Another significant plus is onboarding new team members. Immersing in tasks will be much easier if there is a source at hand that answers all or almost all questions.
And finally, it is worth noting that collecting a lot of data is, of course, good, but first and foremost, events and parameters should be useful for analysis.
