Back-end / Front-end Bridge
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.
So to ensure consistency between the back-end visitorCode and front-end visitorCode, we came up with the following approach.
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:
First we check if a kameleoonVisitorCode cookie exists. If so, we will use this as the identifier for the visitor code.
If no cookie is found, then the identifier is generated randomly.
The visitorCode is then stored in the browser's Local Storage.
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:
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.
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.
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.
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]);