consent

Show a cookie consent banner and load analytics integrations only after the visitor agrees. Or load them at once and give the visitor a footer link to opt out. Set mode to turn the feature on. The default is none, so the block alone changes nothing.

Every string in the banner and the dialog is a translation key. The predefined translation keys page lists them all. Change the wording of any string in your translations.yaml file.

Consent has three fixed categories. You cannot add a category. Change the title and the description of each one with translation keys.

Realm ships no marketing integration, so the marketing category gates only the scripts you add.

consent:
  mode: auto
  privacyPolicyUrl: https://example.com/privacy

With mode: auto, a visitor in an opt-in country sees the banner on the first visit. A visitor who accepts analytics gets the Google Analytics script at once, on the same page, with no reload. Google Tag Manager, Segment, and Heap record the page the visitor accepted on. Google Analytics and Rudderstack record from the next page view. A visitor who rejects it never loads the script. A Cookie preferences link in the footer reopens the dialog.

Use opt-out mode for a site whose visitors live where the law requires a way to refuse, not a question up front. The US state privacy laws work this way.

consent:
  mode: opt-out
  privacyPolicyUrl: https://example.com/privacy

The visitor sees no banner. Analytics and marketing load on the first page view. A Cookie preferences link in the footer opens the settings dialog, with every category on. When a visitor turns a category off, Realm reloads the page, so scripts that already run stop.

If your visitors live in both opt-in and opt-out places, use mode: auto.

Some browsers send the Global Privacy Control signal, which asks the site not to sell or share the visitor's data. Realm treats the signal as a refusal of the marketing category, in both modes. Marketing scripts do not load, the settings dialog shows the marketing toggle off, and the dialog says the browser asked for it. The visitor cannot change the marketing toggle while the browser sends the signal.

Use a provider mode when your company already has a consent manager. The provider shows the banner, keeps the decision, and selects the visitors who see the banner. Realm reads the state from the provider. Then Realm gates its analytics integrations and your scripts on that state.

Add the provider script to the scripts config. Do not add the consent property to it, because the provider must load on each page view. Realm adds no provider script and needs no provider settings.

consent:
  mode: onetrust
scripts:
  head:
    - src: https://cdn.cookielaw.org/scripttemplates/otSDKStub.js
      data-domain-script: 0190abcd-1234-7000-8000-000000000000

Each provider has its own category names. Realm maps them to the analytics category and the marketing category.

Use tcf with a consent manager that supplies the IAB TCF version 2.2 API, such as Didomi, Usercentrics, or Sourcepoint.

A provider mode changes what Realm does:

• Realm shows no banner and no settings dialog.
• The Cookie preferences link opens the preference center of the provider. Before the provider script loads, the link writes a warning to the browser console and does nothing. With tcf, the link opens the Didomi or Usercentrics preference center. The TCF API has no command that shows a preference center, so with another TCF consent manager, add your own trigger.
• Realm keeps no consent cookie, because the provider keeps the decision.
• Realm pushes no Google consent mode command, because the provider pushes its own.

Analytics and marketing stay off until the provider reports a grant. If the provider script does not load in 15 seconds, Realm writes one warning to the browser console. Analytics and marketing stay off.

With mode: auto, visitors in places that require consent up front get the banner. Visitors in places that require a way to refuse get the footer link.

consent:
  mode: auto
  privacyPolicyUrl: https://example.com/privacy

Realm finds the visitor's country from the browser's time zone. The browser reports a zone name such as America/Chicago, and Realm maps the zone to its country with the tz database's country table. This finds the country, not the state or province. The table lists one country for each zone, and that country decides. A visitor in a place that shares a zone with a neighboring country gets the mode of that country.

The country then picks the mode:

auto never picks none. Realm changes the list only in a release, with a changelog entry. If you disagree with the choice for a place, set mode: opt-in or mode: opt-out for every visitor.

Add the consent property to a script in the scripts config. The script loads only while the consent state allows that category. In opt-in mode the visitor must accept first. In opt-out mode the category starts on and stays on until the visitor refuses. Possible values: analytics, marketing. A script without the property loads on every page view.

scripts:
  head:
    - src: https://connect.facebook.net/en_US/fbevents.js
      consent: marketing

A returning visitor who granted the category gets the script on the first page view. Gated scripts load in the order of the config. A pixel inside a Google Tag Manager container follows Google consent mode and needs no consent property. That pixel loads only when the visitor grants the analytics category, because the container itself waits for analytics.

Set settingsLink: none, or hide the footer. Then open the dialog from any element of your own.

document.querySelector('#cookie-settings').addEventListener('click', () => {
  window.redocly.consent.open();
});

Use this when you want the link on a specific page. window.redocly.consent.close() closes the dialog.

A script that is more than one tag can read the state and wait for a category.

window.redocly.consent.on('change', (state) => {
  if (state.analytics) {
    loadMyAnalytics();
  }
});

• Analytics configuration - The integrations that wait for the analytics category
• Scripts configuration - How to add your own scripts and the consent property that gates them
• Localization - How to translate the banner text