Google Tag Manager (GTM)

This document walks through Mixpanel’s native integration with Google Tag Manager. The source code lives here.

Installation

Our video walkthrough demonstrates how get started using our GTM template.

The easiest way to install the custom template is to locate it in the Google Tag Manager community template gallery, and you can install it via the Google Tag Manager user interface.

To manually install the template, e.g. for debugging prior to the changes being published in the community template gallery, follow these steps.

1. Download the ./src/template.tpl file locally.
2. Open a Google Tag Manager Web container via the Google Tag Manager user interface. Preferably one that is already deployed on a website where you can test the template with real use cases.
3. In the GTM UI, browse to Templates, and in the box titled Tag Templates, click the blue New button.
4. Once the Template Editor is open, click the menu (three vertical dots) in the top-right corner of the window and choose Import.
5. Select the template.tpl file you downloaded locally.
6. Follow the prompts. Once the import is complete, the Template Editor should show the Mixpanel template in edit mode.
7. Click Save to save the template, and then proceed to close the Template Editor.
8. In the GTM UI, browse to Tags and click New to create a new tag.
9. From the list of available tag templates, choose the Mixpanel template you just imported to the container.

How It Works

The template brings the functionality of the Mixpanel JS SDK to Google Tag Manager so that you can implement Mixpanel through the Tag Manager interface without needing to directly edit your website’s code.

GTM will load our custom-created Javascript wrapper with predefined tags. These tags correspond to core Javascript SDK functions. You decide when to trigger each tag: on specific pages, button clicks, etc.

The wrapper overcomes the restrictions GTM’s templating system places on available Javascript APIs.

Initialization

When any Mixpanel GTM tag fires, it automatically tries to initialize a new instance using the Initialization Options configured in the tag. If an instance with the given name has already been initialized on the page, the initialization process will be skipped.

This way, the user doesn’t need to worry about initialization; just ensure that the Initialization Options are configured consistently across the tags.

Custom Initialization Options

To add initialization options for capabilities like session replay (record_sessions_percent) or heatmaps (record_heatmap_data) to GTM:

1. Add a new tag in GTM and choose the Mixpanel tag type
2. For the Project Token field, enter your Mixpanel project token
3. For Tag Type, select init from the dropdown
4. For Initialization, choose Set Options Manually
5. In the Option key / Option value section, add the relevant key-value pair according to your needs (e.g., record_heatmap_data as the key and set a boolean value of true)
6. For the Triggering section, choose an early GTM lifecycle event like Initialization - All Pages or Consent Initialization - All Pages

GTM with Custom Autocapture Configurations

To use autocapture initialization options like capture_extra_attrs with GTM, you’ll need to create a custom Javascript variable in GTM and then use that variable for your autocapture configuration. Here’s how to do it:

1. Create a Custom Javascript Variable in GTM

First, create a Custom Javascript variable that returns the autocapture configuration object:

1. In GTM, go to Variables > User-Defined Variables > New
2. Choose “Custom Javascript” as the variable type
3. Add code that returns the autocapture configuration object, including the capture_extra_attrs option

For example, the Custom Javascript variable might look like this:

function() {
 return {
   pageview: "full-url",
   click: true,
   input: true,
   scroll: true,
   submit: true,
   capture_extra_attrs: ['data-cta-name', 'data-cta-position']
 };
}

2. Use the Variable in Your Mixpanel Tag

Once the custom variable is created:

1. Edit the Mixpanel initialization tag in GTM

2. For the Autocapture option, instead of selecting “Enabled” or “Disabled” from the dropdown, select the custom Javascript variable

3. Verify Your Implementation

After setting up the tag with the custom variable:

1. Use GTM’s preview mode to verify that the tag is firing correctly

2. Check in the browser’s developer console that the Mixpanel configuration includes the custom autocapture settings

3. Verify in Mixpanel that the extra attributes are being captured with your events

This approach allows for customized autocapture options beyond the simple enabled/disabled toggle that’s available in the standard GTM template interface.

Sending Mixpanel Commands

After adding the Project Token to its respective field, you need to choose what type of tag to use. Each type corresponds with some command you can use with the Mixpanel Javascript API.

Note that 'init', 'push', and any of the “getter” commands are not supported in the template.

The more complex tag types (group, people, and track) are elevated to the top of the drop-down menu with the - prefix to separate them from the other commands.

Once you select a tag type, additional options may appear. Please have a look at the SDK reference for details on how to configure these options.

Tag to Function Mapping

Essential Tags

These are tags you’ll likely need in any Mixpanel-GTM implementation

Higher-level Mappings

-Group Tags for Group Analytics

-People Tags for User Profiles

Additional Mappings

Firing The Tag

Once you’re happy with your tag, add a Trigger to it. For example, to trigger it with every page load, add the All Pages trigger.

Be sure to save the tag when you’re done.

Testing

You can then enter Preview mode by clicking the blue Preview button in the Google Tag Manager UI. This opens a new tab with your website running the GTM container, and you can proceed to test the Mixpanel tag as if the container were published. In the Tag Assistant Preview tab, you can see additional information about the trigger events, tags, and variables that fire while you are browsing the page in Preview mode.

You can also enable the Javascript SDK’s Debug Mode by following Steps 1-4. Then, add debug and true as an Option key and Option value, respectively.

FAQ

Why is my Mixpanel tag not firing?

• Ensure that the tag is properly configured with the correct Project Token in your Project Settings
• Verify that the trigger conditions are met. For example, if you set the tag to fire on “All Pages,” make sure you are testing on a page that matches this condition.
• Check the browser console for any Javascript errors that might be preventing the tag from executing
• Use the GTM Preview mode to see if the tag is firing and if there are any errors in the console

Why are my events not found in Mixpanel?

• Check if the Project Token in the GTM tag matches the one in your Mixpanel project settings
• Use GTM Preview mode to ensure tags are firing.
• Check the browser console for Mixpanel logs (enable debug mode).
• Disable ad blockers, as they can block client-side tracking.
• Make sure your variables are set up correctly.

Does the Mixpanel template work with iOS/Android/AMP/Server Containers?

The Mixpanel GTM template only works with web containers.