Integrations
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.
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.
Web
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.
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.
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 2
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.
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.
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'
}
}
}
}
}
}
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'
}
}
}
}
}
}
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'
}
}
}
}
}
}
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'
.
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.
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. |
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”. |
|
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?