Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

feat: Experiments

Blue Mouse94309305dcdc
diff --git a/src/Lib.ts b/src/Lib.ts
index 526deaa39..d341df082 100644
--- a/src/Lib.ts
+++ b/src/Lib.ts
@@ -120,11 +120,26 @@ export interface FeatureFlagsOptions {
}
/**
- * Cached feature flags with timestamp.
+ * Options for evaluating experiments.
*/
-interface CachedFlags {
+export interface ExperimentOptions {
+ /**
+ * Optional profile ID for long-term user tracking.
+ * If not provided, an anonymous profile ID will be generated server-side based on IP and user agent.
+ * Overrides the global profileId if set.
+ */
+ profileId?: string
+}
+
+/**
+ * Cached feature flags and experiments with timestamp.
+ */
+interface CachedData {
flags: Record<string, boolean>
+ experiments: Record<string, string>
timestamp: number
+ /** The profileId used when fetching this cached data */
+ profileId?: string
}
/**
@@ -218,7 +233,7 @@ export class Lib {
private perfStatsCollected: boolean = false
private activePage: string | null = null
private errorListenerExists = false
- private cachedFlags: CachedFlags | null = null
+ private cachedData: CachedData | null = null
constructor(private projectID: string, private options?: LibOptions) {
this.trackPathChange = this.trackPathChange.bind(this)
@@ -407,11 +422,11 @@ export class Lib {
}
/**
- * Fetches all feature flags for the project.
+ * Fetches all feature flags and experiments for the project.
* Results are cached for 5 minutes by default.
*
* @param options - Options for evaluating feature flags.
- * @param forceRefresh - If true, bypasses the cache and fetches fresh flags.
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
* @returns A promise that resolves to a record of flag keys to boolean values.
*/
async getFeatureFlags(options?: FeatureFlagsOptions, forceRefresh?: boolean): Promise<Record<string, boolean>> {
@@ -419,51 +434,68 @@ export class Lib {
return {}
}
- // Check cache first
- if (!forceRefresh && this.cachedFlags) {
+ const requestedProfileId = options?.profileId ?? this.options?.profileId
+
+ // Check cache first - must match profileId and not be expired
+ if (!forceRefresh && this.cachedData) {
const now = Date.now()
- if (now - this.cachedFlags.timestamp < DEFAULT_CACHE_DURATION) {
- return this.cachedFlags.flags
+ const isSameProfile = this.cachedData.profileId === requestedProfileId
+ if (isSameProfile && now - this.cachedData.timestamp < DEFAULT_CACHE_DURATION) {
+ return this.cachedData.flags
}
}
try {
- const apiBase = this.getApiBase()
- const body: { pid: string; profileId?: string } = {
- pid: this.projectID,
- }
+ await this.fetchFlagsAndExperiments(options)
+ return this.cachedData?.flags || {}
+ } catch (error) {
+ console.warn('[Swetrix] Error fetching feature flags:', error)
+ return this.cachedData?.flags || {}
+ }
+ }
- // Use profileId from options, or fall back to global profileId
- const profileId = options?.profileId ?? this.options?.profileId
- if (profileId) {
- body.profileId = profileId
- }
+ /**
+ * Internal method to fetch both feature flags and experiments from the API.
+ */
+ private async fetchFlagsAndExperiments(options?: FeatureFlagsOptions | ExperimentOptions): Promise<void> {
+ const apiBase = this.getApiBase()
+ const body: { pid: string; profileId?: string } = {
+ pid: this.projectID,
+ }
- const response = await fetch(`${apiBase}/feature-flag/evaluate`, {
- method: 'POST',
- headers: {
- 'Content-Type': 'application/json',
- },
- body: JSON.stringify(body),
- })
+ // Use profileId from options, or fall back to global profileId
+ const profileId = options?.profileId ?? this.options?.profileId
+ if (profileId) {
+ body.profileId = profileId
+ }
- if (!response.ok) {
- console.warn('[Swetrix] Failed to fetch feature flags:', response.status)
- return this.cachedFlags?.flags || {}
- }
+ const response = await fetch(`${apiBase}/feature-flag/evaluate`, {
+ method: 'POST',
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ body: JSON.stringify(body),
+ })
- const data = (await response.json()) as { flags: Record<string, boolean> }
+ if (!response.ok) {
+ console.warn('[Swetrix] Failed to fetch feature flags and experiments:', response.status)
+ return
+ }
- // Update cache
- this.cachedFlags = {
- flags: data.flags,
- timestamp: Date.now(),
- }
+ const data = (await response.json()) as {
+ flags: Record<string, boolean>
+ experiments?: Record<string, string>
+ }
- return data.flags
- } catch (error) {
- console.warn('[Swetrix] Error fetching feature flags:', error)
- return this.cachedFlags?.flags || {}
+ // Use profileId from options, or fall back to global profileId
+ const cachedProfileId = options?.profileId ?? this.options?.profileId
+
+ // Update cache with both flags and experiments
+ this.cachedData = {
+ flags: data.flags || {},
+ experiments: data.experiments || {},
+ timestamp: Date.now(),
+ profileId: cachedProfileId,
}
}
@@ -481,10 +513,84 @@ export class Lib {
}
/**
- * Clears the cached feature flags, forcing a fresh fetch on the next call.
+ * Clears the cached feature flags and experiments, forcing a fresh fetch on the next call.
*/
clearFeatureFlagsCache(): void {
- this.cachedFlags = null
+ this.cachedData = null
+ }
+
+ /**
+ * Fetches all A/B test experiments for the project.
+ * Results are cached for 5 minutes by default (shared cache with feature flags).
+ *
+ * @param options - Options for evaluating experiments.
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
+ * @returns A promise that resolves to a record of experiment IDs to variant keys.
+ *
+ * @example
+ * ```typescript
+ * const experiments = await getExperiments()
+ * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
+ * ```
+ */
+ async getExperiments(options?: ExperimentOptions, forceRefresh?: boolean): Promise<Record<string, string>> {
+ if (!isInBrowser()) {
+ return {}
+ }
+
+ const requestedProfileId = options?.profileId ?? this.options?.profileId
+
+ // Check cache first - must match profileId and not be expired
+ if (!forceRefresh && this.cachedData) {
+ const now = Date.now()
+ const isSameProfile = this.cachedData.profileId === requestedProfileId
+ if (isSameProfile && now - this.cachedData.timestamp < DEFAULT_CACHE_DURATION) {
+ return this.cachedData.experiments
+ }
+ }
+
+ try {
+ await this.fetchFlagsAndExperiments(options)
+ return this.cachedData?.experiments || {}
+ } catch (error) {
+ console.warn('[Swetrix] Error fetching experiments:', error)
+ return this.cachedData?.experiments || {}
+ }
+ }
+
+ /**
+ * Gets the variant key for a specific A/B test experiment.
+ *
+ * @param experimentId - The experiment ID.
+ * @param options - Options for evaluating the experiment.
+ * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
+ *
+ * @example
+ * ```typescript
+ * const variant = await getExperiment('checkout-redesign')
+ *
+ * if (variant === 'new-checkout') {
+ * // Show new checkout flow
+ * } else {
+ * // Show control (original) checkout
+ * }
+ * ```
+ */
+ async getExperiment(
+ experimentId: string,
+ options?: ExperimentOptions,
+ defaultVariant: string | null = null,
+ ): Promise<string | null> {
+ const experiments = await this.getExperiments(options)
+ return experiments[experimentId] ?? defaultVariant
+ }
+
+ /**
+ * Clears the cached experiments (alias for clearFeatureFlagsCache since they share the same cache).
+ */
+ clearExperimentsCache(): void {
+ this.cachedData = null
}
/**
diff --git a/src/index.ts b/src/index.ts
index e68c49990..b45f0b93f 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -10,6 +10,7 @@ import {
IErrorEventPayload,
IPageViewPayload,
FeatureFlagsOptions,
+ ExperimentOptions,
} from './Lib.js'
export let LIB_INSTANCE: Lib | null = null
@@ -187,6 +188,81 @@ export function clearFeatureFlagsCache(): void {
LIB_INSTANCE.clearFeatureFlagsCache()
}
+/**
+ * Fetches all A/B test experiments for the project.
+ * Results are cached for 5 minutes by default (shared cache with feature flags).
+ *
+ * @param options - Options for evaluating experiments.
+ * @param forceRefresh - If true, bypasses the cache and fetches fresh data.
+ * @returns A promise that resolves to a record of experiment IDs to variant keys.
+ *
+ * @example
+ * ```typescript
+ * const experiments = await getExperiments()
+ * // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
+ *
+ * // Use the assigned variant
+ * const checkoutVariant = experiments['checkout-experiment-id']
+ * if (checkoutVariant === 'new-checkout') {
+ * showNewCheckout()
+ * } else {
+ * showOriginalCheckout()
+ * }
+ * ```
+ */
+export async function getExperiments(
+ options?: ExperimentOptions,
+ forceRefresh?: boolean,
+): Promise<Record<string, string>> {
+ if (!LIB_INSTANCE) return {}
+
+ return LIB_INSTANCE.getExperiments(options, forceRefresh)
+}
+
+/**
+ * Gets the variant key for a specific A/B test experiment.
+ *
+ * @param experimentId - The experiment ID.
+ * @param options - Options for evaluating the experiment.
+ * @param defaultVariant - Default variant key to return if the experiment is not found. Defaults to null.
+ * @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
+ *
+ * @example
+ * ```typescript
+ * const variant = await getExperiment('checkout-redesign-experiment-id')
+ *
+ * if (variant === 'new-checkout') {
+ * // Show new checkout flow
+ * showNewCheckout()
+ * } else if (variant === 'control') {
+ * // Show original checkout (control group)
+ * showOriginalCheckout()
+ * } else {
+ * // Experiment not running or user not included
+ * showOriginalCheckout()
+ * }
+ * ```
+ */
+export async function getExperiment(
+ experimentId: string,
+ options?: ExperimentOptions,
+ defaultVariant: string | null = null,
+): Promise<string | null> {
+ if (!LIB_INSTANCE) return defaultVariant
+
+ return LIB_INSTANCE.getExperiment(experimentId, options, defaultVariant)
+}
+
+/**
+ * Clears the cached experiments, forcing a fresh fetch on the next call.
+ * This is an alias for clearFeatureFlagsCache since experiments and flags share the same cache.
+ */
+export function clearExperimentsCache(): void {
+ if (!LIB_INSTANCE) return
+
+ LIB_INSTANCE.clearExperimentsCache()
+}
+
export {
LibOptions,
TrackEventOptions,
@@ -197,4 +273,5 @@ export {
IErrorEventPayload,
IPageViewPayload,
FeatureFlagsOptions,
+ ExperimentOptions,
}
diff --git a/tests/experiments.test.ts b/tests/experiments.test.ts
new file mode 100644
index 000000000..f2d278e99
--- /dev/null
+++ b/tests/experiments.test.ts
@@ -0,0 +1,330 @@
+import { init, getExperiment, getExperiments, clearExperimentsCache } from '../src/index'
+import { Lib } from '../src/Lib'
+
+// Mock fetch globally
+const mockFetch = jest.fn()
+global.fetch = mockFetch
+
+describe('A/B Testing Experiments', () => {
+ const PROJECT_ID = 'test-project-id'
+ let libInstance: Lib
+
+ beforeEach(() => {
+ jest.clearAllMocks()
+ jest.resetModules()
+
+ // Reset fetch mock
+ mockFetch.mockReset()
+
+ Object.defineProperty(window, 'location', {
+ value: {
+ hostname: 'example.com',
+ pathname: '/test-page',
+ hash: '',
+ search: '',
+ },
+ writable: true,
+ })
+ })
+
+ describe('getExperiments', () => {
+ beforeEach(async () => {
+ jest.resetModules()
+ const { init: freshInit } = await import('../src/index')
+ libInstance = freshInit(PROJECT_ID, { devMode: true }) as Lib
+ })
+
+ test('should return experiments from API response', async () => {
+ // Arrange
+ mockFetch.mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: { 'feature-flag-1': true },
+ experiments: {
+ 'exp-checkout': 'variant-b',
+ 'exp-pricing': 'control',
+ },
+ }),
+ })
+
+ // Act
+ const { getExperiments: freshGetExperiments } = await import('../src/index')
+ const experiments = await freshGetExperiments()
+
+ // Assert
+ expect(experiments).toEqual({
+ 'exp-checkout': 'variant-b',
+ 'exp-pricing': 'control',
+ })
+ })
+
+ test('should return empty object when no experiments in response', async () => {
+ // Arrange
+ mockFetch.mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: { 'feature-flag-1': true },
+ }),
+ })
+
+ // Act
+ const { getExperiments: freshGetExperiments } = await import('../src/index')
+ const experiments = await freshGetExperiments()
+
+ // Assert
+ expect(experiments).toEqual({})
+ })
+
+ test('should use cached experiments on subsequent calls', async () => {
+ // Arrange
+ mockFetch.mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: { 'exp-1': 'variant-a' },
+ }),
+ })
+
+ // Act
+ const { getExperiments: freshGetExperiments } = await import('../src/index')
+ await freshGetExperiments()
+ await freshGetExperiments()
+
+ // Assert - fetch should only be called once
+ expect(mockFetch).toHaveBeenCalledTimes(1)
+ })
+
+ test('should bypass cache when forceRefresh is true', async () => {
+ // Arrange
+ mockFetch
+ .mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: { 'exp-1': 'variant-a' },
+ }),
+ })
+ .mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: { 'exp-1': 'variant-b' },
+ }),
+ })
+
+ // Act
+ const { getExperiments: freshGetExperiments } = await import('../src/index')
+ const first = await freshGetExperiments()
+ const second = await freshGetExperiments(undefined, true)
+
+ // Assert
+ expect(mockFetch).toHaveBeenCalledTimes(2)
+ expect(first).toEqual({ 'exp-1': 'variant-a' })
+ expect(second).toEqual({ 'exp-1': 'variant-b' })
+ })
+ })
+
+ describe('getExperiment', () => {
+ beforeEach(async () => {
+ jest.resetModules()
+ const { init: freshInit } = await import('../src/index')
+ libInstance = freshInit(PROJECT_ID, { devMode: true }) as Lib
+ })
+
+ test('should return specific experiment variant', async () => {
+ // Arrange
+ mockFetch.mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: {
+ 'exp-checkout': 'new-checkout',
+ 'exp-pricing': 'control',
+ },
+ }),
+ })
+
+ // Act
+ const { getExperiment: freshGetExperiment } = await import('../src/index')
+ const variant = await freshGetExperiment('exp-checkout')
+
+ // Assert
+ expect(variant).toBe('new-checkout')
+ })
+
+ test('should return defaultVariant when experiment not found', async () => {
+ // Arrange
+ mockFetch.mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: {},
+ }),
+ })
+
+ // Act
+ const { getExperiment: freshGetExperiment } = await import('../src/index')
+ const variant = await freshGetExperiment('non-existent', undefined, 'fallback')
+
+ // Assert
+ expect(variant).toBe('fallback')
+ })
+
+ test('should return null when experiment not found and no default provided', async () => {
+ // Arrange
+ mockFetch.mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: {},
+ }),
+ })
+
+ // Act
+ const { getExperiment: freshGetExperiment } = await import('../src/index')
+ const variant = await freshGetExperiment('non-existent')
+
+ // Assert
+ expect(variant).toBeNull()
+ })
+ })
+
+ describe('clearExperimentsCache', () => {
+ test('should clear cache and fetch fresh data on next call', async () => {
+ jest.resetModules()
+ const {
+ init: freshInit,
+ getExperiments: freshGetExperiments,
+ clearExperimentsCache: freshClearCache,
+ } = await import('../src/index')
+ freshInit(PROJECT_ID, { devMode: true })
+
+ // Arrange
+ mockFetch
+ .mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: { 'exp-1': 'variant-a' },
+ }),
+ })
+ .mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: { 'exp-1': 'variant-b' },
+ }),
+ })
+
+ // Act
+ await freshGetExperiments()
+ freshClearCache()
+ const newExperiments = await freshGetExperiments()
+
+ // Assert
+ expect(mockFetch).toHaveBeenCalledTimes(2)
+ expect(newExperiments).toEqual({ 'exp-1': 'variant-b' })
+ })
+ })
+
+ describe('profileId handling', () => {
+ test('should include profileId in request when provided in options', async () => {
+ jest.resetModules()
+ const { init: freshInit, getExperiments: freshGetExperiments } = await import('../src/index')
+ freshInit(PROJECT_ID, { devMode: true })
+
+ mockFetch.mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: {},
+ }),
+ })
+
+ // Act
+ await freshGetExperiments({ profileId: 'user-123' })
+
+ // Assert
+ expect(mockFetch).toHaveBeenCalledWith(
+ expect.any(String),
+ expect.objectContaining({
+ body: JSON.stringify({
+ pid: PROJECT_ID,
+ profileId: 'user-123',
+ }),
+ }),
+ )
+ })
+
+ test('should use global profileId when not provided in options', async () => {
+ jest.resetModules()
+ const { init: freshInit, getExperiments: freshGetExperiments } = await import('../src/index')
+ freshInit(PROJECT_ID, { devMode: true, profileId: 'global-user' })
+
+ mockFetch.mockResolvedValueOnce({
+ ok: true,
+ json: async () => ({
+ flags: {},
+ experiments: {},
+ }),
+ })
+
+ // Act
+ await freshGetExperiments()
+
+ // Assert
+ expect(mockFetch).toHaveBeenCalledWith(
+ expect.any(String),
+ expect.objectContaining({
+ body: JSON.stringify({
+ pid: PROJECT_ID,
+ profileId: 'global-user',
+ }),
+ }),
+ )
+ })
+ })
+
+ describe('error handling', () => {
+ test('should return empty object when fetch fails', async () => {
+ jest.resetModules()
+ const { init: freshInit, getExperiments: freshGetExperiments } = await import('../src/index')
+ freshInit(PROJECT_ID, { devMode: true })
+
+ // Arrange
+ mockFetch.mockRejectedValueOnce(new Error('Network error'))
+
+ // Suppress console.warn for this test
+ const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+
+ // Act
+ const experiments = await freshGetExperiments()
+
+ // Assert
+ expect(experiments).toEqual({})
+ consoleSpy.mockRestore()
+ })
+
+ test('should return empty object when response is not ok', async () => {
+ jest.resetModules()
+ const { init: freshInit, getExperiments: freshGetExperiments } = await import('../src/index')
+ freshInit(PROJECT_ID, { devMode: true })
+
+ // Arrange
+ mockFetch.mockResolvedValueOnce({
+ ok: false,
+ status: 500,
+ })
+
+ // Suppress console.warn for this test
+ const consoleSpy = jest.spyOn(console, 'warn').mockImplementation()
+
+ // Act
+ const experiments = await freshGetExperiments()
+
+ // Assert
+ expect(experiments).toEqual({})
+ consoleSpy.mockRestore()
+ })
+ })
+})