Installing the snippet
Where the script tag goes on plain HTML, Webflow, Shopify, WordPress, Squarespace, Wix, Framer, Google Tag Manager, strict-CSP sites and Next.js or React sites.
The tag#
Every site has one tag. It is shown, with your site key filled in, on the site's Install page in the dashboard:
<script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script>Three rules cover every platform below:
- In the head, as early as possible. Before stylesheets and other scripts if you can. The earlier it runs, the less there is to hide while a variant is applied.
- No
async, nodefer. A synchronous script is the only kind that is guaranteed to run before the page is painted. Loaded late, the snippet still works, but visitors may see the original content swap to the variant. - On every page. Experiments choose their pages by URL rules, and goals such as a thank-you page view have to be seen wherever they happen.
The key in the tag is a public key. It identifies the site and cannot read or change anything, so it is safe in page source.
What the tag loads#
One request returns one script: the site's current configuration followed by the runtime, which is under 22 KB gzipped and has no dependencies. There is no second request for configuration. The response is cached for 30 seconds and then revalidated in the background, so a change you make in the dashboard reaches visitors within a few minutes.
The URL never answers with an error. An unknown key, or a failure on our side, returns a script that does nothing, and your page renders as if the tag were not there. Including the tag twice is harmless: the second copy does nothing.
If a tool insists on a file extension, /s/<site key>.js serves the same script.
Plain HTML#
Put the tag directly after the charset and viewport meta tags, in the template or include that every page shares.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script>
<title>Your page</title>
<!-- stylesheets and other scripts -->
</head>
<body>
…
</body>
</html>Webflow#
Open the site-wide custom code
In your Webflow project, open Site settings, then Custom code.
Paste the tag into Head code
Use the Head code field, not Footer code. Code placed in the footer runs after the page is visible.
Save and publish
Custom code only runs on the published site, not in the Designer preview. Publish, then run the installation check in the dashboard.
Shopify#
Open the theme code
In the Shopify admin, go to Online Store, then Themes, and choose Edit code on the theme you want to change. Work on a duplicate first if the theme is live.
Edit layout/theme.liquid
Paste the tag directly after the opening
<head>tag and save.layout/theme.liquidliquid <!-- layout/theme.liquid --> <head> <script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script> <meta charset="utf-8"> {{ content_for_header }} … </head>
Checkout pages are not covered
theme.liquid, so the snippet is not present there and cannot see a purchase. Choose a goal on a page your theme does render — an add-to-cart click, a cart page view — or report the conversion from your own backend with the server SDK's track() once it is published (see the SDK reference).WordPress#
Print the tag from the wp_head hook with a low priority, so it comes before what other plugins add. In a child theme's functions.php, or a small site-specific plugin:
<?php
// functions.php of your (child) theme. Priority 1 prints the tag before other head output.
add_action('wp_head', function () {
echo '<script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script>' . "\n";
}, 1);A header-and-footer scripts plugin works as well, as long as it writes into the head and not the footer.
Exclude the tag from script optimization
Squarespace#
Open Code Injection
In the site's settings, find Code Injection (under the Developer Tools or Advanced section, depending on your version).
Paste the tag into the Header field
Use Header, which prints into the head of every page, not Footer.
Code Injectionhtml <!-- Settings > Developer Tools (or Advanced) > Code Injection > Header --> <script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script>Save and test on the live site
Open the published site in a normal browser window and run the installation check. Injected code does not run inside the Squarespace editor.
Plan requirement
Wix#
Open Custom Code
In the Wix dashboard, open Settings, then Custom Code, and choose Add Custom Code.
Paste the tag and choose where it loads
Set Add Code to Pages to All pages and Place Code in to Head. Body start and body end run after the page has started to paint.
Custom Codehtml <!-- Settings > Custom Code > Add Custom Code Add Code to Pages: All pages · Place Code in: Head --> <script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script>Apply and publish
Publish the site and check the live address. Custom code needs a site with a premium plan and a connected domain; it does not run on a free Wix site.
Framer#
Open the custom code settings
In the project, open Site Settings, then General, and find Custom Code.
Paste the tag at the start of the head
Use Start of <head> tag. The other locations run later in the document.
Custom Codehtml <!-- Site Settings > General > Custom Code > Start of <head> tag --> <script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script>Publish
Custom code only runs on the published site. Custom code on a Framer site needs a paid site plan.
GoHighLevel and Duda#
Both builders have a header code field that prints into the head of every page. Paste the tag there and nowhere else. The labels below are the ones the builders use at the time of writing; if the menu has moved, look for the field that says it adds code to the header or head of the whole site.
<!-- The platform's header tracking code field (printed inside <head>) -->
<script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script>- GoHighLevel. Open the funnel or website, then its Settings, and paste the tag into the Header Code of the tracking code section. It applies to every page of that funnel or website. Header code set on a single page applies to that page only, so a new funnel needs the tag again.
- Duda. Open the site's Settings and paste the tag into Head HTML, which applies to every page of the site.
- Publish afterwards and check the live address, not the builder's preview. Add the builder's own preview or staging host under the site's extra domains if you want to test there.
Google Tag Manager#
Prefer a direct install
Create a Custom HTML tag
Custom HTML taghtml <!-- Tag type: Custom HTML · Trigger: Initialization - All Pages --> <script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY"></script>Fire it as early as the container allows
Use the Initialization - All Pages trigger so the tag runs before your other tags. If the container uses consent settings, give the tag the consent requirements that match the site's consent mode.
Preview, then publish the container
Sending exposures to the data layer
Independently of how the snippet is installed, a site can push every experiment exposure to window.dataLayer. Enable the data layer integration in the site's settings and pick the event name; the snippet then pushes one entry the first time a visitor sees an experiment in a session:
window.dataLayer.push({
event: 'lift_exposure', // the event name configured for the site
lift: {
experimentId: '0198c1de-…',
experimentKey: 'hero-headline',
variantId: '0198c1df-…',
isControl: false,
},
});The array is only used when it already exists — the snippet never creates analytics globals of its own. The other integrations are listed in the JavaScript API reference.
Next.js and React#
There are two ways to run experiments on a React site. They can be combined.
Option 1: the snippet
Add the tag to the document head. In the Next.js App Router that is the root layout:
// app/layout.tsx
import type { ReactNode } from 'react';
export default function RootLayout({ children }: { children: ReactNode }) {
return (
<html lang="en">
<head>
{/* Synchronous on purpose: variants are applied before first paint. */}
{/* eslint-disable-next-line @next/next/no-sync-scripts */}
<script src="https://lift.example.com/s/lift_pk_YOUR_SITE_KEY" />
</head>
<body>{children}</body>
</html>
);
}The snippet is built for single-page apps: it watches route changes, re-evaluates which experiments apply after each navigation, and re-applies a variant's changes when the framework re-renders the elements they touch.
Server-rendered React and hydration
Option 2: server-side assignment with @lift/sdk
Not on a package registry yet
@lift/sdk is not published, so npm install @lift/sdk does not work for a site outside this workspace. Until it is, call the HTTP endpoints it wraps directly: POST /api/v1/assign with a JSON body of siteKey, visitorId and url (optionally sticky, device, userAgent, country) returns the visitor's assignments, and POST /api/v1/e with a text/plain JSON batch reports events. The samples below show the SDK as it will be used.The SDK decides on the server which variant a visitor gets, so the first byte of the response already carries it: no flicker, no hydration mismatch, and it works without the browser snippet. It runs anywhere fetch exists — Node 18 or later, edge runtimes, workers.
// lib/lift.ts
import { createLiftClient } from '@lift/sdk';
// Create it once per process and reuse it.
export const lift = createLiftClient({
siteKey: 'lift_pk_YOUR_SITE_KEY',
apiBase: 'https://lift.example.com',
});A visitor needs a stable id. The SDK reads and writes the same first-party cookie as the snippet (_lift_vid), so both agree on who the visitor is. Server components cannot set cookies, so mint the id in middleware:
// middleware.ts — every visitor has an id before the first page renders.
import { NextResponse, type NextRequest } from 'next/server';
import { buildVisitorCookies, generateVisitorId, readVisitorCookies } from '@lift/sdk';
export function middleware(request: NextRequest) {
const { visitorId } = readVisitorCookies(request.headers.get('cookie'));
if (visitorId) return NextResponse.next();
// First visit: mint an id, hand it to this render and persist it in the cookie
// the browser snippet reads (_lift_vid), so both share one visitor.
const id = generateVisitorId();
const headers = new Headers(request.headers);
headers.set('x-visitor-id', id);
const response = NextResponse.next({ request: { headers } });
for (const cookie of buildVisitorCookies({ visitorId: id, sticky: {}, isNewVisitor: true })) {
response.headers.append('set-cookie', cookie);
}
return response;
}
export const config = { matcher: ['/((?!_next/|api/|favicon.ico).*)'] };Then ask for the visitor's assignments where you render, and branch with the React bindings from @lift/sdk/react:
// app/pricing/page.tsx
import { headers } from 'next/headers';
import { readVisitorCookies } from '@lift/sdk';
import { LiftProvider, Variant } from '@lift/sdk/react';
import { lift } from '@/lib/lift';
export default async function PricingPage() {
const h = await headers();
const cookies = readVisitorCookies(h.get('cookie'));
const visitorId = cookies.visitorId ?? h.get('x-visitor-id');
// No id (middleware did not run): render the original page.
const result = visitorId
? await lift.getAssignments({
visitorId,
url: 'https://www.example.com/pricing',
userAgent: h.get('user-agent'),
referrer: h.get('referer'),
sticky: cookies.sticky,
isNewVisitor: cookies.visitorId === null,
})
: null;
return (
<LiftProvider assignments={result?.assignments ?? []}>
<Variant experiment="pricing-headline" control>
<h1>Simple pricing</h1>
</Variant>
<Variant experiment="pricing-headline" id="VARIANT_ID_FROM_THE_DASHBOARD">
<h1>Pay for what converts</h1>
</Variant>
</LiftProvider>
);
}getAssignmentsnever rejects. If the service cannot be reached the result has no assignments, and every<Variant control>branch renders — the control doubles as the default experience.- Exposures are recorded by the service as part of the call. A visitor who has already been exposed keeps their variant even when traffic weights change later.
- Conversions can come from the snippet on the same page (it shares the visitor id), or from your server with
track(). - Only set the visitor cookie when your consent rules allow storage for that visitor. The SDK does not make that decision for you.
The full surface of the SDK is in the JavaScript API reference.
Sites with a strict Content-Security-Policy#
A site that sends a Content-Security-Policy header must allow the host that serves the tag. That host is the origin in the tag's src, shown on the site's Install page. One host serves everything the snippet needs:
script-src: the Avenue Lift origin. It loads the loader script, and the visual editor and debug panel bundle only when a team member opens them.connect-src: the same origin. Events are sent to/api/v1/ewithsendBeaconorfetch. The runtime configuration is already inside the loader, so/api/v1/configis only requested as a fallback, and the editor calls/api/editor.- No inline script is needed. The tag is an external script, so it needs no nonce or hash. An inline pre-load stub, like the one in the consent examples, is optional and would need its own nonce or hash; put it in a file you host instead if you want to avoid that.
- Inline styles. The snippet writes
<style>elements for the anti-flicker mask and for CSS changes made by a variant. It does not set a nonce. Under astyle-srcwithout'unsafe-inline'the browser blocks them: the mask is not applied, so visitors can see the original content before a variant, and CSS changes do not take effect.
Content-Security-Policy:
script-src 'self' https://lift.example.com;
connect-src 'self' https://lift.example.com;
style-src 'self' 'unsafe-inline'Add these values to the directives you already have; do not replace them. A site that lists no script-src or connect-src falls back to its default-src, which then needs the origin.
When the snippet is blocked
Verifying the installation#
- The installation check on the site's Install page fetches your home page and reports whether the tag is present and where.
- The site's status changes from pending to active after the first real page view reports in.
- On any page, the QA debug mode shows what the snippet loaded and what it is doing.
Events are only accepted from the site's domain, its subdomains and the extra domains listed in the site's settings. If a staging host does not report, add it there.