Last updated

Tealium Integration for Ecommerce

This guide walks you through the process of integrating with Rokt using Tealium. You'll learn how to create variables in Tealium based on your data layer, and how to create tags to initialize 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 Tealium. Variables can be shared with Tealium via the data layer or in subsequent view change declarations.

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

Example of a data layer:

window.utag_data = window.utag_data || {}

utag_data['email_address'] = 'test@test.com'
utag_data['first_name'] = 'john'
utag_data['last_name'] = 'doe'

Setting the view trigger

To trigger the appropriate event, use the following code in your app when a purchase event happens:

utag.view({tealium_event : 'purchase', email_address : 'john.doe@example.com', amount:'20.00', currency:'USD', confirmationref:'123456789'})

The "purchase" event will resolve to the destination you configure in "Mapped Variables", e.g. Purchase, Bag, Checkout, etc..

Initialize the Rokt SDK

1. Log in to your Tealium account.
2. Click Tags in the left hand navigation.
3. Click the New Tag button on the right side, then select Tealium Custom Container.
4. Enter a description name for your tag, like "Rokt SDK".
5. Under Edit Template, paste the SDK initialization snippet provided below.
6. Replace api_key inside u.data with the Rokt API key provided by your Rokt account manager.
7. Click Save.

SDK initialization snippet

//~~tv:20010.20230630
//~~tc: Tealium Custom Container
//~~tc: Updated Tealium loader to 4.35 version

/*
  Tealium Custom Container Notes:
  - Add sending code between "Start Tag Sending Code" and "End Tag Sending Code".
  - Add JavaScript tag library code between "Start Tag Library Code" and "End Tag Library Code".
  - Add JavaScript code only, do not add HTML code in this file.
  - Remove any <script> and </script> tags from the code you place in this file.

  Loading external JavaScript files (Loader):
  - If you need to load an additional external JavaScript file, un-comment the singe-line JavaScript comments ("//") within the following Loader sections near the bottom of this file:
      - "Start Loader Function Call"
      - "End Loader Function Call"
      - "Start Loader Callback Function"
      - "End Loader Callback Function"
  - After un-commenting, insert the path to the external JavaScript file you want to load.
  - Finally, within the Loader callback function, insert the JavaScript code that should run after the external JavaScript file has loaded.
*/

/* Start Tag Library Code */
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); }; });

/* End Tag Library Code */

//tealium universal tag - utag.sender.custom_container ut4.0.##UTVERSION##, Copyright ##UTYEAR## Tealium.com Inc. All Rights Reserved.
try {
  (function (id, loader) {
    var u = {};
    var src;
    utag.o[loader].sender[id] = u;

    // Please do not modify
    if (utag.ut === undefined) { utag.ut = {}; }
    // Start Tealium loader 4.35
    if (utag.ut.loader === undefined) {
      u.loader = function (o) {
        var b, c, l, a = document;
        if (o.type === "iframe") {
          b = a.createElement("iframe");
          o.attrs = o.attrs || { "height" : "1", "width" : "1", "style" : "display:none" };
          for (l in utag.loader.GV(o.attrs)) { b.setAttribute( l, o.attrs[l] ); }
          b.setAttribute("src", o.src);
        } else if (o.type=="img") {
          utag.DB("Attach img: "+o.src);
          b=new Image();
          b.src=o.src;
          return;
        } else {
          b = a.createElement("script");
          b.language="javascript";
          b.type="text/javascript";
          b.async=1;
          b.charset="utf-8";
          for( l in utag.loader.GV(o.attrs) ){ b[l] = o.attrs[l]; }
          b.src = o.src;
        }
        if(o.id){b.id=o.id};
        if (typeof o.cb=="function") {
          if(b.addEventListener) { b.addEventListener("load",function(){o.cb()},false); }
          else { /* old IE support */ b.onreadystatechange=function(){if(this.readyState=='complete'||this.readyState=='loaded'){this.onreadystatechange=null;o.cb()}}; }
        }
        l = o.loc || "head";
        c = a.getElementsByTagName(l)[0];
        if (c) {
          utag.DB("Attach to "+l+": "+o.src);
          if (l == "script") { c.parentNode.insertBefore(b, c); }
          else { c.appendChild(b) }
        }
      }
    } else { u.loader = utag.ut.loader; }
    // End Tealium loader

    u.ev = {view: 1, link:1};

    u.initialized = false;
    
    u.mapFunc = function(arr, obj, item) {
      var i = arr.shift();
      obj[i] = obj[i] || {};
      if (arr.length > 0) {
        u.mapFunc(arr,obj[i], item);
      } else {
        obj[i] = item;
      }
    };
        
    ##UTGEN##
    u.send = function(utag_event, data_layer) { 
      if (u.ev[utag_event] || u.ev.all !== undefined) {
        //##UTENABLEDEBUG##utag.DB("send:##UTID##");

        var a ,b ,c, d, e, f, i;
        a = utag_event
        b = data_layer

        u.data = {
          /* Initialize default tag parameter values here */
          /* Examples: */
          api_key : "YOUR_API_KEY",
          rokt_domain : "https://apps.rokt-api.com",
          is_development_mode: true,
          /* A value mapped to "api_key" or "rokt_domain" in TiQ will replace these default values. */
          "amount": "",
          "billingaddress1": "",
          "billingaddress2": "",
          "billingzipcode": "",
          "cardstatus": "",
          "cartItems": {},
          "confirmationref": "",
          "conversionType": "conversion",
          "currency": "",
          "custom": {},
          "customertype": "",
          "email": "",
          "emailEnc": "",
          "eventtype": "",
          "events": [],
          "gender": "",
          "hashedemail": "",
          "locale": "",
          "Loyaltymember": "",
          "loyaltystatus": "",
          "majorcat": [],
          "majorcatid": [],
          "minorcat": [],
          "minorcatid": [],
          "placementtype": "",
          "price": [],
          "productname": [],
          "paymentserviceprovider": "",
          "quantity": [],
          "shippingtype": "",
          "sku": []
        };

        /* Start Tag-Scoped Extensions Code */
        /* Please Do Not Edit This Section */
        ##UTEXTEND##
        /* End Tag-Scoped Extensions Code */

        /* Start Mapping Code */
        Object.keys(utag.loader.GV(u.map)).forEach(function(mapping_key) {
          if (data_layer[mapping_key] !== undefined && data_layer[mapping_key] !== '') {
            var destinations = u.map[mapping_key].split(',');
            destinations.forEach( function(parameter) {
              if (
                !u.data.hasOwnProperty(parameter) &&
                (parameter.indexOf('cartItems') !== 0)
              ) {
                u.mapFunc(['custom'].concat(parameter.split('.')), u.data, data_layer[mapping_key]);
                return;
              }
              u.mapFunc(parameter.split('.'), u.data, data_layer[mapping_key]);
            });
          } else {
            var event_destinations = mapping_key.split(":");
            if (
              event_destinations.length === 2 &&
              String(data_layer[event_destinations[0]]) === String(event_destinations[1])
            ) {
              if (u.map[mapping_key]) {
                u.data.events = u.data.events.concat(u.map[mapping_key].split(","));
              }
            }
          }
        });

        //   u.initECommerceFields(data_layer);

        var attributes = {
          "amount": u.data.amount,
          "billingaddress1": u.data.billingaddress1,
          "billingaddress2": u.data.billingaddress2,
          "billingzipcode": u.data.billingzipcode,
          "cardstatus": u.data.cardstatus,
          "cartItems": [],
          "ccbin": u.data.ccbin,
          "confirmationref": u.data.confirmationref,
          "conversionType": u.data.conversionType,
          "country": u.data.country,
          "currency": u.data.currency,
          "customertype": u.data.customertype,
          "email": u.data.email,
          "emailEnc": u.data.emailEnc,
          "eventtype": u.data.eventtype,
          "firstname": u.data.firstname,
          "gender": u.data.gender,
          "hashedemail": u.data.hashedemail,
          "language": u.data.language,
          "lastname": u.data.lastname,
          "locale": u.data.locale,
          "Loyaltymember": u.data.Loyaltymember,
          "loyaltystatus": u.data.loyaltystatus,
          "mobile": u.data.mobile,
          "paymentserviceprovider": u.data.paymentserviceprovider,
          "paymenttype": u.data.paymenttype,
          "placementtype": u.data.placementtype,
          "shippingtype": u.data.shippingtype,
          "zipcode": u.data.zipcode
        }

        utag.DB('send:##UTID##:MAPPINGS');
        utag.DB(u.data);
        /* End Mapping Code */
    
        if (!u.data.api_key) {
          utag.DB(u.id + ': Tag not fired: Required attribute api_key not populated');
          return;
        }
    
        /* Start Tag Sending Code */
        var t = u.data.is_development_mode ? 1 : 0, n = "?env=" + t, a = window.mParticle.config.dataPlan;
        
        window.mParticle.config.isDevelopmentMode = u.data.is_development_mode;
        
        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]); });
        
        src = u.data.rokt_domain + "/js/v2/" + u.data.api_key + "/app.js" + n + "&" + s.join("&");
        /* End Tag Sending Code */

        /* Start Loader Callback Function */
        /* Un-comment the single-line JavaScript comments ("//") to use this Loader callback function. */
        
        async function triggerPlacement(identifier) {
            const selection = await window.mParticle.Rokt.selectPlacements({
                identifier: identifier,
                attributes: {
                  "age": attributes.age,
                  "amount": attributes.amount,
                  "billingaddress1": attributes.billingaddress1,
                  "billingaddress2": attributes.billingaddress2,
                  "billingzipcode": attributes.billingzipcode,
                  "cardstatus": attributes.cardstatus,
                  "cartItems": attributes.cartItems,
                  "ccbin": attributes.ccbin,
                  "confirmationref": attributes.confirmationref,
                  "country": attributes.country,
                  "currency": attributes.currency,
                  "customertype": attributes.customertype,
                  "email": attributes.email,
                  "emailEnc": attributes.emailEnc,
                  "eventtype": attributes.eventtype,
                  "firstname": attributes.firstname,
                  "gender": attributes.gender,
                  "hashedemail": attributes.hashedemail,
                  "language": attributes.language,
                  "lastname": attributes.lastname,
                  "locale": attributes.locale,
                  "Loyaltymember": attributes.Loyaltymember,
                  "loyaltystatus": attributes.loyaltystatus,
                  "mobile": attributes.mobile,
                  "paymentserviceprovider": attributes.paymentserviceprovider,
                  "paymenttype": attributes.paymenttype,
                  "placementtype": attributes.placementtype,
                  "shippingtype": attributes.shippingtype
                }
            });
        }

        u.loader_cb = function () {
          
          /* Start Loader Callback Tag Sending Code */
          u.data.events.forEach(function(event) {
            if (["bag", "checkout", "confirmation"].includes(event)) {
              if (attributes.email !== null || attributes.emailsha256 !== null) {
                var userIdentities = {}
                attributes.email && (userIdentities.email = attributes.email)
                attributes.emailsha256 && (userIdentities.email = attributes.emailsha256)
                var identifyRequest = { 
                  userIdentities: userIdentities
                }; 
                mParticle.Identity.identify(identifyRequest);
              }
            }
            
            if (event == "bag") {
              window.mParticle.ready(
                triggerPlacement("bag_page")
              );  
            }
            if (event == "checkout") {
              window.mParticle.ready(
                triggerPlacement("checkout_page")
              );  
            }
            if (event == "confirmation") {
              window.mParticle.ready(
                triggerPlacement("confirmation_page")
              );  
            }
          });
          
          /* End Loader Callback Tag Sending Code */
        };

        /* End Loader Callback Function */

        /* Start Loader Function Call */
        /* Un-comment the single-line JavaScript comments ("//") to use Loader. */

        if (!u.initialized) {
          u.loader({
            "type" : "script",
            "src" : src,
            "cb" : u.loader_cb,
            "loc" : "script",
            "id" : 'utag_##UTID##'
          });
          u.initialized = true;
        } 
        else {
          u.loader_cb();
        }

        /* End Loader Function Call */

        //##UTENABLEDEBUG##utag.DB("send:##UTID##:COMPLETE");
      }
    };
    utag.o[loader].loader.LOAD(id);
  })("##UTID##", "##UTLOADERID##");
} catch (error) {
  utag.DB(error);
}
//end tealium universal tag  

Script activation

Under Rules and Events, set your new tag to fire on all pages.

Under Mapped Variables, configure UDO variable mappings for purchase events and data layer variables.

You must configure variables within Tealium according to your specific data layer before mapping them to Rokt. Refer to the Tealium Data Layer Variables for more details about variables.