Integrate OptinStack with Google Tag Manager

Use this guide when your site manages tags through Google Tag Manager and you want OptinStack to control when measurement, advertising, personalization, and other trackers can run. The setup has two jobs: OptinStack collects and stores the visitor's choices, and GTM uses those choices to set Google Consent Mode v2 and control tags in your container.

For the technical signal mapping and runtime behavior, see the Google Consent Mode v2 docs reference.

How the integration works

The OptinStack runtime runs on your site and maintains four consent categories: necessary, analytics, marketing, and preferences. It stores the visitor's consent record in a first-party technical record named optinstack, exposes the current state through window.OptinStack, blocks or releases direct scripts and iframes by category, and emits dataLayer events that you can use as GTM triggers.

The OptinStack GTM template is the GTM-side bridge. It sets default consent during GTM's Consent Initialization phase, reads any existing OptinStack consent record, subscribes to live OptinStack consent changes, and updates GTM with the matching Consent Mode v2 values. It can also inject the OptinStack runtime through GTM, but direct installation in the page head is recommended for most sites.

Prerequisites

• A Google Tag Manager web container installed on your site.
• An OptinStack project with your domain configured and a Site ID from the dashboard install screen.
• Access to the official downloadable OptinStack GTM template. It is not currently published in the Community Template Gallery.
• A decision on your default consent state by region. Many consent-required regions use denied defaults for optional categories until the visitor makes a choice.

Choose an installation path

Step 1: Install the OptinStack runtime

For the strongest enforcement, paste the runtime snippet from your OptinStack dashboard as early as possible in the site head, before the GTM container snippet and before any direct third-party scripts.

<script src="https://api.optinstack.com/v1/js/runtime/stable/optinstack.js" data-optinstack-sdk="consent" data-optinstack-site="YOUR_SITE_ID"></script>

The data-optinstack-site value tells the runtime which project configuration to load. The runtime fetches your site configuration, resolves the visitor's applicable policy and region, honors Global Privacy Control when configured, blocks direct scripts, iframes, storage writes, and known tracker records by category, then loads the banner and preferences UI.

Step 2: Add the OptinStack GTM template

1. Open your GTM container and go to Templates.
2. In Tag Templates, choose New, open the template editor menu, and import the official downloadable OptinStack template. It is not currently published in the Community Template Gallery.
3. Review the permissions. The template writes GTM consent state, reads the optinstack consent record, sets ads_data_redaction and url_passthrough, reads the OptinStack global API, and optionally injects the OptinStack runtime from api.optinstack.com.
4. Save the template to your workspace.

Step 3: Create the OptinStack consent tag

1. Go to Tags and create a new tag.
2. Choose the OptinStack template as the tag type and name it OptinStack Consent Mode.
3. Set the trigger to Consent Initialization - All Pages. This trigger is required because consent defaults must be available before normal pageview, initialization, and custom event triggers run.
4. Save the tag, then use Preview mode before publishing.

Step 4: Configure every template field

Configure default consent by region

Add at least one blank Region row as your global default. Then add regional rows only where the default needs to differ. Google applies the most specific matching region default, and the blank row applies to visitors not covered by a regional row.

If you do not configure a blank global row, the OptinStack template falls back to denied for analytics, marketing, preferences, and granted for security_storage. This is safe, but explicit defaults are easier to audit and troubleshoot.

Keep the template defaults aligned with the policy you configured in OptinStack. The defaults are used before a visitor has made a choice on the current page. After a stored or new OptinStack choice is available, the template updates GTM with that visitor-specific state.

Consent Mode v2 signal mapping

How the template keeps GTM in sync

1. On Consent Initialization, the template calls GTM's setDefaultConsentState API for each configured region row.
2. If an existing OptinStack consent record is present, the template reads it immediately and calls updateConsentState with the stored choices.
3. When the runtime is available, the template subscribes to window.OptinStack.subscribe, window.OptinStack.on('choices'), or window.OptinStack.events.on('consent-updated'), depending on which surface is available. It falls back to polling the current choices if needed.
4. Each time choices change, the template maps OptinStack categories to Google Consent Mode signals and calls updateConsentState again.
5. The template also sets ads_data_redaction and url_passthrough through GTM's gtagSet API when those options are enabled.

OptinStack dataLayer events

The runtime pushes GTM-friendly events to window.dataLayer. Each event is pushed as an object with only an event property, for example { event: 'optinstack_analytics_accepted' } . Use these events as GTM Custom Event triggers.

Configure tags, triggers, variables, and consent settings

Enable Consent Overview

In GTM, go to Admin, Container Settings, and enable Consent Overview. This gives you one place to review which tags have consent settings configured and which tags still need attention.

Google tags with built-in consent checks

Google tag, GA4, Google Ads, Floodlight, and Conversion Linker tags understand Consent Mode signals. If you want advanced Consent Mode, these tags can load with denied defaults and adapt behavior until consent is granted. If your policy requires basic Consent Mode, add Additional Consent Checks so the tag does not fire until the required consent types are granted.

Third-party tags without built-in checks

For tags that do not understand Google Consent Mode, open Tag Configuration, Advanced Settings, Consent Settings, and choose Require additional consent for tag to fire. Add the consent types that match the tag's purpose. Then use an OptinStack Custom Event trigger so the tag can fire on the first page after consent is granted.

Most GTM setups do not need custom variables because Consent Mode and Additional Consent Checks handle the gating. If you need a variable for advanced logic, read the public runtime state from window.OptinStack.choices.

function() {
  return !!(window.OptinStack && window.OptinStack.choices && window.OptinStack.choices.analytics);
}

Google Consent Mode v2 and advertising products

Consent Mode v2 adds ad_user_data and ad_personalization alongside ad_storage and analytics_storage. OptinStack maps all three advertising signals to the marketing category. When marketing is denied, Google advertising tags should treat advertising storage, advertising user data, and personalized advertising as denied.

This matters for Google Ads conversion tracking, enhanced conversions, remarketing, Floodlight, and other advertiser-related products. Consent Mode changes how supported Google tags behave; it does not replace your responsibility to obtain valid consent or configure tag firing according to your policy.

Use Dynamic ads data redaction when you want ad click identifiers redacted whenever marketing consent is denied. Use URL passthrough only after testing same-domain navigation, redirects, and analytics reporting, because Google may append parameters such as gclid, dclid, gclsrc, _gl, and wbraid to links.

Global Privacy Control

When Global Privacy Control is active and your OptinStack policy honors it, the runtime defaults optional categories according to your GPC behavior. It also pushes optinstack_gpc_signal_detected to dataLayer. Because the GTM template default runs before the runtime can evaluate the browser signal, configure conservative default rows for regions where GPC or consent requirements apply.

Let visitors reopen preferences

Add a footer or privacy-page link that reopens the OptinStack preferences dialog. This lets visitors change or withdraw consent later, and the GTM template will update consent state when their choices change.

<button type="button" onclick="window.dispatchEvent(new CustomEvent('optinstack:open-preferences', { bubbles: true }))">
  Consent preferences
</button>

Control trackers outside GTM

GTM consent settings only control tags inside the GTM container. Scripts, iframes, maps, widgets, or platform integrations inserted directly into the page still need OptinStack runtime enforcement. Use dashboard tracker rules from your scan results, or mark direct elements with data-optinstack-categories when you know the category.

<script data-optinstack-categories="analytics" src="https://example.com/analytics.js"></script>

Test the implementation

1. Open GTM Preview mode and load your site in a fresh browser profile.
2. Confirm that the OptinStack consent tag fires on Consent Initialization before other tags.
3. Open Google Tag Assistant and check the earliest Consent event. Verify that ad_storage, ad_user_data, ad_personalization, analytics_storage, functionality_storage, personalization_storage, and security_storage have the expected default values.
4. Interact with the OptinStack banner. In Tag Assistant, verify that a later Consent event updates the same signals to match the visitor's choices.
5. In GTM Preview, inspect tags that should be blocked before consent and confirm their consent checks and triggers behave as expected.
6. Run an OptinStack scan after publishing to confirm direct trackers and GTM-loaded trackers are categorized correctly.

Troubleshooting

Official references

• Google Tag Manager consent mode support
• Google's guide to creating consent mode templates with GTM consent APIs
• Set up Consent Mode on websites
• Troubleshoot Consent Mode with Tag Assistant
• Google Consent Mode overview
• Google Ads: About Consent Mode