Docs
HomeGuidesDevelopersIntegrations

Integrations

Google Tag Manager
CategoriesAll

Event

Edit this Page

Google Tag Manager (GTM) is a free, unified advertising and analytics platform for the web. GTM utilizes JavaScript and HTML tags to unify tracking and analytics across several different diverse analytics products on websites. mParticle sends data to GTM through a shared data layer. You can then use triggers in GTM to capture the data passed from mParticle to GTM based on the schema of the mParticle data. For example, some triggers can be events or page views.

This is a kit-only integration that solely supports client-side data forwarding.

Prerequisites

Before you can begin sending data to GTM, you must first have a GTM account. For more information about setting up a GTM account, see Setup and install Google Tag Manager.

In order to test the GTM integration, you will need a working website in order to pass parameters to GTM.

Platforms Supported

Web

Supported Identities

  • All User Attributes
  • All User Identities
  • Device Application Stamp
  • MPID

Supported Events

mParticle allows you to explicitly capture consent from the user as shown in the code samples below. Using mParticle and GTM allows you to comply with GDPR with a unified API. For more information about consent, see Data Privacy Controls.

Explaining Containers and Data Layers

GTM is a service and client SDK that allows dynamic control of tags and data federation in your web apps.

Each GTM instance is configured separately in a unique “container”.

Each container must be configured to listen to a “data layer”.

A data layer serves as a conduit for page events and user state to that container.

By default, the GTM documentation recommends naming the data layer as “dataLayer”. However, when configuring GTM through mParticle, mParticle will initialize your GTM container to listen for a data layer named “mp_data_layer” to avoid collisions.

Adding Multiple Containers and Associated Unique Data Layers

Every container set up through mParticle will use the GTM Container ID as its name. However, the mParticle app will name the data layer (regardless of the container) mp_data_layer.

If you add multiple containers through mParticle, make sure each data layer is named uniquely.

For example:

  • Container 1

    • Container ID: GTM-PRLN7HP
    • mp_data_layer1

  • Container 2

    • Container ID: GTM-ABQR8NS
    • mp_data_layer2

Steps to Pass Data from Your Web App to mParticle to GTM

Step 1: Set up mParticle SDK on Your Page

The first step to creating a connection between mParticle and GTM is to add the mParticle SDK to your page. The snippet should be added to every page of your web app within the <head> tag. Make sure to follow the steps to verify and test the connection as outlined in the Getting Started section.

Step 2: Set up mParticle Events on Your Pages

mParticle supports multiple types of events. For more information about event types, see Event Tracking. Some example code snippets that may be passed from mParticle to GTM are listed below.

Custom Event

This is a standard custom event that could be used to pass data from your web app to mParticle to GTM.

Note that some of the attributes such as hostname and mpid are passed automatically from mParticle.

For a more in-depth explanation of custom events, see Custom Events

Here’s the logEvent as it would be coded on your website:

mParticle.logEvent( 					        //Type of event
    "Test Event", 						//Name of the custom event
    mParticle.EventType.Navigation, {                           //Attributes of the custom event
        label: "Transformers",
        value: "200",
        category: "Toys"
    }
);

The code that is passed from mParticle to GTM is shown below.

{
    event: 'Test Event', 		      //Name of the event
    mp_data: {
        device_application_stamp: '1234567890',  
        event: {
            name: 'Test Event',
            type: 'custom_event',            //Type of event
            attributes: { 														    //Attributes of the custom event
                label: 'Transformers',
                value: 200,
                category: 'Toys'
            }
        },
        user: {
            mpid: '8675309',
            attributes: {
                shoe_size: 11,

            },
            identities: {
                customerid: '1138'
            },
            consent_state: { 				
                gdpr: {
                    "location_collection": {
                        Consented: true, 
                        Timestamp: 1559066600299,
                        ConsentDocument: 'location_collection_agreement_v4', 
                        Location: '17 Cherry Tree Lane', 
                        HardwareId: 'IDFA:a5d934n0-232f-4afc-2e9a-3832d95zc702'
                    }
                }
            }
        }
    }
}

Screen View Event

Note that mParticle calls this event a screen_view while GTM refers to this as a PageView.

For an in-depth explanation of screen views, see Page View Tracking.

If you do not include any arguments, the SDK will use logPageView as the page name and will include the page title and hostname as attributes.

Below are code samples of the code in your web app to capture a screen view in mParticle.

//log the page view with details
mParticle.logPageView( 				//Type of event
    "Test Pageview" 				//Name of the event
);

The code passed from mParticle to GTM is shown below.

{
    event: 'Test Pageview',
    mp_data: {
        device_application_stamp: '1234567890',   //A cookie value generated by mParticle
        event: {
            name: 'Test Pageview',
            type: 'screen_view',
            attributes: {
                hostname: 'MyWebsite.com',      //Automatically detected by mParticle
                title: 'My Page Name'           //Automatically detected by mParticle
            }
        },
        user: {
            mpid: '8675309',                  //Automatically detected by mParticle
            attributes: {

            },
            identities: {
                customerid: '1138'
            },
            consent_state: {
                gdpr: {
                    "parental": {
                        Consented: false,
                        Timestamp: 1559066600299,
                        ConsentDocument: 'location_collection_agreement_v5',
                        Location: 'Salt Lake, UT',
                        HardwareId: 'IDFA:a5d934n0-232f-4add-2e9a-3832d95zc702'
                    }
                }
            }
        }
    }
}

Purchase (commerce) Event (without user attributes)

This is an example commerce event passed from mParticle to GTM.

Note that there are multiple types of commerce events. For a more in-depth explanation of mParticle commerce events see Commerce Events.

Below is an example of the code in your web app to capture a commerce event in mParticle.

// 1. Create the product
var product = mParticle.eCommerce.createProduct(
    'Toys',
    'Transformers',
    30.00,
    .45
);

// 2. Summarize the transaction
var transactionAttributes = {
    Id: :'foo-transaction-id',
    Revenue: 30.00,
    Tax: 45
};

// 3. Log the purchase event
mParticle.eCommerce.logPurchase(transactionAttributes, product);

Note that the object for commerce attributes is required by GTM and passed by mParticle. The code that is passed from mParticle to GTM is shown below.

{
    event: 'eCommerce - Purchase',                //Name of the event
    ecommerce: {                                  //Type of event
        purchase: {
            actionField: {                        //Event attributes
                id: 'foo-transaction-id',
                affiliation: 'Online Store',
                revenue: '30.00',
                tax: '.45',
                shipping: '5.99',
                coupon: 'SUMMER_SALE'
            },
            products: [{
                name: 'Transformers',
                id: '44556',
                price: '40.00'
            }, ]
        }
    },
    mp_data: {
        device_application_stamp: '1234567890',
        event: {
            name: 'eCommerce - Purchase',
            type: 'commerce_event',
            attributes:{
            }
        },
        user: {
            mpid: '8675309',
            attributes: {

            },
            identities: {
                customerid: '1138'
            },
            consent_state: { //Consent block automatically passed by mParticle
                gdpr: {
                    "location_collection": {
                        Consented: true,
                        Timestamp: 1559066600299,
                        ConsentDocument: 'location_collection_agreement_v6',
                        Location: 'New York, NY',
                        HardwareId: 'IDFA:a5d934n0-232f-6rfc-2e9a-3832d95zc702'
                    }
                }
            }
        }
    }
}

Step 3: Map GTM Events to Your Events

The next step to use GTM with mParticle is to make sure that your custom mParticle events are mapped properly within GTM. This means verifying that every custom event you’ve created in your web app, is represented in GTM.

For example, if you are calling an event such as mParticle.logEvent('My Event Name'), you need to verify that there is a corresponding trigger in GTM that listens for event: 'My Event Name'.

Step 4: Configuring the mParticle App

The last step in creating a connection from mParticle to GTM is configuring the mParticle app.

The sections below outline the relevant parts of the mParticle app that need to be configured to pass data from mParticle to GTM.

Configuration Settings

In order to set up a GTM output and connection, set the following parameters in the Setup > Outputs > Google Tag Manager > Configuration settings dialog.

Setting Name Data Type Description
Configuration Name string The descriptive name you provide when creating the configuration. This is the name you will use when setting up the output connection to GTM.

Connection Settings

When you are ready to use the GTM output from the data sent to mParticle, you must enter the following information in the Connections > Web > Connected Outputs > Google Tag Manager dialog.

An explanation of the Connection Settings fields is below.

Setting Name Data Type Default Value Description
Container ID string A collection of tags, triggers, variables, and related configurations installed on a particular website is called a “container”.
  • For information about how to set up a container see Setup and install Tag Manager
  • For information about the Tag Manager, see Tag Manager Overview
    		•
    Include GTM Snippet via mParticle? boolean true If this box is unchecked, mParticle will not copy the GTM snippet into your page. It will be assumed that you are using your own GTM snippet.

    By default, this box is checked.
    Data Layer Name string mp_data_layer A JavaScript object that is used to pass information from your website to the GTM container. See this page for an explanation of the GTM Data Layer.

    Note that multiple data layers on the same page should be named differently to avoid duplicate entries.
    Preview URL string The URL for previewing or testing a specific version of your GTM Workspace. See Preview and debug containers for more information.

    Make sure that the Preview URL corresponds to the Container ID you are assigning or it will be rejected.

    If debug is turned on in GTM, debug will also be turned on in the mParticle app.

    Was this page helpful?