Web Experiments

const experiments = posthog.experiments;

/**
 * Get web experiments and evaluate display logic
 * @param forceReload - Force reload from server, bypassing cache
 */
function getWebExperimentsAndEvaluateDisplayLogic(forceReload?: boolean): void;

import posthog from 'posthog-js';

// Automatically load and apply experiments
posthog.experiments.getWebExperimentsAndEvaluateDisplayLogic();

// Force reload from server
posthog.experiments.getWebExperimentsAndEvaluateDisplayLogic(true);

/**
 * Get web experiments with callback
 * @param callback - Called with array of web experiments
 * @param forceReload - Force reload from server
 * @param previewing - Enable preview mode (for testing)
 */
function getWebExperiments(
  callback: WebExperimentsCallback,
  forceReload: boolean,
  previewing?: boolean
): void;

type WebExperimentsCallback = (webExperiments: WebExperiment[]) => void;

posthog.experiments.getWebExperiments(
  (experiments) => {
    console.log('Loaded experiments:', experiments);
    experiments.forEach(exp => {
      console.log(`Experiment ${exp.name}: ${exp.variants}`);
    });
  },
  false // Don't force reload
);

/**
 * Preview a web experiment from URL parameters
 * Looks for __experiment_id and __experiment_variant query params
 */
function previewWebExperiment(): void;

// URL: https://example.com?__experiment_id=123&__experiment_variant=test
posthog.experiments.previewWebExperiment();
// Applies the "test" variant of experiment 123

/**
 * Load experiments if enabled in config
 * Typically called internally during initialization
 */
function loadIfEnabled(): void;

posthog.init('YOUR_PROJECT_API_KEY', {
  api_host: 'https://us.i.posthog.com',
  // Web experiments are disabled by default (beta feature)
  disable_web_experiments: false, // Set to false to enable
});

interface WebExperiment {
  /** Unique experiment ID */
  id: number;
  /** Human-readable experiment name */
  name: string;
  /** Optional feature flag key controlling this experiment */
  feature_flag_key?: string;
  /** Map of variant names to variant configurations */
  variants: Record<string, WebExperimentVariant>;
}

interface WebExperimentVariant {
  /** Display conditions for this variant */
  conditions?: WebExperimentConditions;
  /** Variant name (matches feature flag variant value) */
  variant_name: string;
  /** List of transformations to apply */
  transforms: WebExperimentTransform[];
}

interface WebExperimentConditions {
  /** URL matching configuration */
  url?: string;
  /** How to match the URL */
  urlMatchType?: WebExperimentUrlMatchType;
  /** UTM parameter matching */
  utm?: {
    utm_source?: string;
    utm_medium?: string;
    utm_campaign?: string;
    utm_term?: string;
  };
}

type WebExperimentUrlMatchType =
  | 'regex'         // Regular expression match
  | 'not_regex'     // Inverse regex match
  | 'exact'         // Exact URL match
  | 'is_not'        // URL is not this value
  | 'icontains'     // URL contains substring (case-insensitive)
  | 'not_icontains' // URL does not contain substring
  ;

interface WebExperimentTransform {
  /** CSS selector to target elements */
  selector?: string;
  /** HTML attributes to set/modify */
  attributes?: Array<{ name: string; value: string }>;
  /** Text content to replace */
  text?: string;
  /** HTML content to replace */
  html?: string;
  /** Image URL to replace */
  imgUrl?: string;
  /** CSS styles to apply */
  css?: string;
}

// Change button text
{
  selector: '.cta-button',
  text: 'Buy Now - 20% Off!'
}

// Modify image source
{
  selector: '#hero-image',
  imgUrl: 'https://example.com/new-hero.jpg'
}

// Apply custom CSS
{
  selector: '.pricing-card',
  css: 'background-color: #ff6b6b; border: 2px solid #000;'
}

// Change multiple attributes
{
  selector: 'a.signup-link',
  attributes: [
    { name: 'href', value: '/special-offer' },
    { name: 'class', value: 'btn btn-primary' }
  ]
}

// Replace HTML content
{
  selector: '.announcement',
  html: '<strong>Limited Time:</strong> Get 50% off!'
}