App event markup from scratch: a guide from the top retail mobile app

Subject (or actor) is the source of the action. For instance, it can be a user or the system. A user can be the subject when they perform a click action, and the system — when it returns an error.

For example, if the user clicks a button: "user_space_click_button"

Space refers to the team that’s responsible for a specific marked up scope within the app. This is relevant for apps where different parts of the app are supported by separate development teams, like in the Pyaterochka app. This parameter helps you identify whose events you’re analyzing and who to contact if something goes wrong..

For example, if the user clicks a button within the scope of the Delivery team: "user_delivery_click_button".

This works similarly for system actions. For example, if the app shows a screen after you open it: system_delivery_view_screen.

In a table, these would be recorded as follows:

This is the minimum tracking data necessary to answer four key questions:

1. What happened?
2. What did the event affect?
3. Where (within what team’s scope) did the event occur?
4. Who triggered it?

The "Screen" parameter, which indicates the specific part of the app where the event occurred, is required for implementation. This parameter allows you to distinguish between events, such as clicks on buttons that have the same name (for instance, "Accept") but are located in different parts of the app.

Optionally, you can implement the "Section" parameter, which represents a section containing multiple screens ("Screen").

Together, these parameters allow you to identify exactly where in the app the event took place. And we stress again: while "Section" can be an optional parameter, "Screen" is always mandatory. Without it, the event’s location will be lost.

For quicker filtering and, most importantly, to facilitate communication with the developers, we’ve also introduced the mandatory "event_id" parameter. This parameter records the unique ID of the event, which is expressed in a consistent lowerCamelCase format based on all other parameters. For example: logTapUser…

Markup rules

Rules are necessary for maintaining consistency and providing additional control over the transmitted data. Here are some of the important rules used at Pyaterochka:

1. Do not pass personal data in events and event parameters.
2. Only use lowercase characters in all names. Use underscores to separate words (snake_case).
3. Use Latin characters. Names of events, parameters, and values must be in English.
4. For event and parameter names, use vocabularies approved within the analytics team.
5. All new names must first be coordinated with the team.

Vocabularies

It’s crucial to maintain consistency in your event markup. To make things clearer, you should define and document your event names in a markup vocabulary.

Vocabularies not only help you avoid duplicate entities, but also allow you to determine the number of unique names at a glance, can be converted to a struct, and enable filtering raw data by pattern to identify names that are written in a different format.

Parameter names

Parameter names provide information about the event, so in most cases, the more parameters an event has, the better. However, in some trackers, the same restrictions that limit the number of unique names also apply to parameters.

The framework described above defines 6 required parameters: "object", "subject", "space", "section_name, screen_name", "event_id". Let’s take a closer look at the "Object" parameter.

The "Object" parameter can have the following values:

• button
• screen
• banner
• widget
• warning

You can distinguish different objects, such as buttons, by their names. While you could append the name to the "Object" parameter using an underscore, that would go against the very logic of using parameters, as that would expand their content. It makes more sense to pass the name in a separate parameter, such as "name". There are three ways to do it:

1. object_name
2. class_name — button_name, screen_name
3. name

The third option ("name") is acceptable, but it doesn’t specify what the name refers to, which hurts the event’s readability.

To keep within the limits, use the first option, "object_name". We, however, use "class_name", sacrificing limits for better readability.

Parameter values

There are no restrictions on the number of possible values that your parameters can have. It’s important to identify the object of the action, such as button, icon, or widget. To do this, compile a vocabulary defining the possible object and subject values.

Object vocabulary

Previously, we’ve defined two segments: "user" and "system". Although "system" can be narrowed down to a specific microservice, such granularity is difficult to maintain. That’s why we’ve chosen to simply use "system".

Interim results

The "Action_Object_Subject_Space_Section_Screen" framework allows you to generate an event schema with the following format:

Before you begin marking up your events, you need to make some preparations:

1. 1. Find out the full names of the people responsible for different parts of your app or site, such as the product manager or product owner. List them in a dedicated section of your internal documentation. This table can be structured as follows:

1. Markup
2. Review
3. Revisions
4. Preparing terms of reference for implementation
5. Acceptance of the finished work

Event analysis workflow

The analysts at Pyaterochka use a Google Sheets template for marking up events.

This template includes three tabs:

1. Screens/Widgets: Descriptions of all screens and widgets.
2. Screen: The app screen or site page that is being marked up.
3. EntryPoint screen: The names of the banners or widgets in the app that lead to that screen.

The Home tab is a screen. Here’s what it looks like in the Pyaterochka app.

The header includes two fields with the screen’s URL in Figma and in Confluence. Figma contains the current layouts of the app, while Confluence contains the markup that was implemented based on this table.

The "Date added…", "Android/iOS status", "Implementation priority", "Subject", and "Space" fields are self-explanatory. The "Index" field allows you to reference events by a specific index, rather than by a row in the spreadsheet.

• Event: The action taken
• Event description: What object was affected and how

The required parameters — "Object" (string), "Subject" (string), and "Space" (string) — are appended with two additional parameters:

• Screen_name
• Section_name

The table above shows that the Settings section includes a number of screens. One such screen is Notifications. The Example team is responsible for both this section and this screen.

Here’s how the Pyaterochka app’s main screen is marked up:

The first event that we can describe is a screen view.

Event:

• What happened? — A view

Parameters of this event:

• What was viewed? — A screen
• Which team is responsible? — Growth (team name)
• Who performed the action? — The screen was displayed by the system
• Where in the app did the event occur? — In the main screen section
• On what screen? — Main

Additional parameters (optional, only included as an example):

• referrer: The previous screen
• load_status: Screen load status. Can be successful or unsuccessful (returns a specific error)
• load_time: Screen load time

The second event that we can describe is a tap on a widget with a barcode. This is a loyalty card widget. It belongs to the scope of a different team, the Loyalty team.

Event:

• What happened? — A tap

Parameters of this event:

• What was tapped? — A widget
• Which team is responsible? — Loyalty (team name)
• Who performed the action? — The tap was performed by the user
• Where in the app did the event occur? — On the main screen
• On what screen? — Main.

Additional parameters (optional):

• widget_name: The name of the widget.

What’s next

By marking up all elements on the Main page, we can produce an event table (like the one in the template) that is then sent to the product team for approval. Once everything is approved, the table is used to prepare terms of reference for implementation by the developers. In our case, it looks like this:

In summary, markup involves the following steps

1. Choose an alphabet.
2. Choose a framework.
3. Write the rules.
4. Compile a vocabulary.
5. Name the parameters.
6. Add the parameter values.
7. Prepare the object and subject vocabularies.
8. List the people and teams responsible for different parts of the app or site.
9. Distribute the app’s screens within the analytics team.
10. Prepare the markup structure.
11. Conduct a review.
12. Make the necessary revisions.
13. Prepare terms of reference for implementation.
14. Carry out the acceptance of the finished work.