Skip to main content

JavaScript Browser SDK

The Hyppot JavaScript SDK allows you to integrate A/B testing and feature flags directly on the frontend of your web application. It works with any JavaScript framework or vanilla JavaScript and provides automatic impression tracking and easy conversion tracking.

Installation​

Install the SDK using npm or yarn:

# Using npm
npm install hyppot-browser

# Using yarn
yarn add hyppot-browser

Or include it directly in your HTML:

<script src="https://unpkg.com/hyppot-browser@latest/dist/index.umd.js"></script>

Basic Setup​

Configure and initialize Hyppot in your application:

import { configureHyppot } from 'hyppot-browser';

// Configure Hyppot
const { resolver, tracker } = configureHyppot((config) => {
  config.prefix = '/hyppot'; // API endpoint prefix
});

// Initialize with user ID
const userId = 'user-123';
await resolver.initialize(userId);

Resolving Feature Toggles​

Resolve feature flags to control on/off or variable-based behavior:

// Resolve a specific feature toggle
const toggle = resolver.resolveFeatureToggle('new-checkout');

// Always provide a fallback value
const isEnabled = toggle?.isEnabled ?? false;

if (isEnabled) {
  document.querySelector('.new-checkout')?.classList.remove('hidden');
} else {
  document.querySelector('.new-checkout')?.classList.add('hidden');
}

// Toggles can also expose other variables
const buttonColor = toggle?.getVariableValue('button-color') ?? 'blue';
document.querySelector('.cta-button').style.backgroundColor = buttonColor;

Remarks:

  • Automatic impression tracking is only applied for experiments. Resolving feature toggles does not emit impressions.
  • Only features exposed to frontend will be resolved via the Browser SDK (hidden by default). To make feature toggle visible via browser integration, switch off the "Backend only" option in feature toggle configuration.

Resolving Experiments​

Once initialized, resolve experiments to get variant information:

// Resolve a specific experiment
const experiment = resolver.resolveExperiment('button-color-test');

if (experiment) {
  // Get variable values
  const buttonColor = experiment.getVariableValue('button-color');
  const showFeature = experiment.getVariableValue('show-feature');
  
  // Apply the variant
  document.querySelector('.cta-button').style.backgroundColor = buttonColor;
  
  if (showFeature) {
    document.querySelector('.new-feature').style.display = 'block';
  }
}

Tracking Conversions​

Track user actions as conversions:

// Track a simple conversion
tracker.trackConversion({
  conversionType: { type: 'button-click' },
  user: userId,
  eventDate: new Date()
});

// Track conversion with metrics
tracker.trackConversion({
  conversionType: { type: 'purchase' },
  user: userId,
  eventDate: new Date(),
  metrics: [
    { name: 'value', value: 99.99 },
    { name: 'product-id', value: 'product-123' },
    { name: 'category', value: 'electronics' }
  ]
});

Configuration Options​

Below is the summary of available configuration options for the SDK:

const { resolver, tracker } = configureHyppot((config) => {
  // API endpoint prefix (default: '/hyppot')
  config.prefix = '/hyppot';
  
  // Session storage key (default: 'Hyppot_Ex')
  config.experimentStatusKey = 'MyApp_Experiments';
  
  // Automatic impression tracking (default: true)
  config.autoTrackImpressions = true;
});

Best Practices​

1. Initialize Early​

Initialize Hyppot as early as possible to avoid layout shifts:

// Initialize immediately when user is identified
const userId = await getCurrentUserId();
await resolver.initialize(userId);

2. Handle Loading States​

Always handle the loading state while Hyppot initializes:

if (!resolver.isReady) {
  // Show loading state or default variant
  return <DefaultComponent />;
}

3. Graceful Degradation​

Handle cases where experiments might not be available:

const experiment = resolver.resolve('my-experiment');
const featureEnabled = experiment?.getVariableValue('feature-enabled') ?? false;

// Always have a fallback
if (featureEnabled) {
  showNewFeature();
} else {
  showDefaultFeature();
}

4. Track Meaningful Conversions​

Track conversions that matter to your business:

// Good: Track business-relevant actions
tracker.trackConversion({
  conversionType: { type: 'purchase' },
  user: userId,
  eventDate: new Date(),
  metrics: [
    { name: 'revenue', value: 29.99 },
    { name: 'items', value: 2 }
  ]
});

// Avoid: Tracking every minor interaction

Next Steps​