Web SDK Migration Guide
If you have already integrated the Rokt Web SDK version 2.5926.0 or earlier into your site, and you want to upgrade to the latest version, you will need to make several changes to your code. This migration guide will walk you through the breaking changes introduced in the latest version of the SDK, providing instructions on how to collaborate with your dedicated Rokt account team to bring your integration up to date.
Initializing the Web SDK
The biggest change introduced in the new SDK is how it's initialized within your website. Prior to the current version, Rokt allowed you to initialize, or load, the SDK by calling either the launcher.js or snippet.js scripts from the <head> tags of each page in your site.
Both of these options have been replaced with a single initialization script.
Remove the deprecated launcher.js script
Search your site's code and remove any instances of the launcher.js script.
It should resemble:
<script type="module">
window.RoktLauncherScriptPromise = new Promise((resolve, reject) => {
const target = document.head || document.body;
const script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
script.fetchPriority = "high";
script.crossOrigin = "anonymous";
script.async = true;
script.id = "rokt-launcher";
script.addEventListener('load', () => resolve());
script.addEventListener('error', (error) => reject(error));
target.appendChild(script);
});
</script>
Remove the deprecated snippet.js auto launcher
If you used the auto launcher snippet, search your site's code and remove any instance of the script.
It should resemble:
(function (r, o, k, t, n, e, w, a, _) {
r._ROKT_ = n;
r[n] = r[n] || {
id: t,
h: w,
lc: [],
it: new Date(),
onLoaded: function (c) {
r[n].lc.push(c);
},
};
a = o.createElement("script");
a.type = "text/javascript";
a.async = !0;
a.src = k;
if (e) {
a.integrity = e;
a.crossOrigin = "anonymous";
}
_ = o.getElementsByTagName("script")[0];
_.parentNode.insertBefore(a, _);
})(
window,
document,
"https://apps.rokt.com/wsdk/integrations/snippet.js",
"roktAccountid",
"rokt"
);
Insert the new SDK initialization snippet
After removing any instance of the old SDK snippets, insert the new SDK initialization snippet into the <head> tag of each page of your site. If your site is a multi-page application that uses templates, make sure to update your templates so that this new snippet is executed as early as possible on each page load.
New Rokt Web SDK initialization snippet
<script type="text/javascript">
// Enter your Rokt API key
const 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
const 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: {
// If you're using an un-hashed email address, set it in 'email'.
email: 'j.smith@example.com',
// If you're using a hashed email address, set it in 'other' instead of `email`.
other: 'sha256 hashed email goes here'
},
}
},
};
// 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.5; 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.DOMAIN = window.DOMAIN || 'https://apps.rokt-api.com/'; c.src = DOMAIN + "/js/v2/" + e + "/app.js" + n + "&" + s.join("&"); var l = document.getElementsByTagName("script")[0]; l.parentNode.insertBefore(c, l); })(API_KEY);
</script>
The new snippet introduces several new configuration options:
Rokt API key
Previously, you needed to enter your Rokt Account ID into your SDK snippet. This requirement has been replaced by the Rokt API Key.
Your Rokt account representative will provide you your Rokt API Key.
First-party domain
The new Web SDK allows you to route requests to Rokt through your own subdomain. This is referred to as a "first-party domain integration" and can help prevent content from being blocked.
To use a custom subdomain with your integration, follow the instructions in First Party Domain Integration, then replace the value of DOMAIN in your initialization snippet with your own subdomain:
const DOMAIN = "your-new-subdomain-goes-here";
Development mode
Previously, you could set sandbox: true in your SDK snippet to test your integration.
Now, the Rokt SDK includes a configuration option called isDevelopmentMode. By setting this to true, the Rokt SDK will collect and forward data as "development" (aka testing) data. When you're done testing your integration, change isDevelopmentMode to false.
User identification on initialization
During initialization, the SDK submits an identifyRequest to Rokt using either the user's raw or hashed email address (whichever you can provide) to identify the current user. You can supply either the raw or hashed email address within identifyRequest inside your initialization scripts config settings with:
identifyRequest: {
userIdentities: {
// If you're using an un-hashed email address, set it in 'email'.
email: 'j.smith@example.com',
// If you're using a hashed email address, set it in 'other' instead of `email`.
other: 'sha256 hashed email goes here'
},
}
Identify the user
If you can't provide the user's email address when the SDK is initialized, you should identify the user as soon as they provide their email address by calling the identify method after the SDK has initialized.
If you are providing an un-hashed email address, use:
const identityRequest = {
userIdentities: {
email: 'j.smith@example.com'
}
};
mParticle.Identity.identify(identityRequest);
If you are providing a hashed email address, use:
const identityRequest = {
userIdentities: {
other: 'sha256 hashed email goes here'
}
};
mParticle.Identity.identify(identityRequest);
Setting user attributes
Once you have identified the the current user, you can set descriptive user attributes that will be included with any ad placements or logged events. You can also set user attributes directly when inserting a placement.
To set user attributes, run the following after the SDK has initilaized and you have identified the user:
// To retrieve the current user, call getCurrentUser. This will only succeed if you have identified the user during SDK initialization or by calling the identify method.
const currentUser = mParticle.Identity.getCurrentUser();
// Once you have successfully set the current user to a const called `currentUser`, you can set user attributes with:
currentUser.setUserAttribute("user-attribute-name", "user-attribute-value");
// Note: all user attributes (including list attributes and tags) must have distinct names.
// Rokt recommends setting as many of the following user attributes as possible:
currentUser.setUserAttribute("firstname", "John");
currentUser.setUserAttribute("lastname", "Doe");
// Phone numbers can be formatted either as '1234567890', or '+1 (234) 567-8901'
currentUser.setUserAttribute("mobile", "3125551515");
currentUser.setUserAttribute("age", "33");
currentUser.setUserAttribute("gender", "M");
currentUser.setUserAttribute("city", "Brooklyn");
currentUser.setUserAttribute("state", "NY");
currentUser.setUserAttribute("zip", "123456");
currentUser.setUserAttribute("dob", "yyyymmdd");
currentUser.setUserAttribute("title", "Mr");
currentUser.setUserAttribute("language", "en");
currentUser.setUserAttribute("value", "52.25");
currentUser.setUserAttribute("predictedltv", "136.23");
// To set a list attribute, set the value of the attribute to an array of strings. For example:
currentUser.setUserAttribute("favorite-genres", ["documentary", "comedy", "romance", "drama"]);
// To remove a user attribute, call removeUserAttribute and pass in the attribute name. All user attributes share the same key space.
currentUser.removeUserAttribute("attribute-to-remove");
Inserting placements
The script used to insert a placement in your site has also been replaced in the new SDK.
Deprecated selectPlacements method:
Previously, to insert a placement you would call selectPlacements after the Rokt SDK launcher script completed:
<script type="module">
await window.RoktLauncherScriptPromise;
const launcher = await window.Rokt.createLauncher({
accountId: "rokt-account-id",
sandbox: true,
});
await launcher.selectPlacements({
attributes: {
email: "",
firstname: "",
lastname: "",
confirmationref: "",
billingzipcode: "",
amount: "",
paymenttype: "",
ccbin: "",
mobile: "",
country: "",
language: "",
currency: "",
billingaddress1: "",
billingaddress2: "",
age: "",
gender: "",
cartItems: JSON.stringify(cartItems),
},
});
</script>
This has been replaced with the mParticle.Rokt.selectPlacements method:
New selectPlacements method:
To insert a placement, call the new mParticle.Rokt.selectPlacements after you've initialized the SDK. Similar to the previous section, you can supply a list of attributes to improve the relevance of the content shown to your customer.
window.mParticle.Rokt.selectPlacements({
attributes: {
"email": "j.smith@example.com", // Customer email address used at checkout
"firstname": "Jenny", // Customer first name
"lastname": "Smith", // Customer last name
"confirmationref": "54321", // Order / confirmation reference number
"billingzipcode": "90210", // Billing zip or postcode of customer
"amount": "", // Decimal transaction amount e.g. 300.5
"paymenttype": "", // E.g. Gift card | Chase, Visa
"ccbin": "", // Credit card bin e.g. 372888
"mobile": "", // Customer mobile / cell number
"country": "", // ISO Alpha-2 Country Code
"language": "", // ISO 639-1 2 letter lanugage code
"currency": "", // Transaction currency e.g. USD
"billingaddress1": "", // Customer address line 1
"billingaddress2": "", // Customer address line 2
"age": "", // Customer age
"gender": "", // Customer gender m / f
"cartItems": JSON.stringify(["item 1", "item 2", "item 3"]), // Stringified cart contents
// You can also pass extra attributes relevant to the transaction here
// See link below for a full list of attributes
shippingtype: "Priority Express"
}
});
Implement event tracking
The new Rokt SDK makes it easy to collect event and user attributes. To learn how to implement these new tracking methods into your site, see the new Getting Started for Ecommerce or Getting Started for Advertisers guides.