Unify session data storage across subdomains

Track visitors and unify session data (like page views and targeting criteria) across multiple subdomains within the same top-level domain.

Kameleoon allows you to unify session data across all subdomains. In this mode, Kameleoon tracks visitors across multiple subdomains within the same top-level domain. For example, Kameleoon can record a visit that started on one subdomain and continued on another as a single visit in local storage. Kameleoon recommends enabling this option to use session data across all subdomains for advanced behavioral targeting in personalization campaigns. This configuration unifies the data stored in the local storage for all subdomains.

If you choose an implementation tag that does not support unified session data, Kameleoon tracks a visit that starts on one subdomain as a new visit on the user’s device local storage once it reaches another subdomain. This means that Kameleoon resets all data gathered on one subdomain (such as page views and time spent on site) on the new subdomain. As a result, targeting based on these criteria can produce unexpected results. For example, if you have a personalization campaign that triggers on the fourth page view, a visitor who sees three pages on the first domain and loads a fourth page on a subdomain will only trigger the personalization if you enable unified session data.

Local storage partitioning on different subdomains does not impact data collected for analytics. This option is necessary only for campaigns that span across subdomains or use data stored locally across different subdomains.

Availability:

Safari browsers do not support unified session data due to Local Storage Partitioning restrictions. To address this, Kameleoon provides a fetching mechanism using a Server Synchronization Call (SSC). Using this method, Kameleoon obtains the visitorCode from the (server-set) kameleoonVisitorCode cookie. Kameleoon then checks if the current LocalStorage visitorCode is empty. If it is empty, Kameleoon performs an SSC to fetch all data present in LocalStorage from the Kameleoon backend servers. Once this call completes, Kameleoon restores the data to its previous state.

Kameleoon enables this option by default on the Safari browser.

Unified session data tracking tag

To enable unified session data in Kameleoon, host an <iframe> file (provided below) on your website’s main (top-level) domain. This iframe loads whenever a visitor navigates to a page with a URL that does not match the main domain of the website. The iframe HTML file is small, static, and contains only immutable code used to save and restore visitor data in Local Storage.

Kameleoon recommends fetching the original file at this URL: https://developers.kameleoon.com/resources/iframe_template.html. You can also download the file directly (right-click the link and select Save link as…).

Inside the iframe code, modify two variables:

• The value of the siteCode variable with your own project site code.
• The value of the allowedDomains variable. Setting this variable to allow only your domains removes a potential security and data leak vulnerability.

To ensure optimal performance, set up caching for the iframe file. Since the file remains static, the browser does not need to download it multiple times. Configure caching on the server using the following HTTP header: Cache-Control: max-age=2592000

In addition to hosting the iframe, include the following installation snippet. Provide the correct value for the kameleoonIframeURL variable. Set this variable to the URL where the iframe is accessible on your website.

<script>
  // Change the value of this URL to point to your own URL, where the iFrame is hosted
  window.kameleoonIframeURL = "https://www.customerdomain.com/path/to/kameleoon-iframe.html";

  window.kameleoonLightIframe = false;
  var kameleoonIframeOriginElement = document.createElement("a");
  kameleoonIframeOriginElement.href = kameleoonIframeURL;
  window.kameleoonIframeOrigin = kameleoonIframeOriginElement.origin || (kameleoonIframeOriginElement.protocol + "//" + kameleoonIframeOriginElement.hostname);
  if (location.href.indexOf(window.kameleoonIframeOrigin) != 0) {
    window.kameleoonLightIframe = true;
    var kameleoonProcessMessageEvent = function(event) {
      if (window.kameleoonIframeOrigin == event.origin && event.data.slice && event.data.slice(0,9) == "Kameleoon") {
        window.removeEventListener("message", kameleoonProcessMessageEvent);
        window.kameleoonExternalIFrameLoaded = true;
        if (window.Kameleoon) {
          Kameleoon.Utils.runProtectedScript(event.data);
          Kameleoon.Analyst.load();
        } else {
          window.kameleoonExternalIFrameLoadedData = event.data;
        }
      }
    };
    if (window.addEventListener) {
      window.addEventListener("message", kameleoonProcessMessageEvent, false);
    }
    var iframeNode = document.createElement("iframe");
    iframeNode.src = kameleoonIframeURL;
    iframeNode.id = "kameleoonExternalIframe";
    iframeNode.style = "float: left !important; opacity: 0.0 !important; width: 0px !important; height: 0px !important;";
    document.head.appendChild(iframeNode);
  }
</script>

Host the iframe file on your servers in the main domain of the website. For multiple subdomains, choose the most significant one. This step is mandatory for technical teams. Kameleoon always uses the main domain to store content in the browser’s Local Storage. If the current URL matches the main domain, the Kameleoon engine can directly write data to the associated Local Storage space. If the URL belongs to another domain, Kameleoon loads the iframe file, which contains static code that can only read and write Kameleoon data on the main domain.

You can use the unified session data snippet in a Tag Manager installation.

Unified tag with anti-flicker

If you use the unified tag and the asynchronous tag with anti-flicker, you must add the three script tags in the following order:

1. Asynchronous tag with anti-flicker.
2. Unified session data script.
3. Kameleoon installation tag.

<script>
  // Duration in milliseconds to wait while the Kameleoon application file is loaded
  var kameleoonLoadingTimeout = 750;

  window.kameleoonQueue = window.kameleoonQueue || [];
  window.kameleoonStartLoadTime = Date.now();
  if (! document.getElementById("kameleoonLoadingStyleSheet") && ! window.kameleoonDisplayPageTimeOut) {
    var kameleoonS = document.getElementsByTagName("script")[0];
    var kameleoonCc = "html::after { content: ''; position: fixed; inset: 0; background: #fff; z-index: 2147483647; }";
    var kameleoonStn = document.createElement("style");
    kameleoonStn.type = "text/css";
    kameleoonStn.id = "kameleoonLoadingStyleSheet";
    if (kameleoonStn.styleSheet) {
      kameleoonStn.styleSheet.cssText = kameleoonCc;
    } else {
      kameleoonStn.appendChild(document.createTextNode(kameleoonCc));
    }
    kameleoonS.parentNode.insertBefore(kameleoonStn, kameleoonS);
    window.kameleoonDisplayPage = function(fromEngine) {
      if (!fromEngine) {
        window.kameleoonTimeout = true;
      }
      if (kameleoonStn.parentNode) {
        kameleoonStn.parentNode.removeChild(kameleoonStn);
      }
    };
    window.kameleoonDisplayPageTimeOut = window.setTimeout(window.kameleoonDisplayPage, kameleoonLoadingTimeout);
  }

</script>

<script>
  // Change the value of this URL to point to your own URL, where the iFrame is hosted
  window.kameleoonIframeURL = "https://www.customerdomain.com/path/to/kameleoon-iframe.html";

  window.kameleoonLightIframe = false;
  var kameleoonIframeOriginElement = document.createElement("a");
  kameleoonIframeOriginElement.href = kameleoonIframeURL;
  window.kameleoonIframeOrigin = kameleoonIframeOriginElement.origin || (kameleoonIframeOriginElement.protocol + "//" + kameleoonIframeOriginElement.hostname);
  if (location.href.indexOf(window.kameleoonIframeOrigin) != 0) {
    window.kameleoonLightIframe = true;
    var kameleoonProcessMessageEvent = function(event) {
      if (window.kameleoonIframeOrigin == event.origin && event.data.slice && event.data.slice(0,9) == "Kameleoon") {
        window.removeEventListener("message", kameleoonProcessMessageEvent);
        window.kameleoonExternalIFrameLoaded = true;
        if (window.Kameleoon) {
          Kameleoon.Utils.runProtectedScript(event.data);
          Kameleoon.Analyst.load();
        } else {
          window.kameleoonExternalIFrameLoadedData = event.data;
        }
      }
    };
    if (window.addEventListener) {
      window.addEventListener("message", kameleoonProcessMessageEvent, false);
    }
    var iframeNode = document.createElement("iframe");
    iframeNode.src = kameleoonIframeURL;
    iframeNode.id = "kameleoonExternalIframe";
    iframeNode.style = "float: left !important; opacity: 0.0 !important; width: 0px !important; height: 0px !important;";
    document.head.appendChild(iframeNode);
  }
</script>
<script src="//SITE_CODE.kameleoon.io/engine.js" fetchpriority="high" async></script>

If you cannot host an iframe, Kameleoon provides the Server Synchronization Call (SSC) mechanism. This feature retrieves all visitor data from Kameleoon’s backend servers when a visitor moves from the main domain to a subdomain. After the call, Kameleoon stores the data in the browser’s Local Storage for targeting purposes.

To enable this option, contact your Customer Success Manager.

Note the following:

• SSC may increase the likelihood of flickering in experiments if the targeting segment includes data stored from previous visits or pages, as the Kameleoon engine waits for the data.
• Some features, such as Simulation Mode, will not work when simulating an experiment that runs across multiple domains. To use this feature, launch the simulation on both domains.

Unified session data vulnerability

When using a setup with unified session data, a potential security issue can arise. Because Kameleoon writes all visitor data in local storage belonging to an external domain, a malicious website could potentially read this data by including your iframe in their page. Once loaded, the iframe would always return the Kameleoon data using a postMessage() call. The response could include custom data containing confidential or sensitive information.

This exploit only affects visitors who first visit your website and then visit the malicious site. Therefore, an attacker cannot obtain data for all your visitors. To enhance security, restrict access to the iframe to a specified list of domains and subdomains. Provide this list in the allowedDomains variable within the static iFrame file.

Kameleoon uses the following three measures to enhance the security of the iframe:

1. Restricting access to identified domains: The iframe code includes an allowedDomains variable that specifies the domains authorized to request the iframe. Only listed domains can load and execute code from the Kameleoon iframe.
2. Restricting access to identified site codes: The iframe code includes a siteCode variable that ensures only a Kameleoon engine with the specified site code can request the iframe.
3. Prefixed Local Storage: The iframe and Kameleoon only read and write entries that begin with the “kameleoon” prefix. Kameleoon cannot read or write any other data, which adds an extra layer of security.

To enable unified session data, the Kameleoon iframe must load on all of your domains. Do not set an X-Frame-Options response header.

Kameleoon hosts projects on either kameleoon.eu or kameleoon.io depending on their creation date. Use the domain displayed in the Kameleoon App for your project.