Naming Convention: How to name tracking events

Read time: 3min

Who is this for

This blog is for individuals and teams, who feel they need a naming system for their tracking events but are not sure what makes a good one.
I will share a ready-to-use naming convention (if you are in a hurry), a guide to find a tailored naming convention for your team (if you have more than 120 seconds), and some tips on how to really solve your problems with a naming convention.

I will not talk about why you need a naming convention in this blog. That deserves its own blog.

The quick one

For a quick solution suitable for most teams, here's how to name your events in platforms like Amplitude, Mixpanel, Pendo, mParticle, Rudderstack, Segment:
page_location.ui_component.action_past_tense
For example,
web_product_detail_page.add_to_cart_button.clicked


The tailored one

If you want a solution that tailors better for your team, here is how to figure this out yourself in 5-10 min:

Step 1: Figure out the 3 main sections

Page Location: This should be the screen/page of your product. 
UI Component: What is the UI the user is interacting with? 
Action: What action is the user performing? This can be explicit action like clicked, or implicit action like loaded (the page with their browser)? Choose between past tense and present tense. 
Be verbose here; this is where you define the specifics that will save huge time afterward.

Step2: connecting these 3 pieces

Cases:
Using all lowercase is usually safer as some analytics tools auto-convert everything to lowercase. However, you can use camelCase or PascalCase if case sensitivity is not a concern.

Connectors: 
Choose from:

• underscore '_'
• dash '-'
• dot '.'
• no explicit connector (e.g., camelCase, PascalCase.
• 'justlowercase' is not recommended as it is hardtoread).
• space (as a programmer, I do shy away from this option).

Choose a connector for words within a section: The example above uses underscore “_” to connect words within a section. e.g. “add_to_cart_button”
Choose a connector between sections: The example above uses dot “.”

Step3: put these all down in a simple doc/message, share it out

We have completed the “naming” part of naming convention, now is the time for making it a convention.

Why do I need to do this?
Because it is not a naming convention until most of your team members accept it. Without accepting it, engineers will implement event tracking in malformed shapes, analytics tasks will waste time on questions like “what does this event means?” and “what is that new event called?”

How do I do this?
Honestly, it is not as hard as it sounds:

1. Put down the naming convention into a 1-page doc, or a short message. Be clear, be easy to understand and to follow. Here is a template:

Tracking events naming convention:
Connect these three section using dot “.”:
page_location: e.g. web_home_page, ios_home_screen
ui_component: e.g. cancel_button, home_menu
action_past_tense: e.g. loaded, clicked, hovered, scrolled
Use underscore “_” to connect words within each section.
For example, web_product_detail_page.add_to_cart_button.clicked
Question? Ping @someone or #some-channel 

1. Stick them to the top of a Slack channel or save this document to an obvious place.

2. Find some 5-10 minutes in a team meeting to talk about this, get everyone look at it. Address concern if any. Before this discussion, it could be helpful to take some minutes to get supporters (e.g. buy-in from tech lead) in advance if necessary. 

Common questions related

Events separated vs. aggregated?
There are multiple buttons located in different places in UI doing similar things, should I name them the same event?

Default to separate events. Aggregate events only when these events are eactly the same, just at different location. Keep a side note or tracking plan for similar events to group them together if needed. 
Some downstream tools might not support properties; Saving key information in a property can lead to problems there. It will also be easier to manage when things grow. 

Server-side vs. Client-side?
Should I log an event in the frontend or backend?

Intent on frontend client side, action on backend server side. 

Sign up to receive updates of future blogs, where I will talk about these two problems in more detail.

Originally posted on getseal.co