Documentation
NAV Navbar
JavaScript
  • Back-end / Front-end Bridge
  • Back-end / Front-end Bridge

    Introduction

    Operating the Kameleoon platform both on the back-end (via server-side SDKs) and on the front-end (via JavaScript engine) is possible. This approach can actually be beneficial, as it allows you to choose different approaches for different tasks. For instance, your team could decide it is easier to implement and deploy variations on the back-end, but better to perform all tracking on the front-end, seeing as many third-party integrations with web analytics solutions (such as Google Analytics) only work on the front-end.

    This article describes how you can implement an optimal integration between Kameleoon Back-end and Kameleoon Front-end, and have both sides communicate with each other. It assumes Kameleoon is already properly installed in your back-end server as well as in your front-end HTML pages.

    Ensuring user identification consistency between the back-end and the front-end

    One of the challenges of using Kameleoon both on the back-end and the front-end is to make sure each visitor is properly identified as the same individual from both sides. In Kameleoon, this means that the visitorCode, which is a unique id for every user / visitor, has to be identical everywhere. This allows correct tracking of the visitor's actions, which in turn leads to correct data and statistics. Ie, a user registered with the visitorCode 10ctbql0zpf4rwjy for a variation of an experiment in the back-end also has to be associated with the same visitorCode when a conversion is triggered in the front-end.

    From back-end to front-end, communication is easy (for instance via embedded JavaScript code in the HTML pages). But sending information from front to back can be difficult for a third party platform with an integration that needs to be as painless as possible. The only practical way is to write a cookie, that our back-end SDKs will read and use. However, recent developments with Apple's Intelligent Tracking Prevention (ITP) technology, as well as similar approaches from other browser vendors, heavily restrict what JavaScript based solutions can do. With ITP 2.1, cookies deposited via JavaScript can only have a lifespan of seven days before expiring.

    So to ensure consistency between the back-end visitorCode and front-end visitorCode, we came up with the following approach.

    Client-side

    On the front-end side, a visitorCode is generated and assigned for every new visitor. A visitor is technically considered a new visitor if no previous visitorCode can be found by the engine for this user. This usually happens when the Kameleoon engine is run for the first time on the visitor's browser. The logic of the visitorCode assignment is the following:

    1. First we check if a kameleoonVisitorCode cookie exists. If so, we will use this as the identifier for the visitor code.

    2. If no cookie is found, then the identifier is generated randomly.

    3. The visitorCode is then stored in the browser's Local Storage.

    When Kameleoon is only used on the front-end, this means that visitorCode identifiers are always assigned randomly in the JavaScript engine. But if it is used on both sides, the JS engine can also obtain the identifier from a cookie passed from the back-end. This allows the identifier to be set by the server, rather than in the front-end.

    Server-side

    On the back-end, we designed the obtainVisitorCode() method in our SDKs. You should make sure to call this method everytime you need to obtain a visitor identifier, usually before triggering a server-side experiment via our SDKs. The obtainVisitorCode() takes an optional string argument, and implements the following logic:

    1. First we check if a kameleoonVisitorCode cookie or query parameter associated with the current HTTP request can be found. If so, we will use this as the visitor identifier.

    2. If no cookie / parameter is found in the current request, we either randomly generate a new identifier, or use the given argument as identifier if it is passed. This allows our customers to use their own identifiers as visitor codes, should they wish to. This can have the added benefit of matching Kameleoon visitors with their own users without any additional look-ups in a matching table.

    3. In any case, the server-side (via HTTP header) kameleoonVisitorCode cookie is set with the value. Then this identifier value is finally returned by the method.

    Conclusions and remarks

    By following this approach, the visitorCode is coherently saved and shared between front-end and back-end, and cross-domain and ITP restrictions are also correctly taken into account. If an experiment is implemented on the first page of a visitor's journey on your website, the back-end will generate the identifier and pass it to the front. If the journey starts on a page where obtainVisitorCode() is not called on the back-end, then the front-end will generate the identifier first, pass it to the back-end, which will read it and then rewrite it as a server-side cookie to bypass ITP restrictions.

    Cross-domain problems are also automatically treated. The only difficult case consists in a change of top-level domain with a server-side triggered experiment on the first page of the new top-level domain. In this setup, the cookie associated with the previous domain cannot be read on the new domain, and the Kameleoon JS engine won't have had the opportunity to run and restore the identifier from the Local Storage yet. So, if possible, you should pass the visitor code as a kameleoonVisitorCode HTTP query parameter from the old domain to the new one. Another solution is to wait until Kameleoon's JavaScript engine has run once on the new domain before accessing server-side SDK methods.

    Linking server-side experiments with third-party Analytics platforms

    If you setup a server-side Kameleoon experiment but want to follow the results on a third-party solution, for example Google Analytics, a bit of work is required. This is because most Web Analytics platforms perform their tracking only on the front-end. So the experiment must be registered both as a server-side AND a normal front-end one in Kameleoon, in order to benefit from Kameleoon's integration with the target third party platform. This way, the front-end experiment will have access to the assigned variation (remember, the assignment took place on the server).

    var kameleoonQueue = kameleoonQueue || [];
    const experimentID = 1; // this value must be correctly entered and corresponds to the experiment's ID in Kameleoon
    const variationID = 3; // this value must be correctly entered and usually corresponds to the value returned by the triggerExperiment() method
    kameleoonQueue.push(['Experiments.assignVariation', experimentID, variationID]);
    

    It is recommended to take advantage of the Kameleoon Command Queue and the Activation JavaScript API to carry out the integration, as shown in the example on the right. This JavaScript snippet must be generated by the back-end side. It can be for example embedded in the returned HTML page. Usually, it should be generated where the experiment's triggering code is written, since this is where you will have easy access to the variationID.

    Don't forget to activate the desired integration (Google Analytics, Adobe Omniture...) on the front-end experiment via the standard Kameleoon interface. The relevant data will then be automatically sent to the third party platform by the Kameleoon JavaScript engine.