Browser script

1. Add the script

The browser script shows one of your versions and records whether visitors reach a goal. Install it throughout the visitor's journey so a later goal can be linked to what they saw.

Sign in or create an account, then enter your website address in Dashboard. The examples will then show your site's public ID.

Until then, YOUR_PUBLIC_SITE_ID below is a placeholder, not a working site.

Put this script once in <head> in your shared page layout, so it loads on every relevant page: marketing pages, sign-up and sign-in pages, forms, and the final goal page. Use the same public site ID throughout. Never put a private integration key or an agent access token in your HTML.

Copy<script defer src="https://version.compare/embed.js" data-site="YOUR_PUBLIC_SITE_ID"></script>

Your site's Setup tab lists its Allowed websites. The website address you used to create the site is already allowed. Add any other domains that should track versions or goals for this site, such as your checkout or app.

If your site uses a Content Security Policy, allow the script URL above in script-src and https://version.compare in connect-src. Keep your other policy restrictions.

2. Add versions

Choose a part of your page you would like to improve, such as its headline, and write a few alternatives. Group them in your HTML so Version Compare knows they are different versions of the same thing.

Mark the containing element with data-vc and each direct alternative with data-vc-version. One or more alternatives are supported, with no per-set count limit.

We recommend leaving your preferred fallback visible and adding hidden to the others, so the page stays useful before the script loads or if it cannot load. This is a recommendation, not a requirement: when the script runs, it makes one usable alternative visible.

Copy<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Our coffee</title>
  <script defer src="https://version.compare/embed.js" data-site="YOUR_PUBLIC_SITE_ID"></script>
</head>
<body>
<section data-vc>
  <h1 data-vc-version>Coffee for your everyday ritual</h1>
  <h1 data-vc-version hidden>A better start to your morning</h1>
</section>
<a href="/thanks">Try the page goal</a>
</body>
</html>

Publish this page on an allowed website. The ordinary link above is for trying the page goal; on your real site, use the actual confirmation page for the action you care about.

• Keep alternatives directly inside their marked container. Do not nest version sets.
• Sets may be present in the original HTML or inserted later by JavaScript. You can also add or replace alternatives after the page loads.
• Changing an alternative's content makes it a different version. For example, changing a headline starts fresh results for that wording, rather than combining them with the old headline's results.
• A visitor keeps the same valid choice on later visits. There is no time limit on their choice or on crediting a later goal to a version they actually saw. A single-alternative set is still shown and measured.

An id on the container or a unique data-vc-id keeps the same set together if it moves within the page. Otherwise its position in the page identifies it. A different website address or page path creates a different set.

3. Choose a goal

Decide what success looks like: a completed sign-up, a purchase, or a click on a useful link. A goal tells us which outcome to optimise for.

Open the site's Goals tab. Give the goal a useful label and choose its type. Leave Applies to set to All site version sets to start; after discovery, you can scope a goal to one set.

A page visit

Use this when the action ends on a particular page, such as a purchase confirmation. Reaching that page counts towards versions the visitor saw earlier.

Choose Page visit (URL or path) and enter /thanks or a destination such as checkout.example.com/thanks. You can omit https://. With several allowed websites, choose which website a relative path belongs to. Start a dotted filename with / or ./ to keep it relative.

Serve this page at /thanks, using the same public site ID. A goal destination does not need its own version set.

Copy<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Thank you</title>
  <script defer src="https://version.compare/embed.js" data-site="YOUR_PUBLIC_SITE_ID"></script>
</head>
<body>
  <h1>Thank you</h1>
</body>
</html>

Page goals count document loads and page-path changes made with the browser's history API, including single-page app navigation and Back or Forward. A form submission alone is not a page visit. Query strings and fragments are ignored, so /thanks?order=123#receipt matches /thanks.

An interaction

Use this when the action happens on the page, such as opening delivery details. Mark the button or link instead of adding a separate confirmation page.

Choose Named interaction (event name) and enter show-details. Add this HTML to a page with the script. The data-vc-goal value must match the interaction name exactly.

Copy<button type="button" data-vc-goal="show-details" popovertarget="delivery">
  Delivery details
</button>
<div id="delivery" popover>
  <p>Delivery takes three to five working days.</p>
  <button type="button" popovertarget="delivery" popovertargetaction="hide">
    Close
  </button>
</div>

This example counts opening the delivery details, not a purchase. Native buttons and links work with clicks and keyboard activation, including clicks on their child elements. The attribute records the interaction; your button or link still performs its normal action.

One goal for many items

If you are testing descriptions for several products, you can share one Add to cart goal while keeping each product's results separate.

Create one Named interaction (event name) goal with the name add-to-cart and Applies to set to All site version sets. You do not need a separate goal for each product.

On a page with the script installed, put the Product ID in data-vc-item on a wrapper around that product's versions and button:

Copy<article data-vc-item="coffee-123">
  <section data-vc>
    <p data-vc-version>Freshly roasted beans</p>
    <p data-vc-version hidden>A richer morning ritual</p>
  </section>
  <button type="button" data-vc-goal="add-to-cart">Add to cart</button>
</article>

Use the same markup for other products with their own product IDs. The nearest data-vc-item wrapper supplies the ID to both the version set and the button. If the button is outside the wrapper, put the matching data-vc-item on the button itself.

Clicking product A's button credits only versions actually observed for product A. Use public product or item IDs, never customer identifiers.

4. Check your setup

1. Open the published page on an allowed website. Keep the version set visible, then activate the interaction or visit the goal page.
2. Return to Setup. It stops showing pending after an approved browser connection, not merely a script download.
3. Open Versions to see the discovered sets and real counts. Only versions actually observed in the visible page count as visits.

Your test visits are real evidence. Use a separate test site if you do not want them in your results. Previews are unavailable for private pages or content created only by page scripts: the preview worker does not run your application's JavaScript.

Allowed websites

This list controls which domains may track versions and goals for this site in Version Compare. It helps keep another website's browser traffic out of your results. Include every domain in your visitor's journey, such as your marketing site, app, and checkout. The domain you added when creating the site is already allowed.

In Setup, add each Website address, such as checkout.example.com. Leave out page paths: an allowed address covers the whole website. www.example.com and example.com need separate entries.

The service checks the browser's Origin header against this list. Browsers prevent ordinary third-party page scripts from forging this header, so an unrelated website cannot normally use your public site ID to send browser measurements. Non-browser clients can forge it: this check is not proof of genuine visitors or protection against fabricated traffic.

Track a sign-up across websites

A visitor may see a marketing version, browse other pages, sign up on another website, open an email sign-in link in a new tab, complete some forms, and finally reach your goal.

1. Allow every website in that journey in the same site's Setup, such as https://www.example.com and https://app.example.com.
2. Install the same public site's script in the shared layout on every relevant page, including the sign-up, sign-in, form, and final goal pages.
3. Use ordinary links between the websites. No special link attributes or manually forwarded tracking tokens are needed.
4. Choose the actual completion page or interaction as your goal, not the first sign-up page unless arriving there is what you want to measure.

Copy<a href="https://app.example.com/sign-up">
  Create your account
</a>

The script automatically carries observed versions when the visitor follows a link to another allowed website. Once that website has received them, its browser storage makes them available on later pages and in new tabs in the same browser. You do not need to pass tracking information through every form or email link.

An independent visit to an unrelated website cannot be joined automatically. An email opened in another browser or on another device, or a hop the installed scripts cannot observe, needs application integration to connect the journey. Clearing or blocking browser storage also limits continuity.

Navigation is never blocked for tracking. If the scripts cannot prepare a transfer before the visitor leaves, the link still works, but the next website may not receive the earlier observations.

Fallback behaviour

Visitors should still get a useful page if the service is unreachable or the script has not loaded. Choose a fallback: the version you want to show until Version Compare can choose.

Your fallback is the first alternative you leave visible, or the first alternative if all are hidden. Once the script runs, it shows just one alternative, even if its request to the service fails. Do not hide the whole set while waiting, or override the alternatives' hidden attribute with CSS.

Without the script, the browser shows your HTML as written. If several alternatives lack hidden, all of them may appear; if all are hidden, none appear. Leaving exactly one visible is the safest starting point.

With a working connection, the script may replace the fallback with the selected version. A slow response can make that change visible; this integration does not promise zero flicker.

Privacy and limits

To link a later goal to what a visitor saw, the script needs to remember their version choices. It saves these in the browser on your website. These are the limits to what it remembers and measures:

• Visitor choices and credit for later goals have no time limit. Only a version actually observed can receive credit, never one merely selected but not seen. A visitor can credit a stored choice only once, even if they repeat the goal.
• The script saves choices and observation identifiers in the website's own localStorage, scoped to this site and website address. These identifiers persist across visits and are available to later pages and tabs in the same browser.
• When storage is blocked, selection and goals can still work on the current page, but continuity across navigation is limited.
• Browser tracking sends requests directly to our service. Our infrastructure receives those connections.
• Stored page addresses exclude query strings and fragments. Do not put personal information in page paths, marked content, or interaction names.

Use the script in accordance with your site's privacy and consent requirements. Read the privacy policy.