SDKs

Official SDKs for integrating Experiment Plus into your applications.

Installation

npm

npm install @experiment-plus/sdk

pnpm

pnpm add @experiment-plus/sdk

yarn

yarn add @experiment-plus/sdk

pip

pip install experiment-plus

Quick Start

TypeScript

import { ExperimentPlus } from '@experiment-plus/sdk'

const client = new ExperimentPlus({
  apiKey: process.env.EXPERIMENT_PLUS_API_KEY!,
  localEvaluation: true,
})

// Identify the user
client.identify('user-123', { plan: 'pro', country: 'US' })

// Check a feature flag
const variant = await client.getFeatureFlag('new-checkout')

if (variant === 'variant-a') {
  // Show new checkout
} else {
  // Show control
}

// Track conversion
client.track('checkout_completed', { value: 99.99 })

// Cleanup on shutdown
await client.shutdown()

Python (sync)

from experiment_plus import ExperimentPlus

client = ExperimentPlus(
    api_key="sk_live_...",
    local_evaluation=True,
)

# Identify the user
client.identify("user-123", {"plan": "pro", "country": "US"})

# Check a feature flag
variant = client.get_feature_flag("new-checkout")

if variant == "variant-a":
    # Show new checkout
    pass
else:
    # Show control
    pass

# Track conversion
client.track("checkout_completed", value=99.99)

# Cleanup
client.shutdown()

Python (async)

from experiment_plus import ExperimentPlus

async def main():
    client = ExperimentPlus(
        api_key="sk_live_...",
        local_evaluation=True,
    )

    client.identify("user-123", {"plan": "pro"})

    variant = await client.get_feature_flag_async("new-checkout")

    await client.shutdown_async()

Configuration

Option	Type	Default	Description
apiKey	string	Required	Your API key (pk_* for client, sk_* for server)
baseUrl	string	https://api.experiment-plus.io	API base URL
localEvaluation	boolean	false	Enable local flag evaluation
cache.ttl	number	60000	Cache TTL in milliseconds
batching.flushInterval	number	5000	Event flush interval in ms
batching.maxBatchSize	number	100	Max events per batch
timeout	number	30000	Request timeout in ms
retries	number	3	Max retries on failure

Core Methods

identify(distinctId, properties?)

Set the user context for all subsequent evaluations.

client.identify('user-123', {
  plan: 'pro',
  country: 'US',
  signupDate: '2024-01-15'
})

getFeatureFlag(flagKey, context?)

Evaluate a feature flag and get the variant key.

const variant = await client.getFeatureFlag('new-checkout')
// Returns: 'control' | 'variant-a' | 'variant-b' | ...

isFeatureEnabled(flagKey, context?)

Check if a boolean flag is enabled.

if (await client.isFeatureEnabled('dark-mode')) {
  enableDarkMode()
}

getFeatureFlagWithPayload(flagKey, context?)

Get the variant with its associated payload data.

const result = await client.getFeatureFlagWithPayload('pricing-test')
// result.variant = 'variant-a'
// result.payload = { price: 9.99, currency: 'USD' }

track(eventName, options?)

Track an event (batched automatically).

client.track('purchase', {
  value: 49.99,
  properties: { productId: 'sku-123' }
})

flush()

Manually flush queued events.

await client.flush()

shutdown()

Gracefully shutdown the client, flushing all pending events.

await client.shutdown()

Local Evaluation

When localEvaluation: true is set, flags are evaluated client-side using cached configurations. This provides:

• Lower latency: No network round-trip for each evaluation
• Offline support: Works when the network is unavailable
• Consistent bucketing: Uses MurmurHash3 for deterministic user assignment

The SDK automatically fetches and caches flag configurations, refreshing them based on the cache.ttl setting.

const client = new ExperimentPlus({
  apiKey: 'pk_live_...',
  localEvaluation: true,
  cache: { ttl: 30_000 }, // Refresh every 30s
})

Error Handling

import { ExperimentPlus, RateLimitError, AuthenticationError } from '@experiment-plus/sdk'

try {
  const variant = await client.getFeatureFlag('my-flag')
} catch (error) {
  if (error instanceof RateLimitError) {
    // Back off and retry
  } else if (error instanceof AuthenticationError) {
    // Check API key
  }
}

Context Manager (Python)

The Python SDK supports context managers for automatic cleanup:

with ExperimentPlus(api_key="sk_live_...") as client:
    client.identify("user-123")
    variant = client.get_feature_flag("my-flag")
# Automatically calls shutdown()

# Async version
async with ExperimentPlus(api_key="sk_live_...") as client:
    variant = await client.get_feature_flag_async("my-flag")

Next Steps

• Feature Flags Guide
• A/B Testing Guide
• API Reference