-
Notifications
You must be signed in to change notification settings - Fork 7
Analytics Events Guidelines
- Events need maintenance (both on the client, and in our data warehouse), so in general, go for simple solutions, and don’t create events at all unless there’s a specific product question or metric that we intend to analyse. Don’t track events for their own sake.
- Fewer types of events is usually better. It’s better for consistency and easier to understand what’s available in the data if the list of overall events is short. We should aim to represent our event catalog using as few event types as possible, where it’s sensible to do so.
- Note that the mobile SDKs send events in batches for efficiency, so it’s usually not necessary to batch up events yourself to save battery.
- You should not have to read the code to understand when an event triggers, or what its properties are. Naming conventions, types, and comments in JSON Schema must be enough - it’s not just engineers doing analysis.
- Event names are in UpperCase and describe the action that triggered the event
- Property names are in camelCase
- Enum members are in UpperCase
We will maintain a cross-platform event schema using JSON schema at https://github.com/matrix-org/matrix-analytics-events. This schema can be used to generate client side stubs and potentially filter events when they’re sent to posthog.
Maintaining a schema is useful because -
- We can ensure events are defined the same way across platforms, when they refer to the same things, validating events on the client and server.
- We have a clear way to review event definitions as they are defined, to ensure they’re useful and going to stand the test of time.
- We have one place to go to as a reference for events, relying on description fields in JSON schema to document what events and properties mean. We can generate a human readable dictionary from schema which can be quickly reviewed by analysts.
We define a single Error event which should be used by default for reporting errors. Having a single event helps consistency, which means it’s easier to understand which events are available to analyse.
This event has properties
- domain which we can use to partition events and easily ask questions like “how many e2ee errors are occurring overall”
- name which is a enumeration of constant strings, ensuring that the same error is reported consistently across platforms
- context which provides a string field to stash any other context; probably not going to be very useful for analysis as the values will be divergent depending on client behaviour, but quite useful for debugging specific situations
In some cases, we may want more expressive power when error reporting e.g. more fields of different types. We will define additional event types as those cases arise, but by default, we should be using Error.
We define a single Click event which is triggered when users click/tap UI elements that are of interest to us. We will not attempt to perform blanket tracking of element clicks, simply those that are of interest to us when trying to analyse particular flows.
This event has properties:
- name which is a enumeration, ensuring consistency across platform when the user is clicking on the same event
- index which can be passed when the user clicks on an element within a list
On iOS and Android, Posthog has built-in functionality for tracking which screen the user is viewing. We need to decide whether we should reuse this functionality, or roll our own. If we use the built-in functionality, we wouldn’t use a schema with it.