Web server modules
Kameleoon has traditionally allowed the operation of A/B tests at the front-end level (using a JavaScript engine) or at the back-end level (using a server-side SDK). However, because extensive caching strategies are common for performance reasons, HTTP requests may never reach the back-end application servers. Instead, a front-facing web server replies directly with a cached version of the requested page. In these configurations, server-side SDKs cannot be used, since the logic of allocating a visitor to an experiment happens in the back-end application code, which means many requests cannot be processed because a cached version of the page is returned instead. In other words, the code implementing traffic repartition to variations of an experiment would not be run.
To solve this challenge, Kameleoon A/B testing modules are available for the major web servers. This allows the web server to determine the variation used by each visitor. The server can reply with a cached version of the correct variation, so the application can benefit from standard caching strategies.
Web testing at the web server level is an intermediary level between the front-end and the back-end.
General concepts
A Kameleoon web server module is a low-level component (written in C for optimal performance) that performs variation allocation whenever an HTTP request triggers an A/B experiment. It then (internally) redirects the request to a potentially different URL corresponding to the chosen variation.
For example, if a visitor hits the page https://www.shop.com/plasma-tvs.html and there is a running experiment on that category page, with three variations, the web server redirects the HTTP request internally to either https://www.shop.com/plasma-tvs.html (original version), https://www.shop.com/plasma-tvs.html?version=B (first variation) or https://www.shop.com/plasma-tvs.html?version=C (second variation). It then returns a cached version of these pages (or passes the call to the application server to generate a new one if the TTL value has expired).
The A/B/C test is completely transparent to end users. The visitor only sees the canonical URL https://www.shop.com/plasma-tvs.html in the browser.
Setup and configuration of the experiment (including setting the target and redirection URLs; for example, by adding the ?version=B parameter) are completed in the Kameleoon platform. The web server module periodically refreshes its configuration from the Kameleoon servers and database. For convenient planning and deployment of A/B tests, all usual Kameleoon features are available, including starting, pausing, and stopping tests; changing deviation; and modifying configuration.
Due to the technical constraints of the client-server model on the web, using URL conditions is the only way to configure experiment targeting at the web server level. Similarly, always use URL redirects in Kameleoon to configure variations at the web server level. The negative performance and SEO impacts associated with front-end (browser) redirection are not an issue with web server redirects. Instead, internal web server redirects are perfectly safe and considered a good practice because they are processed internally on the web server (they're fast) and are transparent to search engine crawlers.
Operating web server A/B experiments
-
In the Kameleoon app, create a new A/B experiment, with the Code editor.
-
In Kameleoon, create the variations you want to implement for the experiment. For each variation, choose the URL redirection option and enter the desired new URL.
-
Choose the targeting of the experiment by adding one or more URL targeting conditions. Any matched URL on the web server will trigger the web server module for the request and activate an internal redirect. The module stores a (first-party) cookie named kameleoonVisitorCode for matched requests.
Only URL redirection options are taken into account for web-server experiments. Any other modifications on the variations, such as JavaScript or CSS code changes via the graphical editor, are ignored.
You can then choose the deviation and launch the experiment as usual. Pausing or stopping the experiment also works as expected.
Traffic exclusion does not work with web server A/B experiments. Analytics for the original version of the experiment will include data from visitors in the excluded bucket, instead of excluding those visitors from the experiment entirely.
To help with potential treatments on the server-side (tracking, implementation of variations), the web server adds an HTTP header to any request that matches a Kameleoon experiment, when the option is turned on in Nginx config file (kameleoon_headers on;). The first header is named kameleoon-experiment and its content is in the format experimentID=variationID, where experimentID represents the triggered experiment ID, and variationID represents the ID of the variation assigned. The second header is named kameleoon-redirection and its content is in the format variationID=redirectionURL, where variationID represents the ID of the variation assigned and redirectionURL represents parameter used for the redirection.
Supported platforms
Nginx server module
The module supports version 1.18.0, 1.20.2 and 1.21.4 of Nginx; the Docker package is available here.
The latest version of the module supports version 1.27.1 of Nginx; the Docker package is available here.
The module is tested under an x86_64 architecture.
A Python script must also be installed in parallel (and launched periodically via a CRON job; 30 or 60 minute intervals are recommended). Automation API credentials (for OAuth 2.0 Authentication) are required to use the script. See the API credentials article for details.
Apache HTTPd server module (deprecated)
The Apache httpd module supports version 2.4 and has been tested on a CentOS distribution with an x86_64 CPU architecture.
A Python script must also be installed in parallel (and launched periodically via a CRON job; 30 or 60 minute intervals are recommended). This script refreshes or updates the generated Nginx configuration file required by the Kameleoon module. The script also reloads the configuration file.