Documentation
NAV Navbar
  • Legal Consent
  • Legal Consent

    Context

    Depending on the country you are operating your website in, it may be necessary to ask for the visitor's permission to be submitted to A/B testing or Personalization before you are actually allowed to execute parts of Kameleoon's code on a visitor's browser. You could have a responsibility to disclose on your website the various technologies you use (especially the ones that perform tracking activities, which is the case with Kameleoon), and the visitor has to agree (even implicitely) to each of them.

    For example, this legal consent is mandatory in European Countries with the famous GDPR regulation. This article explains how Kameleoon deals with legal consent, and describes the different options that enable you to tailor its behavior to your requirements.

    Legal Consent Policies

    For a given visitor, the legal consent to use Kameleoon is considered either granted, denied or unknown (a special state used when consent is not defined, as the visitor has not granted nor denied it yet). You should first choose how Kameleoon treats legal consent:

    To cover all possible use cases, Kameleoon's behavior can be further customized in the case when consent is considered unknown, and in the case when consent is denied. The options chosen will then determine Kameleoon's operational mode, as described below. Selecting the legal consent policy, as well as the behaviors in case of denial and unknown state, is possible via our back-office application.

    Basic implementation example for the Consent required policy

    <script>
        function acceptPolicy() {
            document.getElementById("footer").style.visibility = "hidden";
            Kameleoon.API.Core.enableLegalConsent(); // this will enable both AB Testing and Personalization modules
    
            /* Use the following code if you want to enable A/B Testing or Personalization module separately
            Kameleoon.API.Core.enableLegalConsent("AB_TESTING"); // this will enable only AB Testing module
            Kameleoon.API.Core.enableLegalConsent("PERSONALIZATION"); // this will enable only PERSONALIZATION module
            */
        }
    
        function disablePolicy() {
            document.getElementById("footer").style.visibility = "hidden";
            Kameleoon.API.Core.disableLegalConsent(); // equivalent to Kameleoon.API.Core.disableLegalConsent("BOTH");
    
            /* Use the following code if you want to disable A/B Testing or Personalization module separately
            Kameleoon.API.Core.disableLegalConsent("AB_TESTING"); // this will disable only AB Testing module
            Kameleoon.API.Core.disableLegalConsent("PERSONALIZATION"); // this will disable only PERSONALIZATION module
            */
        }
    </script>
    <div id="footer">
        <p>
            We use various technologies to personalize content and to analyze our traffic.
            Please accept if you comply with our privacy policy, or decline if you wish to avoid tracking.
        </p>
        <button type="button" onclick="acceptPolicy()">Accept</button>
        <button type="button" onclick="disablePolicy()">Decline</button>
    </div>
    

    The customer is responsible for implementing the overall framework for legal consent, as well as the corresponding visual interfaces. Usually, it is done via a banner or simple control granting tracking software the right to be used. Advanced use cases include the possibility for the visitor to whiteflag or blacklist individual technology providers. For instance, you could agree to A/B experiments and general web analytics but refuse any form of tracking for advertising purposes.

    When the interfaces are ready on your side, pass the visitor's choice to Kameleoon via the use of the Kameleoon.API.Core.enableLegalConsent() / Kameleoon.API.Core.disableLegalConsent() methods in our JavaScript Activation API. There is an optional argument to specify the target module. Calling these methods will switch the Kameleoon operational mode (see below). On a typical workflow, consent is given and Kameleoon starts its standard processing, displaying experiments and personalizations, collecting visitor data, etc. This needs to be done only once and not on every page, since Kameleoon automatically remembers this setting for a duration of 380 days.

    An example of a typical setup is provided to the right. The customer provides a dialog that informs its visitors that the website uses tracking features (usually with a list of the platforms / technologies used). If they don't agree with the terms provided, they can avoid tracking by clicking the appropriate button.

    Reading the current legal consent state

    While the Kameleoon.API.Core.enableLegalConsent() and Kameleoon.API.Core.disableLegalConsent() methods allow you to change (write) the legal consent status for this visitor, obtaining (reading) the current state is done via Kameleoon.API.Visitor.

    Technically, this information is also stored in the LocalStorage via the kameleoonLegalConsent key (see details). This key has a lifespan of 380 days, which means the consent is considered valid for a bit more than a year.

    Modes of operation for the Kameleoon engine

    Depending on its mode of operation, Kameleoon's engine works differently - from performing normal operations to doing absolutely nothing. To determine the operational mode, Kameleoon considers the current value of the legal consent. Then if this value is null (unknown state) or false, the corresponding configuration value for the "Behavior when consent is unknown" or "Behavior in case of opt-out" is taken into account. The following logic is applied:

    It is very possible that Kameleoon will have different operational modes for AB experiments and personalizations. In that case, everything works as expected. For instance, experiments are displayed and tracking data, but nothing happens for personalizations.

    Active mode

    This is the normal mode of operation. Kameleoon sends data to tracking servers and writes data to the device as needed. The visitor is supposed to have granted consent to the use of Kameleoon.

    Disabled mode

    In this mode, Kameleoon does nothing at all - data is neither sent out to remote servers nor written to the local device. Experiments and personalizations are never displayed. For all purposes, it's as if Kameleoon did not exist for this particular visitor.

    Delayed mode

    In this mode, Kameleoon does not send any data to tracking servers nor write any data to the device. However, it will still display experiments (or personalizations) normally, if the visitor triggers the associated segment.

    In addition, every data that should be written or sent to a remote server is kept in memory. If later Kameleoon switches to the active mode (usually because the consent is granted at some point), all the data gathered so far (in the context of this page) is written and sent at once. Thus the "delayed" name: if the full consent is obtained at some point, the end result will be that Kameleoon behaved almost like in active mode.

    Restricted mode

    In this mode, Kameleoon does not send any data to tracking servers nor write any data to the device. However, it will still display experiments (or personalizations) that have been flagged with the "Technical" tag in Kameleoon back-office interface. All other experiments / personalizations are not displayed.

    This is a very useful mode that allows most Kameleoon operations to be disabled if a visitor does not want to grant consent, but that still permits critical experiments and personalizations to run for this visitor. Very often, Kameleoon is used as a quick workaround for deploying bugfixes and small improvements to production. In this particular context, data privacy regulations such as GDPR explicitely do not apply, and Kameleoon can be used without consent for such use cases.

    The restricted mode is equivalent to the delayed mode, but more restrictive. Since it can be chosen as a result of a final legal consent choice (a denial), it is expected that data will probably never be written nor sent in this case (whereas the delayed mode is normally only a "transitional" mode).

    Advanced considerations and remarks

    Choosing to implement an explicit consent policy in the context of AB testing usually leads to complex issues, and there is no ideal solution. We describe here the two main problems.

    The first thing to take into account is that if you choose a strict behavior (disabled mode) while consent is unknown, experiments / personalizations will be triggered "late" in the context of the first page view of a totally new visitor. With this setup, they can indeed be displayed only after the legal consent has been obtained, which is typically after a few seconds. This can unfortunately lead to some serious UX issues, depending on the underlying experiments and personalizations, and should be taken into account.

    This problem can be mitigated with the delayed mode, as display is immediate and only writing is delayed. However, there is a second issue arising when a visitor "stays" with an unknown legal consent status over several pages. Since Kameleoon does not write any data to the device, not even the Kameleoon visitorCode identifier, it keeps being randomly (re)generated on each page while final consent is not determined. This implies that for experiments, variation allocation will happen at each new page view, and no consistency is guaranteed in those allocations. It is thus important to take steps to prevent this situation from happening. Several options are possible (blocking consent banner, denying consent automatically after X seconds...), but a visitor should never stay in the unknown legal consent status forever. Either consent is granted, or it is denied.