Defining descriptive events and properties
When designing good event structures it’s important to create a common understanding of meaning between the data designer, the data consumer and the instrumenting developers. This is for example to avoid duplicates of events and properties and an event being sent at different times between platforms.
A few things to consider:
Naming conventions for events and properties
When defining events and properties, Avo recommends sticking to a naming convention and using the same words in all definitions. Consistency is the key to avoid duplicates and be able to easily find events and properties in your analytics tool. When signing up to Avo, example events and properties are created for you according to the industry chosen - with our recommended naming convention.
The Avo Naming Assistant helps you to avoid duplicates and be consistent in your casing and when selecting or changing event and property names. Note that some analytics tools require specific casing for events or properties.
Events
A naming convention for events is comprised of three parts; 1/ order of objects and actions, 2/ tense and 3/ casing. Avo recommends the following convention:
- Order of objects and actions: object-action
- Tense: past tense
- Casing: title case
All other naming conventions are supported and no matter which one you choose, we recommend that you try to stick to it.
Examples of events in the recommended naming convention:
- Signup Completed
- Cart Updated
- Message Sent
- Game Started
Properties
A naming convention for properties is not as predictable as for events. As with events, casing and using the same words to describe things is important. We also recommend to be explicit about the property names to avoid misunderstanding to which value they describe.
Event property examples
For example when creating a property that describes the number of passengers many want to simply name the property “Passengers”. But without context it’s hard to understand what the property means; is it number of passengers, is it a list of all the passengers or is at a boolean indicating if passengers were selected or not? Therefore we recommend explicitly naming the property either “Number of Passengers” or “Passenger Count” - or have a convention to shorten all number of properties to something like “Num Passengers”.
Another example is something that has perhaps a name, ID and a type. It can be tempting to create a property on the “Purchase Completed” event with the simple name “Product”, as you want to know what product the user was purchasing. In that case it’s hard to know whether the property is describing the product name, it’s ID, the type or something else. There for we recommend naming properties explicitly what they refer to;
- “Product Name”
- “Product ID”
- “Product Type”
User property example
Often user teams like to track event and user properties that have the same name. We generally recommend avoiding that because of two reasons:
- It’s confusing to have two properties with the same name in many analytics platforms and one can be mistaken for the other, leading to a chart with not the desired results
- Event and user properties do not describe exactly the same value. Event properties describe the exact value at the time that the event was sent, but user properties generally describe the latest value.
- For example on the “UTM Medium” might be “Facebook” at the time that the user performed the “Signup Started” event and the user property would then be updated to “Facebook” as well. But when the user come back, the “UTM Medium” property can be a totally different one and the user property would be updated accordingly, for example to “Google”. In this case, the user property is describing the latest UTM Medium and we would recommend naming the user property accordingly: “Latest UTM Medium”.
Descriptions for events and properties
Events and properties with a descriptive name get you far to create a common understanding on what they mean. However, often the name itself does not contain all the information required to know exactly when the event is sent or what the value of the property is. Then descriptions are useful, and we recommend adding descriptions to all new events and properties to prevent misunderstanding.
Events
For events we recommend adding a description to an event with all the information required for a developers to trigger an event by the same user action for all code paths, platforms and products.
For example for the “Purchase completed” a good description would be: Event sent when the client receives a successful response when a user has completed a purchase.
This is to avoid a situation where for example an Android developer sends the “Purchase Completed” event when a user taps a purchase button and an iOS developer sending the same event when the client gets a response from the server about the purchase being successful. In this case iOS would include all purchase attempts, successful or not, while Android only includes successful ones.
Properties
For properties we recommend adding a description to supplement the event name - that describes exactly which value is in the property so that the developers know what value to send and the data consumer knows for sure what it means.
For example for a “Search Result Position” property on a “Search Result Clicked” event the property name is pretty descriptive on what it means, but still further information is required to know exactly which value it’s referring to. A good description in this case would be: Which search result the user selected. 1 for the top search result, 2 for the one below and so on.
Property constraints
Property constraints are very useful to ensure that the correct spelling or allowed numerical values are sent with the event.
We recommend using property constraints whenever possible, specifically in cases when:
- Limited set of strings are possible for the property.
- “Authentication Method” can only be “Facebook”, “Google” or “Email” for all code paths, platforms and products. No risk of Android sending “facebook”, iOS sending “Facebook” and web sending “FB”
- Numerical value can not be lower and/or higher than some value:
- “Search Result Position” can never be lower than 1 so it has a minimum value 1. No risk of iOS starting count on 0 and Android on 1 or accidental negative values.