# Consent manager

URL: https://docs.ablyft.com/developers/consent-and-security/consent-manager/

> Show variations and start tracking only when your consent manager allows it.



If your website uses a consent manager (also called cookie banner or CMP), ABlyft must know what the visitor has
agreed to. ABlyft supports this with two rules in your project and two API calls that you trigger from your consent
manager.

## Choose a setup

Technically, ABlyft can work with a consent management platform (CMP) in three ways. Which one fits depends on your
architecture, your testing setup and your data protection requirements. Assess the legal side independently of what is
technically possible.

|                                          | 1. Independent of consent | 2. Load after consent              | 3. Consent-dependent storage and tracking |
| ---------------------------------------- | ------------------------- | ---------------------------------- | ----------------------------------------- |
| Snippet is loaded                        | Immediately               | Only after the visitor consented   | Immediately                               |
| Experiments are delivered before consent | Yes                   | No                             | Yes                                   |
| Variation ID is stored before consent    | Yes                   | No                             | No                                    |
| Events are sent to ABlyft before consent | Yes                   | No                             | No                                    |
| Consent status must be passed to ABlyft  | No                    | No (the CMP loads the snippet) | Yes                                   |

**1. Independent of consent.** The snippet runs without restrictions and is not linked to the CMP. Leave both rules
below at their default `return true;`.

**2. Load after consent.** The snippet is blocked by your CMP and loaded once the visitor agreed. Until then ABlyft does
not run at all. This is simple, but visitors may see flicker, because variations can only be applied after the decision.

**3. Consent-dependent storage and tracking.** The snippet sits directly in the page and runs before consent, so
variations appear without flicker. Storage and tracking wait for the visitor's decision. This is the setup described in
the rest of this page.

## How it works

ABlyft separates two things:

| Stage               | Question                                              | Controlled by                                 |
| ------------------- | ----------------------------------------------------- | --------------------------------------------- |
| **Show variations** | May ABlyft run experiments and change the page?       | Rule **Show Variations (General Startup)**    |
| **Track and store** | May ABlyft store data in the browser and send events? | Rule **Start Tracking (and Browser Storage)** |

You can always show variations, and only track once the visitor consented. This avoids flicker, because the snippet
can stay in the `<head>` of your page.

While the tracking rule does not return `true`:

* Data that ABlyft would write to the browser (for example the variation assignment) is kept in memory only.
* Events that would be sent (bucketing, goals) are held back in the browser's `sessionStorage` key `ablyft_temp_events`.
* The consent state itself (`ablyft_tracking_consent`) and a redirect marker are still stored, because they are needed to
  remember the decision.

As soon as consent is given, the held data is moved to the configured storage and the events are sent.

## Step 1: Set the rules in ABlyft

1. Open your project and go to **Settings → Prerequisites** ("Project Prerequisites").
2. Edit the two code fields. Each is the body of a JavaScript function. Return `true` to allow the stage.

| Field                                    | If your code returns `true`                              | Default        |
| ---------------------------------------- | -------------------------------------------------------- | -------------- |
| **Show Variations (General Startup)**    | The project is processed further and can show variations | `return true;` |
| **Start Tracking (and Browser Storage)** | Tracking and browser storage are enabled                 | `return true;` |

An empty rule counts as `true`. If your code throws an error, the error is logged and the rule counts as **not met**.

Example: always show variations, and track only after consent. These are the examples shown on the Prerequisites page.

**Show Variations (General Startup)**

```js
if (ablyft.get('trackingConsentEnabled') !== false) {
  return true;
}
```

**Start Tracking (and Browser Storage)**

```js
return ablyft.get('trackingConsentEnabled');
```

[`ablyft.get('trackingConsentEnabled')`](https://docs.ablyft.com/developers/reference/javascript-api/get/#trackingconsentenabled) returns `true` after
`enableTrackingConsent`, `false` after `disableTrackingConsent`, and an empty value as long as the visitor has not decided yet.
That is why the first rule uses `!== false`: variations are shown until the visitor explicitly declines.

If you return `false` from **Show Variations**, ABlyft does not run experiments on that page view.

## Step 2: Tell ABlyft about the decision

Call these from the consent callback of your consent manager. The calls also work before the snippet has loaded.

```js
window.ablyft = window.ablyft || [];

// Visitor accepted
window.ablyft.push({ eventType: 'enableTrackingConsent' });

// Visitor declined
window.ablyft.push({ eventType: 'disableTrackingConsent' });
```

See [`enableTrackingConsent`](https://docs.ablyft.com/developers/reference/javascript-api/push/#enabletrackingconsent) and
[`disableTrackingConsent`](https://docs.ablyft.com/developers/reference/javascript-api/push/#disabletrackingconsent) for what each call does.

## Example with a generic consent manager

Most consent managers can run JavaScript when the visitor accepts or declines, or provide a status you can read. The
exact API differs for each product, so the names `onConsentChange` and `hasStatisticsConsent` below are placeholders for the
functions of your consent manager.

```html
<script>
  window.ablyft = window.ablyft || [];

  function syncAblyftConsent(hasConsent) {
    window.ablyft.push({
      eventType: hasConsent ? 'enableTrackingConsent' : 'disableTrackingConsent',
    });
  }

  // 1. Remember the decision of returning visitors
  if (typeof hasStatisticsConsent === 'function' && hasStatisticsConsent()) {
    syncAblyftConsent(true);
  }

  // 2. React when the visitor decides
  if (typeof onConsentChange === 'function') {
    onConsentChange(function (consent) {
      syncAblyftConsent(consent.statistics === true);
    });
  }
</script>
```

> **Register ABlyft's entries in your consent manager:** Consent managers often delete cookies and storage entries they do not know. Add every entry that starts with `ablyft_`
> to the right category in your consent manager. The list is in [Storage & privacy](https://docs.ablyft.com/developers/consent-and-security/storage-and-privacy/).

## Check that it works

1. Open your site in a private window without giving consent.
2. In the console, run `ablyft.get('trackingConsentEnabled')`. It returns an empty value.
3. Accept in your consent manager and run it again. It returns `true`.
4. Turn on [debug mode](https://docs.ablyft.com/developers/debugging/preview-and-live-log/#debug-mode). The console then shows whether the
   general and tracking prerequisite rules are met.

## Next steps

- [Storage & privacy](https://docs.ablyft.com/developers/consent-and-security/storage-and-privacy/): Which entries ABlyft writes, and where.
- [ablyft.push()](https://docs.ablyft.com/developers/reference/javascript-api/push/): All event types.