@trevosdk/browser

Lightweight browser client for Trevo experiments — deterministic variant assignment and event tracking. Branch on getVariant() in your own code; Trevo Bot opens PRs that wire up the variants, so the SDK never mutates the DOM at runtime.

Install

npm install @trevosdk/browser

CDN (script tag)

No bundler? Load the minified IIFE build from the CDN. It exposes a global Trevo. Pin an exact version in production:

<script src="https://cdn.trevosdk.com/browser/v0.3.2/trevo.min.js"></script>
<script>
  Trevo.init({ apiKey: 'tsk_live_...' });
  Trevo.identify('user-42');
  if (Trevo.getVariant('checkout-cta') === 'treatment') {
    // show alternate experience
  }
  Trevo.track('checkout_started');
</script>

| URL | Updates | Cache | | --- | --- | --- | | …/browser/v0.3.2/trevo.min.js | never (immutable) | 1 year | | …/browser/v0/trevo.min.js | patches & minors within v0 | 5 min | | …/browser/latest/trevo.min.js | every release | 5 min |

Use v0 or latest only for prototyping — pin a full version for production.

Quick Start

import trevo from '@trevosdk/browser';

trevo.init({ apiKey: 'tsk_live_...' });
trevo.identify('user-42');

const variant = trevo.getVariant('checkout-cta');
if (variant === 'treatment') {
  // show alternate experience
}

trevo.track('checkout_started');

Using a framework?

This package is the framework-free JavaScript core. Framework integrations ship as their own packages, built on top of it:

• React — @trevosdk/react: <TrevoProvider> + useExperiment() hooks, SSR-safe.
• Next.js — @trevosdk/nextjs: bucketing middleware + getTrevoBootstrap() for flicker-free SSR.

Typed variants (multi-arm)

Declare an experiment's variants once with defineExperiment to get a typed union back and exhaustive handling — so an arm added in Trevo that the code doesn't handle is a compile error, not a silent fallthrough:

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

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

const variant = trevo.getVariant(emailTiming); // 'control' | 'before-checkout' | 'after-payment'
switch (variant) {
  case 'control':
    break;
  case 'before-checkout':
    showEmailBeforeCheckout();
    break;
  case 'after-payment':
    showEmailAfterPayment();
    break;
  default:
    assertNever(variant); // fails to compile if a variant is unhandled
}

The same defineExperiment handle works with useExperiment in @trevosdk/react and with @trevosdk/node. A resolved value outside the declared set falls back to the first variant, and a mismatch between the declared set and the Trevo config logs a warning — surfacing drift between the shipped code and Trevo.

API

| Method | Description | | --- | --- | | init({ apiKey }) | Initialize the SDK. Starts event queue and config polling. | | identify(userId) | Set the authenticated user. May change variant assignment. | | getVariant(experimentKey, options?) | Returns the assigned variant ("control" as fallback). Fires an exposure event by default; pass { trackExposure: false } to read the assignment for rendering without exposure. | | trackExposure(experimentKey, variantName) | Emit an exposure explicitly — call when the treatment surface is actually visible. Deduplicated per identity; a no-op unless the experiment/variant is configured. | | isReady() | true once config has loaded (or the first fetch failed). Use to read getVariant() synchronously during render. | | ready() | Resolves once config has loaded (or the first fetch failed). | | track(eventName, properties?) | Enqueue a tracking event. Batched and flushed automatically. | | flush() | Manually flush all queued events. |

Documentation

Full docs at docs.trevosdk.com

License

MIT