> ## Documentation Index
> Fetch the complete documentation index at: https://help.maestra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Consent and Tracking

A visitor who clicks an email usually lands on your site before they answer the cookie banner. They might browse two or three pages before clicking Accept, or never answer at all.

What happens before they answer depends on the consent mode you choose:

* **Buffer** — the tracker saves the landing page in the visitor's browser without sending anything to Maestra Platform. If the visitor accepts, it's sent and recorded. If they decline, it's deleted.
* **Gate** — nothing is collected until the visitor accepts.

Here's a closer look at each mode.

## Consent modes

| | Buffer (default) | Gate |
| - | - | - |
| **Before the visitor answers** | The tracker script loads but sends no tracking requests and sets no cookies. It keeps the landing page URL (with UTM parameters and click IDs), referrer, and arrival time in the browser's session storage. | Nothing is kept. On Shopify, the tracker script isn't even requested until the visitor accepts. |
| **After Accept** | The saved landing page is sent once, followed by the current page. The visit is recorded at the time the visitor arrived, not when they clicked Accept. Identifier cookies are created at this point. No page reload needed. | Tracking starts from the current page. If the visitor accepted on a later page, the landing page and its UTM parameters are lost. |
| **After Decline** | The saved landing page is deleted. Nothing is sent. | Nothing is sent. |

> [!TIP]
>
> Use **buffer** to keep email and campaign attribution.\\
>
> Choose **gate** only if your legal team requires zero requests to Maestra Platform before consent.

### When a visitor withdraws consent

If a visitor accepts and later switches to Decline, Maestra Platform:

* Deletes its identifier cookies (`maestraDeviceUUID`, `directCrm-session`) and the data it keeps in local storage and IndexedDB.
* Stops sending tracking requests from that page on.

If they accept again, tracking starts over with a new anonymous identifier.

> [!NOTE]
>
> **The visitor's choice is remembered.**\\
>
> Once the visitor accepts or declines, the choice is saved in the `maestraConsent` cookie for one year. On later pages, the tracker applies it right away instead of waiting for the banner. The cookie holds only the choice and its date — no identifiers.

## Set up consent with the Maestra Shopify app

The Maestra app embed reads the visitor's choice from Shopify's Customer Privacy API. It works with the native Shopify cookie banner and with any consent app that reports to Shopify.

**1. Open App embeds**

In Shopify admin, go to **Online Store → Themes → Customize → App embeds**.

**2. Open the Maestra embed**

Find the **Maestra** embed and open it.

**3. Set Consent mode**

* **Buffer until consent** — buffer mode (default).
* **Don't load before consent** — gate mode.

**4. Click Save**

How the Shopify integration handles consent:

* Maestra Platform tracks a visitor only when they allow **both** analytics and marketing. A visitor who allows analytics but not marketing isn't tracked.
* In regions where your store doesn't show a cookie banner, tracking starts on page load, as before.
* The Shopify Web Pixel (cart and product events) follows the same choice. No separate setup needed.

> [!WARNING]
>
> **Remove hand-pasted tracker code from your theme.** If your theme has its own `maestra('create', …)` snippet that runs before the app embed, that snippet wins and consent settings are ignored — the visitor is tracked before they answer the banner. Remove the snippet and keep only the app embed.

> [!WARNING]
>
> **Consent apps that don't report to Shopify.** Some consent tools (for example, PieEye) don't pass the visitor's choice to Shopify's Customer Privacy API, so the Maestra app can't see it. Pass the choice to the tracker yourself with `consent.set`, as described below.

## Set up consent with JavaScript

If you install the tracker with a code snippet or through a tag manager, add a `consent` block to the `create` call, then pass the visitor's choice from your consent tool to the tracker.

### 1. Add consent settings to `create`

```js theme={null}
maestra('create', {
  endpointId: 'YourEndpoint.Website',
  consent: {
    mode: 'buffer',     // or 'gate'
    default: 'pending'  // wait for the visitor's choice
  }
});
```

| Setting | Values | What it does |
| - | - | - |
| `mode` | `'buffer'` (default), `'gate'` | See [Consent modes](#consent-modes). |
| `default` | `'pending'`, `'granted'`, `'denied'` | The state before the visitor makes a choice. Use `'pending'` when your banner asks for opt-in. Required whenever `consent` is present. |

Without the `consent` block, the tracker works as before and tracks every visitor from the first page.

> [!WARNING]
>
> If the `consent` block is invalid — for example, `default` is missing or misspelled — the tracker tracks no one until the visitor makes an explicit choice. Check the browser console for errors after setup.

> [!NOTE]
>
> In gate mode on your own site, the tracker script still loads — it just keeps and sends nothing. If you need zero requests to Maestra Platform before consent, load the tracker snippet only after the visitor accepts.

### 2. Pass the visitor's choice

Call `consent.set` from your consent tool's callback when the visitor answers the banner or changes their choice later:

```js theme={null}
maestra('consent.set', 'granted'); // visitor accepted
maestra('consent.set', 'denied');  // visitor declined or withdrew consent
```

You can call it on every page with the current choice. Repeating the same value does nothing.

### 3. Read the current state (optional)

```js theme={null}
// Current state: 'pending', 'granted', or 'denied'
maestra('consent.get', function (state) {
  console.log(state);
});

// Called every time the state changes
maestra('consent.subscribe', function (state) {
  console.log(state);
});
```

> [!NOTE]
>
> Calls made while consent is pending — product views or cart updates, for example — are held in the browser. They're sent if the visitor accepts on the same page and discarded if they decline.

## What the tracker stores in the browser for consent

Consent adds two records to what Maestra Platform keeps in the visitor's browser. List them in your cookie policy under whichever category your legal team chooses.

| Record | Where | Lifetime | Contents |
| - | - | - | - |
| `maestraConsent` | Cookie, your website (first-party) | 1 year | The visitor's choice (accepted or declined) and its date — no identifiers. Set once the visitor answers; on later pages the tracker applies it right away instead of waiting for the banner. |
| `maestraLanding` | sessionStorage | Until consent is given or declined, or the tab is closed | The saved landing page in buffer mode (see [Consent modes](#consent-modes)). |

For identifier cookies and everything else Maestra Platform stores, see [Cookies and Browser Storage](https://help.maestra.io/api-integrations/cookies-and-browser-storage.md).

## How to check it on your site

Open your website in a private window, so no earlier choice is stored, and open your browser's developer tools.

**1. Check Network before answering the banner**

Go to **Network** and filter by `maestra`. In buffer mode, you should see only the tracker script (`tracker.js`). In gate mode on Shopify, you should see nothing.

**2. Check cookies and session storage**

Go to **Application → Cookies**. There shouldn't be a `maestraDeviceUUID` cookie yet. In buffer mode, **Session Storage** holds `maestraLanding` with your landing page.

**3. Click Accept**

In **Network**, you should see visit requests. `maestraDeviceUUID` and `maestraConsent` appear in **Cookies**, and `maestraLanding` disappears.

> [!NOTE]
>
> Questions? Reach out to your Maestra Platform Forward Deployed Marketer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.