Documentation
Usage With Google Tag Manager (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)
Load our script directly in the <head>
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
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
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
Unpredictable behavior
Use:
Page View → DOM Ready
orPage 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
GTM cannot guarantee the same visual stability as loading the script in the <head>.
Usage With Google Tag Manager (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)
Load our script directly in the <head>
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
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
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
Unpredictable behavior
Use:
Page View → DOM Ready
orPage 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
GTM cannot guarantee the same visual stability as loading the script in the <head>.