Plan events, properties, and user properties

  • Updated

This article will help you:

  • Tell Amplitude Data which events and properties it should track

In Amplitude Data, the tracking plan is a living document that outlines what events and properties to track, why you're tracking them, and where they are tracked. Once this has been done, developers can instrument the analytics schema in the code base.

Implementing a tracking plan helps avoid the common pitfalls teams face when instrumenting analytics. When creating your tracking plan, you should be considering two primary roles: the developer who has to implement tracking, and the data consumer who’ll use the data to answer questions. It's imperative to keep them both on the same page.

This article will explain how you should think about your tracking plan in the planning stages, as well as describe how to implement it when you’re ready.

Define your business objectives

Before creating your tracking plan, your team will need to share a clear understanding of your business objectives, so that everyone is aligned on what you're tracking and why. Some questions to consider are:

  • What are you and the team working towards?
  • What metric are you trying to optimize for?
  • What questions are you looking to answer with data?

Everything you work on should be tied to a goal. This helps ensure you’re prioritizing outcomes over outputs, and not merely celebrating “success theater.” Once you’ve identified your business objectives, it's easier to break them down into metrics (what you're measuring) and events (how you're measuring them) within your tracking plan.

If your goal is to improve active usage of your product, you first need to determine the key action in your product that’s most closely tied to value. It's important to break this down further into a suite of metrics that feed into that output metric.

For example, for a music streaming service, that metric could be the time spent listening to music. Your input metrics would be things like New artist notification, an event that brings users back to the product increasing their time spent listening to music.

Input Metrics

Output Metrics

New artist notifications →

Bring users back more often →

⭐️ Time spent listening to music

Recommendations →

Create playlists →

Increase time spent per session →

Discover new songs →


Once you have that suite of metrics, you can start to determine what events you need to instrument in your product.

Create your tracking plan

In Amplitude Data, the tracking plan allows all stakeholders to collaborate on a single source of truth for analytics definitions. It keeps everyone in sync on what data to track, when, and why, and maintains a consistent schema across engineering, product management, data science, and other consumers of analytics data.

When creating the tracking plan, you will:

  • Add sources. Sources represent the main parts of your product, e.g. your iOS, Android, Web, and Backend. You’ll create a new source for every standalone part that will send events to your analytics backends.
  • Add destinations. Destinations represent the analytics providers events will be sent to from your sources.
  • Create your events. An event is a distinct action that a user can perform in your product. You should not be tracking all user interactions; only those that are important for understanding user behavior or triggering marketing automation. You'll also want to specify which sources will be sending each event. Assigning sources to events connects your tracking plan with the Ampli Developer experience.
  • Add event properties. An event may have one or more properties associated with it. Properties further describe the particular event and the context it was invoked in. For example, a Song Played event may contain a songTitle property. Every property is defined by a name, description, examples, and rules for that property.
    Properties are validated at runtime to ensure that only data conforming to your rules makes its way into your analytics destinations. Rules are specific to each data type. For example, property songTitle of type String can have the following rules: Min Length, Max Length, and Regex.
  • Publish your changes.
  • Solicit your team's feedback. Collaborating with your team on your tracking plan helps ensure everyone is aligned and you can gather feedback from your colleagues before instrumenting new events.
  • Instrument your product.

To create and implement your tracking plan, follow these steps:

  1. Add your data sources. Every source has a name, runtime, and a set of destinations associated with it. A source's runtime defines the platform-language combination used by that part of your application (e.g. iOS — Swift). Amplitude Data uses this information to generate the correct tracking library for engineers implementing your tracking plan.Repeat this step for each source you want to add.

  2. Add your data destinations. Every destination has a vendor, access token, and a set of sources associated with it. The vendor identifies the analytics provider you're working with. Amplitude Data uses this information when generating a tracking library for your engineering team to make sure it sends events to all the right places.

    NOTE: For Amplitude specifically, you can choose your respective projects directly from a dropdown menu. A destination's set of sources defines the parts of your applications that will send events to this destination. Repeat this step for each destination you want to add.

  3. In the left-hand sidebar, click Events. Then click + Add Event and enter the requested information in the fly-out panel. Every event has a name, description, a list of sources it applies to (e.g. iOS, Android), and a set of properties.

    Repeat this step for each event you want to add.

    NOTE: We recommend the object-action framework as a best practice for governing the structure of your events. Each event is associated with an object in your application (e.g. Song, File, or User) and an action (e.g. Played, Uploaded, or Logged In).

  4. In the left-hand sidebar, click Properties. You’ll see tabs for event properties, user properties, and group properties. Depending on the tab you have open, click + Add {Event / User / Group} Properties and enter the requested information in the fly-out panel. Repeat this step for each property you want to add.

  5. In the left-hand sidebar, click Events again to connect event properties to the events you created in Step 3 above. Click on the event name to open its fly-out panel. From there, click edit.png, then click %2Bwhere.png, and select from the drop-down list the property you want to add to this event. Repeat this step for each event that has properties associated with it.

    NOTE: If you have multiple events that share similar properties, you can create a property group. Property groups—which are distinct from group properties—make it much easier to manage complex tracking plans, as you don't have to keep adding the same properties multiple times. When you update a property group, the update applies to all events the group is associated with.

  1. At this point, you are ready to solicit feedback from your team. You can do this from within Amplitude Data—just @mention your colleagues in the rich text editor of any event or property to send them an email notification—or use Amplitude’s Slack integration.

In the final step, your developers will instrument your product using the Ampli CLI. Your tracking plan will be consumed by developers in the form of type-safe auto-generated code. Amplitude Data can generate a tracking library for all popular platforms and programming languages. The auto-generated library is a lightweight wrapper over your analytics provider's SDK that provides type-safety, supports linting, and enables additional features like input validation. The code exactly replicates the spec in the tracking plan and enforces all its rules and requirements.