メインコンテンツまでスキップ

Web SDK Migration Guide

This guide explains how to migrate from older versions of the Rokt Web SDK (version 2.5926.0 or earlier) to the latest version. It’s relevant to both Rokt Ecommerce and Rokt Ads implementations, and walks you through breaking changes—like the updated initialization script—and how to coordinate with your Rokt account team to complete the migration smoothly.

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 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: {
                // 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.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>

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.

const selection = await 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.

この記事は役に立ちましたか？