Prerequisite: Guide to Mixpanel Basics
This guide assumes that you already have a foundational understanding of the Mixpanel data model. If you haven't already done so, please take time to review the Guide to Mixpanel Basics before proceeding with this guide.
Implementation refers to the process of configuring your product to send data to a Mixpanel project. The implementation process is highly customizable – it's up to you to decide what data should be sent to Mixpanel, and you are responsible for adding the appropriate tracking code to do so.
A proper Mixpanel implementation will provide you with comprehensive user engagement data that can be used for powerful analysis and targeted outreach. However, a poor implementation can lead to missing data, or even worse, inaccurate data resulting in misguided business decisions.
Ultimately, the value that you get out of Mixpanel is dependent on the quality of your implementation. This guide is designed to walk you through the necessary steps to ensure that you are implementing Mixpanel in a way that will set you and your entire organization up for success.
Are you more of a visual learner? If so, you'll definitely want to check out our Mixpanel Implementation Course which contains 3 hours of video lessons exploring many of the same topics covered in this guide, but in much more depth.
Phase 1: Planning
Too often, new Mixpanel users are so over-eager to start collecting data that they jump straight into the process of adding Mixpanel tracking code without first thinking through a solid implementation strategy. The end result is almost always the same – they end up wasting more time trying to fix problems with their implementation than if they just invested the time to properly plan their implementation beforehand. In this section, we'll discuss best practices to keep in mind when planning out your implementation.
Assemble A Team
Unless you're part of a one-person company, chances are there are other people at your organization that would benefit from having the ability to analyze the type of user engagement data that Mixpanel can collect. Therefore, we always recommend that you begin by assembling a team representing the various departments at your organization and have each person identify the user actions and details that relate to their key metrics.
We've built out A Guide To Product Metrics to help you decide what metrics are most important for your product and business.
When it comes to determining what user actions to track, you want to make sure that your events are not too specific or too broad. To illustrate this, let's run through a couple quick examples in which we'll assume we are setting up an implementation for a music streaming application.
Tracking an event such as "Hip-Hop Song Play" is too specific. This approach would result in different events for every single type of music genre which would make it cumbersome to perform a rather simple query like finding the total number of songs played. Instead, it is better to track a "Song Play" event and store the genre in an event property that could then be used to filter or breakdown our analysis.
Tracking an event such as "Button Click" is too broad. It groups together completely unrelated actions such as clicking on the logout button or clicking on a song's play button. Instead, it is better to track separate events that describe the action represented by the button click (e.g. "Logout", "Song Play").
To Track Or Not To Track?
When planning your Mixpanel implementation, you will inevitably have times when you find yourself debating whether or not a user action or detail is important enough to track with Mixpanel. When in doubt, track it! This way, the data will be available to you should you decide at a later point in time that you do in fact want to analyze it. Furthermore, you can always use Lexicon to hide unused events or properties so that they won't clutter your Mixpanel project.
However, there is one extremely important exception to this guideline. When the data in question deals with sensitive user information, it's best to err on the side of caution and not track the data with Mixpanel. Please refer to our section on Data Security and Privacy for more information on this topic.
Take Advantage Of Properties
Properties are the cornerstone of a quality Mixpanel implementation as they are what allow you to slice and dice your data to find interesting segments of users or actions. As such, it is important to send as much detail as you can with every event and user profile in the form of properties, so long as you stay within the property limits. To help in this effort, Mixpanel client-side SDKs (more about this in the next section) will automatically collect a set of default properties and send them to your project.
Pro Tip: Super Properties
Super properties are a type of event property that you can set once to automatically attach to every event you’re tracking. They are particularly useful for tracking how characteristics about a user change over time. For more details, please refer to this article.
Some property names are reserved for use by Mixpanel and used in special ways. It is important that you review the list of reserved properties and make sure that you name your properties accordingly. This is particularly important if you plan on using Mixpanel to send messages to your users, because Mixpanel Messages rely on reserved properties (e.g. $email, $phone).
Make An Implementation Spec
An implementation spec is a document that details the exact events and properties that need to be implemented. There is not one specific format for setting up an implementation spec – it could be a spreadsheet, text document, or even a set of napkin sketches if you want – so long as it defines a clear blueprint for a developer to follow when implementing Mixpanel.
A well-defined implementation spec should include the desired event and property names as well as the property data types. Not only will an implementation spec help ensure that all of the necessary data gets sent to your Mixpanel project in the correct format, but it also serves as a source of truth that can be referenced after the implementation process to understand what data is being collected.
Looking for some inspiration on how to setup your implementation spec? Check out this guide for implementation spec best practices as well as implementation spec templates for industry-specific verticals.
Phase 2: Development
With a plan in place, it's time to start sending data to Mixpanel. In this section, we'll identify several best practices and key concepts related to this phase of the implementation process.
Creating A Project
Before you start adding Mixpanel tracking code, you first need to create a project so that you have somewhere to send your data. This can be done directly within the Mixpanel UI:
Whether you are implementing for the first time or modifying an existing implementation, it is best practice to send all data generated during the implementation process to a separate dev project. Only once you have confirmed that your implementation is working as expected should you switch to sending data to a production project. This helps to ensure that the data set in your production project remains free of any poorly structured data or internal testing data generated during the development phase.
By default, all new Mixpanel projects are set to Pacific time. If you are based in a different timezone, you will want to update your project settings accordingly. For a walk-through of how to do this as well as information about the importance of setting a project's timezone, please refer to this article.
Sending Data To Mixpanel
Warning: Tracking Should Be Handled By A Developer
Tracking mistakes can produce inaccuracies in your analytics as well as unintended issues in your product. To help avoid these problems, please make sure that your Mixpanel tracking is carried out by a qualified developer(s) that can follow the guidelines outlined in the Mixpanel Developer Docs.
Mixpanel maintains three API endpoints for the purposes of ingesting data into a project:
- api.mixpanel.com/track – track events less than 5 days old
- api.mixpanel.com/import – track events more than 5 days old
- api.mixpanel.com/engage – make updates to user profiles
These endpoints will only accept requests that adhere to the technical specifications defined in the Mixpanel Developer Docs.
While you can send data to Mixpanel via HTTP requests to the various API endpoints, a vast majority of Mixpanel implementations are built using one of the Mixpanel SDKs. These SDKs, which are offered in a wide variety of major client-side and server-side programming languages, contain functions that simplify the process of sending data to a Mixpanel project. Furthermore, the client-side SDKs will automatically collect certain bits of information (e.g. user's location, device details) and pass them along as default properties with all events and profiles that get sent to your Mixpanel project.
Mixpanel is a user analytics platform, which means that all tracking is performed at the individual user level. In other words, each event that gets sent to Mixpanel should be associated with a specific user. The way Mixpanel determines which user performed a particular event is through a special event property called distinct_id which serves as a unique user identifier.
When building out your Mixpanel implementation, it is essential that you include the necessary logic to ensure that a user's distinct_id remains constant throughout their lifetime, even as they switch between different devices or platforms. This concept, which we refer to as identity management, is one of the most important yet often overlooked parts of the Mixpanel implementation process.
Check out this article for best practices and things to look out for when configuring identity management within your Mixpanel implementation.
Phase 3: Post-Development
The implementation process should not end once the track calls have been added into your product's source code. Instead, this should kick off a post-development process to ensure that the data being collected is accurate and well-documented.
Mixpanel offers a couple built-in tools to help you QA your implementation:
Live View – This tool displays events that are sent to your Mixpanel project in real-time. You can use Live View to verify that events are being tracked as expected and contain all of the properties you wish to be captured.
Explore – This report lets you view all of the user profiles within your Mixpanel project. You can use Explore to verify that the appropriate user properties are being collected and that all events for a specific user are tied to the same profile.
Document Your Implementation
After you have successfully built out and tested your Mixpanel tracking, the final step is to document your implementation. This will help individuals at your company who may not have been a part of the implementation process to understand what data is being collected, which in turn will empower them to run analyses within Mixpanel.
The easiest way to to do this is through Lexicon, which allows you to add event and property descriptions as well as other useful metadata that will be surfaced directly within the Mixpanel UI.
It's important to note that implementation should be seen as an ongoing process – it's not something that should be setup once and then never touched again. Instead, your Mixpanel implementation should constantly be updated to reflect any changes to your product or your business metrics. When you do eventually revisit your implementation to add additional tracking or make changes to existing tracking, just make sure to follow all the guidelines discussed here in this guide.
This is just one of a series of Getting Started guides to help you as you embark on your Mixpanel journey. Once you have data populated in your Mixpanel project, we'd recommend that you move on to the next guide in this series: