Kameleoon provides native integrations with analytics or CDPs platforms, and in hybrid mode, you can use any integration in combination with server-side experiments, without needing to write additional code.
This article describes how to implement an optimal integration between the Kameleoon server-side SDK and the Kameleoon front-end application file, 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.
To ensure the reliable performance of Kameleoon on Safari browsers, we now recommend implementing a back-end/front-end bridge for ITP management, even if you do not directly use Kameleoon Feature Experimentation. This allows to you overcome Intelligent Tracking Prevention (ITP) limitations so that Kameleoon functions seamlessly.
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 back-end, you need to use the
getVisitorCode()method available in all our server-side SDKs. Make sure to call this method every time you need to obtain a visitor identifier before using any other SDK methods. The
getVisitorCode()takes an optional string argument that you can use to pass your own identifier rather than rely on a randomly generated Kameleoon ID. When the method is called, Kameleoon first looks for a kameleoonVisitorCode cookie or query parameter associated with the current HTTP request. If found, the SDK uses this as the visitor identifier.
If no cookie or parameter is found, Kameleoon uses the
getVisitorCode() method argument, if you provided one, as the identifier. If you don't provide an argument, Kameleoon randomly generates the ID. In either of these cases, Kameleoon also sets the server-side kameleoonVisitorCode cookie with the value (via HTTP header).
If you don't use an SDK, there are other other methods you can use to perform the synchronization, such as adding a code snippet on your backend server. See the synchronization options in the Advanced implementation guide.
By following this approach, the visitorCode is coherently saved and shared between front-end and back-end. 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
getVisitorCode() is not called (or the synchronization snippet is not ran) 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 front-end tracking code (Hybrid Experimentation)
If you follow these guidelines, and you already use a standard client-side tagging plan for Kameleoon, then you don't even need to implement conversion calls on the back-end when using server-side experiments (although this can still be useful). Goals and conversions will be tracked via the front-end and will appear automatically in Kameleoon reports. This will also allow you to get experiment results in any Web Analytics solution with an integration to Kameleoon (Adobe Analytics, GA4, Mixpanel, Amplitude, etc).
To link your server-side experiments with the front end, you need to configure triggering as described in the following section.
Ensuring correct triggering on the front-end
Our front-end engine needs to know whenever an experiment has taken place in the back-end, ie when a visitor has been bucketed into an experiment. This is important in order to count only visitors that have actually seen / triggered the experiment. To achieve this, you need to use the
const engineTrackingCode = `
window.kameleoonQueue = window.kameleoonQueue || ;
window.kameleoonQueue.push(['Experiments.assignVariation', 123456, 7890]);
window.kameleoonQueue.push(['Experiments.trigger', 123456, true]);
const script = document.createElement('script');
script.textContent = engineTrackingCode;