Skip to content

Add a cookie consent banner

Install the banner, declare trackers, and verify a visitor’s first decision.

Declare the trackers your site uses, configure the banner, and install its script before any tracker loads. Then verify that a visitor can allow a category and that Consent records the decision.

The setup needs no DNS changes. Configuration happens in your Lepsto product; installation and browser checks happen on your site.

Before you start

  • A Lepsto product with Consent available and at least Member access. MCP changes need product write scope; reading the snippet and results needs read. Cookie domain changes and record exports require Admin.
  • A list of third-party providers, their script and iframe hostnames, and the storage they use.
  • Access to edit your pages’ <head>.

Replace <YOUR_PRODUCT_ID> with your product id. The example uses example.com as your site and analytics.example.net as its analytics provider; replace both and verify the example cookie details against your tracker.

1. Declare the providers you use

Only declared provider hosts can be blocked. Adding the banner to a product with no provider declarations does not block your trackers.

For each provider, supply a unique name, category, hostnames and cookie details:

  • Use preferences, statistics or marketing for resources that require a choice.
  • Supply up to 50 lowercase hostnames with at least one dot. Do not include a scheme, port, path or wildcard.
  • Give each cookie a name, purpose, storage duration and type: http_cookie, local_storage or session_storage. Purpose and duration cannot be blank or cleared later.

A necessary provider must have no hosts. It is disclosed but not blocked.

UI. Open Consent for your product in app.lepsto.com and add the providers. Choosing a known tracker from the catalog fills suggested hosts and cookies for you to check.

MCP. Ask your agent, using product write scope:

“On example.com we load analytics from analytics.example.net. Declare it as a statistics provider with an _ga cookie: first-party analytics id, 2 years, type http_cookie.”

The agent uses consent_providers_create. See Declare your providers and cookies for the full field rules.

2. Set the theme

Choose the brand color, light or dark surface, corners and font. Add a logo and set the banner’s placement if needed.

UI. Use Consent’s appearance settings.

MCP. Use consent_config_theme_upsert and consent_config_customization_upsert with product write scope. Both merge the supplied fields into the stored settings.

The banner uses a shadow root and overrides inherited page styling. Use these settings to style it; your page’s CSS is not a supported styling path. See Configure the banner.

3. Copy the snippet

UI. Copy the snippet from Install on your site.

MCP. Call consent_embed_get with product read scope. It returns the snippet with your product id and public edge URL.

<!-- Lepsto consent: must be the first script in <head>. Do not add async or defer — trackers would run before consent is known. -->
<script src="https://public.lepsto.com/<YOUR_PRODUCT_ID>/consent/banner.js" data-product-id="<YOUR_PRODUCT_ID>"></script>

Keep the comment with the tag: it records the load-order requirements for anyone editing the page later.

4. Paste it into your page

Make the banner the first script in <head>, before trackers and inline tracker loaders. Do not add async or defer. banner.js installs the blocker; it cannot intercept a tracker that already ran.

If you also use Lepsto Tracking, leave its snippet loaded unconditionally and add data-consent="banner" to that tracking tag. The equivalent snippet request is tracking_snippets_get with consentBanner: true. Use this option only on pages that load the Lepsto banner. See Tracking consent.

5. Load your site and check it worked

Open a fresh browser profile with no stored choice and open the Network panel.

  1. Confirm that the banner appears with your theme. The bundle includes the theme; a recent configuration change may take up to five minutes to appear in its first frame.
  2. Before accepting, confirm that no requests reach analytics.example.net or other declared hosts in optional categories.
  3. Click Allow all and confirm those resources load in their original order.
  4. In the app’s recent decisions list, or through consent_dashboard_decisions_list, find the decision. Check that the statistics include it.

If a declared tracker runs before consent, check the cases below.

What you have now

Your site has a configured banner, blocking for declared tracker resources, a floating icon to reopen preferences, and signed decision records retained for 1095 days. Record retention and cookie lifetime are separate; see Consent records.

If a tracker still fires

It ran before the banner. Move the banner tag above all trackers and their loaders. Remove async and defer from the banner tag.

Its host is undeclared. Add the host to the correct provider. Undeclared hosts pass through.

It is bundled into your app. Host blocking covers third-party script and iframe elements. It does not stop code you start with import() and fetch. Gate that code on analytics_storage: granted or window.LepstoConsent.getDecision(), and listen for changes. See The banner runtime.

It is Lepsto Tracking. This first-party integration is disclosed without host blocking so it can read consent and switch collection modes. Declare the banner on its snippet as described in step 4. See Tracking consent.

For interception details, see Script blocking.

Next steps

Was this page helpful?
Esc

Start typing to search the docs.

↑↓navigate↵select