Last updated

Google Tag Manager Integration for Advertisers

This guide walks you through the process of integrating with Rokt using Google Tag Manager (GTM). You'll learn how to create variables in GTM based on your data layer, and how to create tags to initialize the the Rokt SDK and insert placements.

Understanding the data layer

The data layer should have been implemented on your web page by your developers.

A data layer is an object that contains all of the information that you want to share with Google Tag Manager (GTM). Information such as events or variables can be shared to Google Tag Manager via the data layer, and triggers can be set up in Google Tag Manager based on the values of variables (e.g., fire a remarketing tag when purchase_total > $100) or based on the specific events. Variable values can also be shared through to other tags (e.g., add purchase_total into the value field of a tag).

Refer to the GTM developer guide for comprehensive details on how the data layer works.

Example of a data layer:

window.dataLayer = window.dataLayer || []

window.dataLayer.push({
    'email':'jenny.smith@rokt.com',
    'user': {
        'firstname' : 'Jenny',
        'lastname' : 'Smith'
    },
    'ecommerce': {
        'transaction': {
            'amount' : '12.36'
        }
    },
    'event':'gtm.transactionComplete'
});

Identify your variable names

Variables are set up in your GTM and are matched to the data layer. Refer to the GTM developer guide for more details about variables.

The structure of your data layer on your page affects the data layer variable name in your GTM.

Example data layer script 1:

window.dataLayer.push({
    'email':'jenny.smith@rokt.com'
});

Data layer variable name: email

Example data layer script 2:

window.dataLayer.push({
    'user': {
        'firstname' : 'Jenny'
    }
});

Data layer variable name: user.firstname

Example data layer script 3:

window.dataLayer.push({
    'ecommerce': {
        'transaction': {
            'amount' : '12.36'
        }
    }
});

Data layer variable name: ecommerce.transaction.amount

Create your variables in Google Tag Manager

1. Open Google Tag Manager.
2. Click Variables.
3. Under User-defined variables, click New.
4. Enter a name for your variable.
5. Click Choose a variable type to begin setup...
6. Under Page Variables select Data Layer Variable.
7. Enter the Data Layer Variable Name. See the examples above to identify the variable name based on your data layer structure.
8. Click Save.

Rokt suggests creating variables for the following attributes:

• email
• firstname
• lastname
• zipcode
• mobile
• conversiontype
• confirmationref
• amount
• currency

Create your tags

Initialize the Rokt SDK

1. Log in to your Google Tag Manager Container, and click Tags in the left hand navigation.
2. Click New and select Tag Configuration.
3. Under Custom, select Custom HTML Tag.
4. Enter a descriptive name for your tag, like "Initialize Rokt".
5. In the HTML entry field, paste in the following snippet:

<script type="text/javascript">

// Enter your Rokt API key
var API_KEY = "YOUR_API_KEY";

// If you configured a first-party domain, set it as the value of DOMAIN instead of the default apps.rokt-api domain
var ROKT_DOMAIN = "https://apps.rokt-api.com";

// Set your SDK configuration settings
window.mParticle = {
    config: {
        // Specify the data environment with isDevelopmentMode:
        // Set isDevelopmentMode to true if you are still testing your integration. 
        // Set isDevelopmentMode to false if your integration is ready for production data.
        isDevelopmentMode: true,
        // Identify the current user:
        // If you have the user's email address, include it in an object called `userIdentities` within `identifyRequest` as shown below.  
        identifyRequest: {
            userIdentities: {
                // Make sure to replace the sample variable {email} with the variable you create to store your user's email
                email: {{email}},
                // Hashed email addresses should be passed into the `other` field
                other: {{hashed-email}}
            },
        }
    },
};

// Load the SDK
(function(e) { window.mParticle = window.mParticle || {}; window.mParticle.EventType = { Unknown: 0, Navigation: 1, Location: 2, Search: 3, Transaction: 4, UserContent: 5, UserPreference: 6, Social: 7, Other: 8, Media: 9 }; window.mParticle.eCommerce = { Cart: {} }; window.mParticle.Identity = {}; window.mParticle.Rokt = {}; window.mParticle.config = window.mParticle.config || {}; window.mParticle.config.rq = []; window.mParticle.config.snippetVersion = 2.6; window.mParticle.ready = function(e) { window.mParticle.config.rq.push(e); }; ["endSession", "logError", "logBaseEvent", "logEvent", "logForm", "logLink", "logPageView", "setSessionAttribute", "setAppName", "setAppVersion", "setOptOut", "setPosition", "startNewSession", "startTrackingLocation", "stopTrackingLocation"].forEach(function(e) { window.mParticle[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift(e); window.mParticle.config.rq.push(t); }; }); ["setCurrencyCode", "logCheckout"].forEach(function(e) { window.mParticle.eCommerce[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("eCommerce." + e); window.mParticle.config.rq.push(t); }; }); ["identify", "login", "logout", "modify"].forEach(function(e) { window.mParticle.Identity[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Identity." + e); window.mParticle.config.rq.push(t); }; }); ["selectPlacements","hashAttributes","setExtensionData"].forEach(function(e) { window.mParticle.Rokt[e] = function() { var t = Array.prototype.slice.call(arguments); t.unshift("Rokt." + e); window.mParticle.config.rq.push(t); }; }); var t = window.mParticle.config.isDevelopmentMode ? 1 : 0, n = "?env=" + t, a = window.mParticle.config.dataPlan; if (a) { var o = a.planId, r = a.planVersion; o && (r && (r < 1 || r > 1e3) && (r = null), n += "&plan_id=" + o + (r ? "&plan_version=" + r : "")); } var i = window.mParticle.config.versions, s = []; i && Object.keys(i).forEach(function(e) { s.push(e + "=" + i[e]); }); var c = document.createElement("script"); c.type = "text/javascript"; c.async = !0; window.ROKT_DOMAIN = ROKT_DOMAIN || 'https://apps.rokt-api.com'; mParticle.config.domain = ROKT_DOMAIN.split('//')[1]; c.src = ROKT_DOMAIN + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); var l = document.getElementsByTagName("script")[0]; l.parentNode.insertBefore(c, l); })(API_KEY);
</script>

6. Enter your configuration settings:
   • Replace YOUR_API_KEY with the API key provided to you by your Rokt account manager.
   • If you set up a custom domain for a first party domain integration, replace https://apps.rokt-api.com with your new domain.
   • If you are ready to use your tag for production data, set isDevelopmentMode to false. Leave this set to true if you are still testing your tag.
   • Make sure email is set to the variable you created to store your user's unhashed email address. In the example snippet above, the variable name is {email}.
7. Check Support document.write.
8. Click Choose a trigger to make this tag fire...
9. Select All Pages.
10. Click Save.

Identify the User

You should also create a tag that identifies the current user to Rokt. Make sure to include this tag in your site so it is fired as soon as the user provides their email address.

1. Click Tags in the left hand navigation from your Google Tag Manager Container.
2. Click New and select Tag Configuration.
3. Under Custom, select Custom HTML Tag.
4. Enter a descriptive name for your tag, like "Identify User".
5. In the HTML entry field, paste in the following snippet:

<script type="text/javascript">

window.mParticle.ready(
    function() {
        var identifyRequest = {
            userIdentities: {
            // If you're using a raw, un-hashed email, pass it into the `email` field
            email: {{email}},

            // If you're integrating hashed email, pass it into the `other` field instead
            other: {{hashed-email}}
            }
        };
        mParticle.Identity.identify(identifyRequest);
    }
);

</script>

6. If you are sending the user's raw, unhashed email address to Rokt, set it to email. If you are sending the hashed email address, set it to other. Make sure to replace the example variable names ({{user.email}} and {{user.hashed-email}}) with the data layer variables you created to store your user's email address.
7. Configure a trigger so that this tag is fired as soon as a user provides their email address. The trigger you use will depend on your specific integration, but (as an example), you could create a trigger that fires the tag when a user provides an email address via a form submission:
   • From Trigger Configuration, select Form Submission.
   • Under "This trigger fires on", select Some Forms.
   • Select the data layer variable you created to store your user's email address.
   • For the condition, select matches RegEx and enter the regular expression .+@.+\..+.

caution

The exact trigger configuration you use for the Identify User tag will depend on your integration. If you have questions about how best to implement this tag so that your users are successfully identified before logging events, speak to your Rokt Account manager.

Track Page Views

Advertisers should track views for each page through the conversion funnel by calling the logPageView method as soon as possible when each page is loaded.

1. Click Tags in the left hand navigation from your Google Tag Manager Container.
2. Click New and select Tag Configuration.
3. Under Custom, select Custom HTML Tag.
4. Enter a descriptive name for your tag, like "Track Page View".
5. In the HTML entry field, paste in the following snippet:

<script type="text/javascript">

window.mParticle.ready(
    function() {
        mParticle.logPageView(
            // Replace 'page view' with a descriptive name of the page you're tracking
            "page view",
            // An object containing attributes describing the page
            {
                "url": window.location.toString(),
                "product": "Example Product Name",
                // Add any other page specific attributes as key/value pairs
                "custom-attribute-name": "custom-attribute-value"
            }
        );
    }
);

</script>

The logPageView method takes two arguments:

Page Name: a string for the name of the page being loaded

Custom Attributes: an object of key/value pairs containing information about the page

The page name field should be set to a generic page name. For example, an ecommerce website could have hundreds of product detail pages. To log these correctly, you should use a generic name (e.g. "Product Detail Page") and then log the url and other attributes of the page as attributes.

6. Configure a trigger so that this tag is fired on every page in the conversion funnel (after the initialization tag).

caution

The exact trigger configuration you use for the Track Page Views tag will depend on your integration. If you have questions about how best to implement this tag so that your pages are tracked correctly, speak to your Rokt Account manager.

Log a Conversion

In addition to creating a tag to initialize the Rokt SDK, Rokt advertiser integrations also require a tag to log a conversion.

1. Click Tags in the left hand navigation from your Google Tag Manager Container.
2. Click New and select Tag Configuration.
3. Under Custom, select Custom HTML Tag.
4. Enter a descriptive name for your tag, like "Conversion".
5. In the HTML entry field, paste in the following snippet:

<script type="text/javascript">

window.mParticle.ready(
  function() {  
        var currentUser = mParticle.Identity.getCurrentUser();
        currentUser.setUserAttribute("firstname", {user.firstname});
        currentUser.setUserAttribute("lastname", {user.lastname});
        currentUser.setUserAttribute("zipcode", {user.zipcode});
        currentUser.setUserAttribute("mobile", {user.mobile});

        mParticle.logEvent( 
        "conversion", // The name of the event
        mParticle.EventType.Transaction, // The event type
        { 
            "conversiontype": {ecommerce.transaction.conversiontype}, // Type of conversion
            "confirmationref": {ecommerce.transaction.confirmationref}, // Transaction ID / Order ID
            "amount": {ecommerce.transaction.amount}, // Transaction amount e.g. 300.5
            "currency": {ecommerce.transaction.currency}, // Transaction currency e.g. USD
        }
    );
  }
);

</script>

6. Set each attribute you want to forward to Rokt with the variable you created based on your site's data layer.

caution

Make sure to replace the example variables in the snippet with your own variables.

7. Check Support document.write.

8. To configure when the tag is triggered, select Triggering.

9. Click the + button to add a new trigger.

10. Click Trigger Configuration. The next steps vary depending on whether your site is a multi-page application (MPA) or a single page appliaction (SPA):

    • Trigger configuration for multi-page appliactions

      1. Select Page View from the list.
      2. Change the trigger firing rules to Some Page Views.
      3. Enter the URL parameter(s) that identify each unique page where the tag should fire. For example, if your confirmation page is example.com/cart/payment/confirmation the identifying parameter can be any of cart, payment, or confirmation.

    • Trigger configuration for single page applications

      1. Select History Change from the list.
      2. Change the trigger firing rules to Some History Changes.
      3. Enter the URL parameter that identifies the page where the tag should fire. For example, if your confirmation page is example.com/cart/payment/confirmation the identifying parameter can be any of cart, payment, or confirmation.

11. Click Save.