Anti-flicker and performance
How variants are applied before first paint, what the mask does, its hard timeout, and what the snippet costs a page.
What flicker is#
A client-side experiment changes a page the browser has already been told how to draw. If the change lands after the first paint, the visitor sees the original headline for a moment and then the variant. That flash is distracting, and it biases the experiment: the visitor has seen both versions.
Avenue Lift avoids it in two ways. First, the tag is synchronous and the configuration is inlined in the script, so the snippet knows what to do before the browser has painted anything. Second, for the short time it takes the elements of a variant to appear in the document, it hides the page behind a mask with a hard time limit.
How the mask works#
The mask is a single style rule that sets the opacity of the document to zero. The layout is computed as usual underneath, so nothing shifts when it is removed.
- When it goes up
- Only when it can help: an experiment with changes targets the current URL (or a preview is forced) and the document is still loading. Pages without a matching experiment are never masked. Neither is a page where the script ran late — hiding content that is already visible would cause a blink rather than prevent one.
- When it comes down
- As soon as every change of the visitor's variant has been applied. Visitors assigned to the original page are revealed immediately.
- The hard timeout
- 400 ms by default. When it fires the page is shown whatever state the variant is in, and remaining changes are applied as their elements appear. The timer is started before the page is hidden, so no failure can leave a page invisible.
The timeout is a setting of the site, in milliseconds. Set it to 0 to switch masking off entirely. Whatever the setting says, the snippet never masks for longer than 3 seconds.
Choosing a timeout
Content that renders late#
A change whose selector matches nothing yet is not an error. The snippet keeps watching the document and applies the change when the element shows up — after hydration, after a client-side navigation, after a lazy component mounts. If your framework re-renders an element and overwrites a change, the change is applied again.
Two limits keep this from fighting the host page: a change is re-applied at most 20 times per second, and the anti-flicker mask stops waiting for missing elements when its timeout fires. The QA debug panel shows, per variant, how many changes are applied, how many are still waiting for their element, and any that failed.
When something goes wrong#
The snippet is written so that it cannot break the page it runs on. Every step runs inside an error guard, and each failure has the same outcome: the visitor sees the original page.
- The script cannot be loaded. Nothing runs, nothing is hidden. Because the tag is synchronous, the browser waits for the response like for any other script in the head; the response is small and cacheable to keep that wait short.
- The site key is unknown, or our service is failing. The URL still answers with a valid script that does nothing.
- A change is invalid for the page. It is skipped and reported in the debug panel; the other changes of the variant still apply.
- Your code calls the API before the script has loaded. With the pre-load queue the calls are kept and replayed. Every method of the global is safe to call at any time and never throws.
What the snippet costs#
- Download
- One script: a runtime under 22 KB gzipped, with the site's configuration in the same response. No dependencies and no further requests before the page is shown. The visual editor and the debug panel are a separate file that is only fetched when you open them.
- Caching
- Fresh for 30 seconds, then served from cache for up to 2 minutes while it is revalidated in the background.
- Events
- Batched: sent 1 second after the first event of a batch, or at once when 20 have queued, and when the page is hidden or closed. Requests are fire-and-forget background requests that need no preflight and never block navigation.
- Main thread
- On a page without a matching experiment the snippet reads its configuration, records a page view and listens for the site's goals. The document is only observed for changes while a variant is applied.
To remove the client-side cost for a page entirely, assign on the server with the SDK: the variant is rendered into the response and the browser has nothing to apply.