Installation

The Ttoolab pixel is a JavaScript SDK that loads on your site, fetches active experiments, assigns visitors to variants, and sends events.

Get your project key

Sign in to the Ttoolab dashboard.
Open your project settings.
Copy the public key (format: pk_...).

Use a placeholder like PROJECT_KEY in the examples below. Replace it with your real project key in production.

Standard HTML installation

Add this snippet to the <head> of every page, before other scripts that depend on experiment assignments:

<script>
  window.ttoolabSettings = {
    projectKey: "PROJECT_KEY",
    endpoint: "https://sdk.ttoolab.com"
  };
</script>
<script async src="https://sdk.ttoolab.com/ttoolab.min.js"></script>

The pixel auto-initializes when the script loads. You do not need to call ttoolab.init() unless you want to pass configuration programmatically.

Alternative: project key in script URL

You can pass the project key as a query parameter on the script tag:

<script async src="https://sdk.ttoolab.com/ttoolab.min.js?project=PROJECT_KEY"></script>

When using this method, the SDK derives the endpoint from the script origin (https://sdk.ttoolab.com).

Google Tag Manager

Create a Custom HTML tag in GTM:

<script>
  window.ttoolabSettings = {
    projectKey: "PROJECT_KEY",
    endpoint: "https://sdk.ttoolab.com"
  };
</script>
<script async src="https://sdk.ttoolab.com/ttoolab.min.js"></script>

Recommended trigger: All Pages, firing as early as possible (e.g. Consent Initialization or Page View, depending on your consent setup).

Single Page Applications (React, Vue, Next.js, etc.)

Load the pixel once in your root layout or index.html. The SDK reads the current URL on each page load.

For client-side route changes without full page reloads:

// After a client-side navigation, the SDK uses the URL from the initial bootstrap.
// Re-fetching happens on the next full page load.
// TODO: confirm with the Ttoolab team whether SPA re-bootstrap is supported.

Use ttoolab.ready() to run code after the SDK has loaded experiment data:

window.ttoolab?.ready(() => {
  const variant = window.ttoolab?.getVariant("EXPERIMENT_KEY");
  console.log("Assigned variant:", variant);
});

Programmatic initialization

If you load the SDK dynamically, call init with your configuration:

window.ttoolab?.init({
  projectKey: "PROJECT_KEY",
  endpoint: "https://sdk.ttoolab.com"
});

Verify installation

Open your site in a browser with DevTools.
Check the Network tab for a request to /sdk/bootstrap?projectKey=....
Confirm the response includes experiment assignments when a published experiment matches the current URL.

If bootstrap returns an empty blob, the project key is valid but no running experiments match the page URL.

Content Security Policy

If your site uses CSP, allow scripts and connections to the SDK host:

script-src https://sdk.ttoolab.com;
connect-src https://sdk.ttoolab.com;

Adjust for your custom endpoint if applicable.

What happens after install?

On each page load, the pixel:

Generates or reads an anonymous visitor ID (stored in localStorage)
Calls GET /sdk/bootstrap with the project key, visitor ID, and current URL
Assigns the visitor to matching experiment variants
Applies DOM changes for A/B test variants
Sends an automatic exposure event ($exposure) when assignments are active