Advanced

Usage with Google Tag Manager (GTM)

Why we recommend loading the script directly in the <head>, and how to minimize flicker if you must use GTM.

Our script performs direct DOM manipulations to dynamically update on-page content. To avoid visible flashes or flickers during these updates, we provide an optional anti-flicker mechanism that temporarily hides content until the script has completed its changes.

Because this process must occur before the browser renders the page, GTM's asynchronous loading model introduces timing issues that can cause visual instability. This guide explains the recommended setup and the fallback approach if GTM must be used.

1. Recommended setup (strongly recommended)

For stable, flicker-free behavior, place both our main script and our anti-flicker snippet directly in the <head> of the page. This ensures:

DOM updates occur before first paint
No flash or flicker
No duplicate executions
No dependency on GTM timing
No interference from navigation events

Tip

This is the only setup that guarantees consistent behavior across all pages and campaigns.

2. Understanding our anti-flicker mechanism

Our anti-flicker script:

Injects a temporary overlay or style block to hide content
Prevents the user from seeing the “original” content before our script updates it
Removes itself once the DOM manipulation is complete

When loaded through GTM:

The anti-flicker overlay appears too late, because GTM loads after initial rendering
The overlay may appear on non-campaign pages
Multiple overlays may be injected if GTM History triggers fire
Flicker may still occur because the original content is already visible

Note

This is why we recommend loading the anti-flicker snippet outside GTM.

3. Why GTM causes issues

Asynchronous loading

GTM loads after the initial HTML is parsed, meaning:

The page may already be visible
Our script manipulates the DOM too late
Flicker or flash becomes unavoidable

History triggers

If GTM uses History triggers:

The entire tag stack may fire multiple times
Our anti-flicker snippet may be injected repeatedly
Our script may run more than once per page view
Non-campaign pages may receive overlays unintentionally

4. If GTM must be used (fallback integration)

If you cannot place the script in the <head> and must use GTM, follow these guidelines to minimize issues.

A. Do NOT load the anti-flicker snippet via GTM

The anti-flicker must run before first paint, which GTM cannot guarantee. If you must use GTM:

Place the anti-flicker snippet in the <head>
Load only the main script through GTM

This reduces (but does not eliminate) flicker.

B. Use a Page View trigger (not History)

History triggers cause multiple executions, multiple overlays, and unpredictable behavior. Instead use:

Page View → DOM Ready, or
Page View → Window Loaded

depending on your needs.

C. Expect some limitations

Even with the best GTM setup:

A flash may still occur
Flicker may appear on slow connections
Timing may vary across browsers
Multiple campaigns may increase instability

Important

GTM cannot guarantee the same visual stability as loading the script in the <head>.