Browser

@trevosdk/browser assigns variants and records events in the browser. It never touches the DOM — your own code branches on the variant it returns. Under 10kb gzipped, no dependencies.

Install

npm install @trevosdk/browser

Without a bundler

The CDN build exposes a global called Trevo. Pin the exact version in production — the floating channels change under you with no deploy on your side.

<script src="https://cdn.trevosdk.com/browser/v0.2.4/trevo.min.js"></script>
<script>
  Trevo.init({ apiKey: 'tsk_live_…' });
</script>

URL	Updates	Cache
`…/browser/v0.2.4/trevo.min.js`	never	1 year
`…/browser/v0/trevo.min.js`	patches and minors within v0	5 minutes
`…/browser/latest/trevo.min.js`	every release	5 minutes

Use v0 or latest for prototyping only.

Initialise

import trevo from '@trevosdk/browser';

trevo.init({ apiKey: process.env.NEXT_PUBLIC_TREVO_API_KEY });

The key is publishable (tsk_live_…) and belongs in your client bundle. Server keys (tsk_secret_…) are rejected from browsers. init() is re-entrant — calling it again reconfigures rather than duplicating.

Options

Option	Default	Notes
`apiKey`	—	Required
`bootstrap`	—	Pre-resolved `{ experimentKey: variantName }` for a correct first paint. See Next.js
`manualReveal`	`false`	With the anti-flicker snippet, wait for your `reveal()` instead of revealing automatically

Identify the user

trevo.identify(currentUser.id);

Before this, users are bucketed on an anonymous id stored in local storage. After it, they are bucketed on your user id — which means identify() can change a user’s variant. Call it as early as you can, and before rendering anything under test. Anonymous ids are per browser, so the same person on a phone and a laptop is two participants until they sign in. On logout:

trevo.reset();

Read a variant

const variant = trevo.getVariant('checkout-cta');

Synchronous, no network call, and deterministic — the same identity and key always produce the same variant. Unknown keys return 'control', so this is safe to ship before the experiment exists. Each call records an exposure. To read without recording one:

trevo.getVariant('checkout-cta', { trackExposure: false });

Typed variants

defineExperiment() returns a typed union and turns an unhandled variant into a compile error — so a variant added in Trevo that your code does not handle fails the build instead of silently falling through:

import { defineExperiment, assertNever } from '@trevosdk/browser';

const emailTiming = defineExperiment('email-capture-timing', [
  'control',
  'before-checkout',
  'after-payment',
]);

switch (trevo.getVariant(emailTiming)) {
  case 'control':          return null;
  case 'before-checkout':  return <EmailBeforeCheckout />;
  case 'after-payment':    return <EmailAfterPayment />;
  default:                 return assertNever(variant);
}

Track conversions

trevo.track('purchase_completed', { value: 49.99, plan: 'pro' });

Batched automatically — up to 50 events per request, flushed every couple of seconds and on page unload. trevo.flush() forces a send if you need one. Limits: event names up to 500 characters, properties up to 8KB serialised.

Waiting for config

On a first visit the SDK has no cached config, so getVariant() returns 'control' until the first fetch lands. Returning visitors read from a warm cache and are correct immediately.

if (trevo.isReady()) {
  // safe to read synchronously during render
}

await trevo.ready();  // resolves when config loads, or the first fetch fails

Config is polled every 60 seconds and cached in local storage for 24 hours, so a slow network delays the first visit only. To avoid the flash of control on a first visit entirely, either resolve variants on the server (Next.js) or use the anti-flicker snippet below.

Anti-flicker

Hides the page until variants are resolved, with a safety timeout so a blocked or failed SDK can never leave your page blank:

import { ANTI_FLICKER_SNIPPET } from '@trevosdk/browser';

Inline it in a <script> in <head>, before anything renders. It reveals automatically after 1 second by default:

<script>window.__trevoConfig = { timeout: 2000 };</script>

With manualReveal: true, call trevo.reveal() once you have committed the variant. Server-side bootstrapping is better where you can do it — nothing is hidden and there is no timeout to tune.

trevo.optOut();   // stops everything, clears identity, drops queued events
trevo.reset();    // clears the user, keeps the anonymous id

optOut() is idempotent and safe to call before init().

API summary

Method	Purpose
`init(options)`	Start the SDK
`identify(userId)`	Set the authenticated user
`getVariant(key, options?)`	Resolve a variant, recording an exposure by default
`trackExposure(key, variant)`	Record an exposure explicitly
`track(name, properties?)`	Queue a conversion event
`flush()`	Send queued events now
`isReady()` / `ready()`	Whether config has loaded
`reset()`	Clear the user (logout)
`optOut()`	Stop all activity (consent withdrawal)
`reveal()`	Reveal the anti-flicker overlay
`destroy()`	Tear down entirely

Getting started

Install

Concepts

Reference

Troubleshooting

Install

Without a bundler

Initialise

Options

Identify the user

Read a variant

Typed variants

Track conversions

Waiting for config

Anti-flicker

API summary

​Install

​Without a bundler

​Initialise

​Options

​Identify the user

​Read a variant

​Typed variants

​Track conversions

​Waiting for config

​Anti-flicker

​Consent and opt-out

​API summary

Install

Without a bundler

Initialise

Options

Identify the user

Read a variant

Typed variants

Track conversions

Waiting for config

Anti-flicker

Consent and opt-out

API summary