Tealium Integration for Advertisers
This page explains how to implement Rokt Ads using Tealium to close the loop by linking conversions back to your campaigns. By linking conversions back to your Ads engagement, you can enable more accurate attribution, real-time optimization, and campaign measurement.
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 log conversions.
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 conversion event, use the following code in your app when a conversion happens:
utag.view({tealium_event : 'purchase', email_address : 'john.doe@example.com', amount:'20.00', currency:'USD', confirmationref:'123456789'})
The integration requires confirmationref, amount, and currency. email_address is optional if you are not using rclid to close the loop.
Initialize the Rokt SDK
- Log in to your Tealium account.
- Click Tags in the left hand navigation.
- Click the New Tag button on the right side, then select Tealium Custom Container.
- Enter a description name for your tag, like "Rokt SDK".
- Under Edit Template, paste the SDK initialization snippet provided below.
- Replace
api_keyinsideu.datawith the Rokt API key provided by your Rokt account manager. - Change the value of
rokt_domainwithinu.datato your own domain if you are setting up a first party domain integration. - 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: data_layer.tealium_environment == "prod" ? false : true,
/* A value mapped to "api_key" or "rokt_domain" in TiQ will replace these default values. */
email: '',
conversionType: "conversion",
confirmationref: "",
amount: "",
currency: "",
price: [],
quantity: [],
majorcat: [],
majorcatid: [],
minorcat: [],
minorcatid: [],
productname: [],
sku: [],
cartItems: {},
custom: {},
events: [],
};
/* 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 = {
conversionType: u.data.conversionType,
email: u.data.email,
firstname: u.data.firstname,
lastname: u.data.lastname,
mobile: u.data.mobile,
confirmationref: u.data.confirmationref,
amount: u.data.amount,
currency: u.data.currency,
paymenttype: u.data.paymenttype,
zipcode: u.data.zipcode,
country: u.data.country,
language: u.data.language,
ccbin: u.data.ccbin,
cartItems: []
}
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;
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. */
u.loader_cb = function () {
/* Start Loader Callback Tag Sending Code */
u.data.events.forEach(function(event) {
if (event == "conversion"){
window.mParticle.ready(
function() {
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);
}
var currentUser = mParticle.Identity.getCurrentUser();
var transactionObject = {}
attributes.conversionType && (transactionObject.conversiontype = attributes.conversionType)
attributes.confirmationref && (transactionObject.confirmationref = attributes.confirmationref)
attributes.amount && (transactionObject.amount = attributes.amount)
attributes.currency && (transactionObject.currency = attributes.currency)
mParticle.logEvent(
"conversion", // The name of the event
mParticle.EventType.Transaction, // The event type
transactionObject
);
}
);
}
});
/* 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 the conversion event and data layer variables.
Mapping your variable names
You should map your Tealium variables to the following Rokt fields:
emailaddressconfirmationrefamountcurrency
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.