gatsby-plugin-kameleoon

Easily add Kameleoon — A/B Testing and personalization platform — to your Gatsby site.

Contents

• Installation
• How to use
• Recommended implementation Method
• Use with Tag Manager
• Install Asynchronous Script ( without Anti-Flicker )
• Install Synchronous Script
• Cross-Domain Tracking

Installation

npm install gatsby-plugin-kameleoon

How to use

By default, you should use the installation method recommended by Kameleoon, which consists of adding a script tag in the head of each page of your site with the anti-flicker option which avoids a bad user experience for your customers.

If you have no choice but to use a tag manager on your site, which is not recommended by Kameleoon, please read the following section about how to install Kameleoon with a Tag Manager.

If the methods below do not meet your needs, consider the following methods: install asynchronous script without anti-flicker or install synchronous script.

Besides these considerations, if you need to track your customers across different sites or subdomains that belong to you (different protocols are considered as different domains), you will need to additionally follow the cross-domain tracking implementation method.

Recommended implementation Method

Our official recommended implementation method is Asynchronous Loading, with Anti-Flicker. This recommended implementation is the safest one. Using an asynchronous script guarantees you that Kameleoon can not block the load your web site. And the added white overlay on the page "simulates" the effect of a synchronously loaded script, preventing flickering.

Edit the gatsby-config.js file as follows by setting only the siteCode option if you want to add the recommended script to your site.

// In your gatsby-config.js
plugins: [
  {
    resolve: "gatsby-plugin-kameleoon",
    options: {
      
      // see how to find your personnal site code (site ID) here: 
      // https://help.kameleoon.com/question/how-do-i-find-my-site-id/
      siteCode: "YOUR_SITE_CODE",
    }
  }
]

then follow the cross-domain tracking implementation method if you need to track your customers across different sites or subdomains.

Use with Tag Manager

This plugin is not able to finalize the installation of Kameleoon for you in this situation. To complete the installation of Kameleoon on your site, you will need to copy the following code snippet and paste it in your Tag Manager interface.

Remember to replace "YOUR_SITE_CODE" with your own in the snippet below. Read this Kameleoon documentation article if you need help finding your own site code.

var scriptNode = document.createElement("script");
scriptNode.src = "//YOUR_SITE_CODE.kameleoon.eu/kameleoon.js";
scriptNode.type = "text/javascript";
scriptNode.async = true;
scriptNode.setAttribute("data-tagmanager", true);
document.head.appendChild(scriptNode);

If you need to configure Kameleoon for cross-domain tracking, please edit the gatsby-config.js file as follows setting only the tagManager: true option then follow the cross-domain tracking implementation method.

// In your gatsby-config.js
plugins: [
  {
    resolve: "gatsby-plugin-kameleoon",
    options: { tagManager: true }
    // cross-domain tracking option, follow further instructions
  }
]

Install Asynchronous Script ( without Anti-Flicker )

Edit the gatsby-config.js file as follows if you want to install the asynchronous version of Kameleoon without anti-flicker and if you don't use a Tag Manager.

// In your gatsby-config.js
plugins: [
  {
    resolve: "gatsby-plugin-kameleoon",
    options: {
      
      // see how to find your personnal site code (site ID) here: 
      // https://help.kameleoon.com/question/how-do-i-find-my-site-id/
      siteCode: "YOUR_SITE_CODE",

      // specify the script to install 
      script: 'async'
    }
  }
]

Install Synchronous Script

Edit the gatsby-config.js file as follows if you want to install the synchronous version of Kameleoon if you don't use a Tag Manager.

// In your gatsby-config.js
plugins: [
  {
    resolve: "gatsby-plugin-kameleoon",
    options: {
      
      // see how to find your personnal site code (site ID) here: 
      // https://help.kameleoon.com/question/how-do-i-find-my-site-id/
      siteCode: "YOUR_SITE_CODE",

      // specify the script to install 
      script: 'sync'
    }
  }
]

Cross-Domain Tracking

Kameleoon offers support for cross-domain tracking which makes it possible to link sessions on several related sites as a single session. For instance, you may wish to consider that a visit started on https://portal.mysite.com and continued on https://transaction-engine.mysite.com or http://myothersite.fr (which are websites that you own) form a single visit. Note that for technical reasons, different protocols (such as HTTP and HTTPs) also count as different domains for Kameleoon.

To add cross-domain tracking capabilities to Kameleoon you should right-click to save the original iFrame file available here.

This iFrame will be loaded whenever, during the visitor's journey, the page URL does not match the main domain of the website. The iFrame HTML file is static and contains only immuable code used to save and restore visitor data in the Local Storage.

Inside the iFrame code, you should modify two variables (follow the comments inside the file to do so):

• the value of the siteCode variable;
• the value of the allowedDomains variable to remove a potential security / data leak vulnerability.

To finalize cross-domain tracking configuration edit the gatsby-config.js file as follows:

// In your gatsby-config.js
plugins: [
  {
    resolve: "gatsby-plugin-kameleoon",
    options: {
      // other options...
      crossDomainIframeURL: "https://www.yourdomain.com/path/to/kameleoon-iframe.html",
    }
  }
]

find more informations by reading Kameleoon's documentation: https://developers.kameleoon.com/tag-installation.html#cross-domain-tracking