Desig Documentation

Welcome to the Desig developer documentation. Everything you need to integrate, configure, and extend the Desig A/B testing platform.

📅 Last updated May 2026 ⏱ 5 min read 📦 API v3.2

What is Desig?

Desig is a design testing and A/B optimization platform that helps product and marketing teams discover which design variations drive the highest conversions. It provides a visual editor, a statistical engine, real-time dashboards, and a full REST API.

Platform Architecture

Key Capabilities

Visual Editor — point-and-click variation builder, no code required for standard changes
Targeting Engine — audience segmentation by device, geography, behavior, custom attributes
Statistics Engine — Bayesian and frequentist testing; configurable significance thresholds
REST API v3 — full programmatic control over experiments, events, and results
AI Hypothesis Generator — ML-driven suggestions based on heatmap and session data
Real-Time Dashboard — live metrics with confidence intervals updated every 60 seconds

Note: All API calls must include your workspace API key. See Authentication for details.

Quick Start Guide

Get your first A/B test running in under 10 minutes by installing the Desig snippet and creating an experiment via the dashboard or API.

⏱ 10 min📦 SDK v3

Step 1 — Install the Snippet

Add the Desig snippet to the <head> of your HTML, before any other scripts. Replace YOUR_WORKSPACE_ID with your actual workspace ID from the dashboard settings.

HTML


<script>
  window.desig=window.desig||[];
  window.desig.push(['init', {
    workspaceId: 'YOUR_WORKSPACE_ID',
    autoActivate: true
  }]);
</script>
<script src="https://cdn.desig.io/sdk/v3/desig.min.js"
        async></script>

Step 2 — Or Install via npm

Shell

npm install @desig/sdk

JavaScript

import { Desig } from '@desig/sdk';

const client = new Desig({
  workspaceId: 'YOUR_WORKSPACE_ID'
});

await client.initialize();

Step 3 — Activate an Experiment

JavaScript

const variation = await client.activate('hero-cta-test', {
  userId: user.id,
  attributes: {
    plan: 'free',
    country: 'JP',
    device: 'desktop'
  }
});

if (variation.key === 'variation_b') {
  // Show the new CTA design
  document.querySelector('.hero-cta').classList.add('variant-b');
}

Step 4 — Track a Conversion

JavaScript

// Track when user completes a goal action
await client.track('purchase_completed', {
  userId: user.id,
  value: 89.99,
  currency: 'USD'
});

You're done! Results will start appearing in your dashboard within minutes of your first tracked events. Desig requires a minimum of 100 conversions per variation before showing significance estimates.

Next Steps

1

Configure Targeting

Set up audience segments to run targeted experiments for specific user groups.

2

Add Custom Metrics

Define revenue, engagement, and retention metrics beyond the default conversion tracking.

3

Connect Integrations

Sync experiment data with your analytics stack — GA4, Segment, Amplitude, and more.

Authentication

Desig uses API keys for server-side requests and workspace tokens for client-side SDK initialization.

API Keys

All REST API requests must include your API key in the Authorization header as a Bearer token. API keys are scoped to a workspace and can have read or read_write permissions.

HTTP Header

Authorization: Bearer dsig_sk_live_xxxxxxxxxxxxxxxxxxxx

⚠ Keep keys secret. Never expose your secret API key in client-side code, version control, or public repositories. Use environment variables and server-side requests instead.

Key Types

Key Type	Prefix	Usage
Secret Key	dsig_sk_live_	Server-side REST API calls. Full read/write access.
Publishable Key	dsig_pk_live_	Client-side SDK initialization. Read-only experiment config.
Test Key	dsig_sk_test_	Development environment. Events do not affect production data.

Generating an API Key

Go to Settings → API Keys in your Desig dashboard
Click Generate New Key
Select the permission scope (read or read_write)
Copy the key immediately — it will only be shown once

Experiments API

Create, manage, and retrieve experiments programmatically via the REST API.

📦 Base URL: https://api.desig.io/v3

List Experiments

GET/experiments

Returns a paginated list of all experiments in the workspace.

Parameter	Type	Description
statusoptional	string	Filter by status: draft, running, paused, completed
limitoptional	integer	Number of results per page. Default: 20, max: 100
pageoptional	integer	Page number, 1-indexed. Default: 1

Create Experiment

POST/experiments

Creates a new experiment with the specified configuration. Returns the created experiment object.

JSON Request Body

{
  "name": "Hero CTA Button Test",
  "key": "hero-cta-test",
  "type": "ab",
  "hypothesis": "A green button will increase CTA clicks by 15%",
  "primaryMetric": "cta_click",
  "trafficAllocation": 0.5,
  "variations": [
    { "key": "control", "weight": 0.5 },
    { "key": "variation_b", "weight": 0.5 }
  ]
}

Get Experiment Results

GET/experiments/{id}/results

Returns statistical results for all variations in the experiment.

JSON Response

{
  "experimentId": "exp_01HXQ2B8KN",
  "status": "running",
  "variations": [
    {
      "key": "control",
      "visitors": 4821,
      "conversions": 289,
      "conversionRate": 0.0599,
      "isControl": true
    },
    {
      "key": "variation_b",
      "visitors": 4836,
      "conversions": 331,
      "conversionRate": 0.0684,
      "uplift": 0.142,
      "significance": 0.94,
      "isWinner": false
    }
  ]
}

Statistics Engine

Desig supports both frequentist and Bayesian statistical frameworks. Understand how each works and when to choose one.

Frequentist Testing

The frequentist approach uses p-values and confidence intervals. A test is declared significant when the p-value falls below your configured threshold (default: 0.05), corresponding to a 95% confidence level.

Default significance level: α = 0.05 (configurable per workspace)
Statistical power: 80% minimum (1 − β = 0.80)
Correction for multiple comparisons: Bonferroni correction applied when > 2 variations
Minimum detectable effect: Set per experiment; defaults to 5% relative lift

Bayesian Testing

Bayesian testing calculates the probability that each variation is the best performer. Results are expressed as "Probability of Being Best" (PoBB) and "Expected Loss" if you choose the wrong winner.

Prior: Beta(1,1) uniform prior by default; configurable from historical data
Decision threshold: PoBB ≥ 95% by default
Expected Loss threshold: 0.1% relative lift (configurable)

Which to choose? Use Frequentist when you need to report externally on statistical significance. Use Bayesian for internal decisions where you want to stop early and minimize regret. Bayesian is Desig's default for new workspaces.

Sample Size Requirements

Formula

// Required sample size per variation (two-tailed)
n = (Z_α/2 + Z_β)² × (p1(1-p1) + p2(1-p2)) / (p2 - p1)²

// Where:
// p1 = baseline conversion rate
// p2 = expected conversion rate (p1 × (1 + MDE))
// Z_α/2 = 1.96 for 95% confidence
// Z_β  = 0.84 for 80% power

Changelog

A record of all notable changes, improvements, and fixes to the Desig platform and API.

2026 Releases

v3.2.0 — May 2026

Released May 1, 2026

New AI Hypothesis Generator with heatmap analysis
New Results API endpoint with variation-level breakdown
Improved Statistical engine: sequential testing now supported
Improved Dashboard load time reduced by 40%
Fixed Edge case where flicker occurred on SPA route changes

v3.1.0 — March 2026

Released March 14, 2026

New Shopify native integration (beta)
New Bandit testing algorithm (epsilon-greedy)
Improved Segment syncing now supports nested traits
Fixed GA4 event deduplication issue with SPA apps

v3.0.0 — January 2026

Released January 8, 2026

New API v3 with unified experiment model
New Bayesian engine as default (replaces v2 frequentist default)
Improved SDK bundle size reduced by 60% (8.2 KB gzipped)
Deprecated API v2 — end-of-life December 2026

SDKs & Libraries

Official Desig SDKs are available for JavaScript, Python, Ruby, Go, and PHP. All SDKs are open source on GitHub.

Language	Package	Version
JavaScript / TS	@desig/sdk	3.2.0
Python	desig-python	3.1.2
Ruby	desig-ruby	3.0.5
Go	github.com/desig/go-sdk	3.2.0
PHP	desig/php-sdk	3.1.0

Experiments

An experiment is a controlled test comparing two or more design or content variations. Learn how Desig models experiments and how to configure them.

Each experiment contains a control (baseline) and one or more variations. Traffic is split between them according to configured weights. Desig tracks conversions for each assigned user and computes statistical results continuously.

Tip: Keep experiments focused. Test one hypothesis at a time for clean, interpretable results.

Variations

Variations define what is different about your test experience — from a changed headline to a fully redesigned page layout.

Each variation has a unique key used in the SDK's activate() response. Use the key to conditionally render the correct experience in your code.

Segments & Targeting

Target experiments to specific audiences using built-in attributes or custom user properties.

Targeting rules can combine attributes with AND/OR logic. Built-in attributes include: device type, browser, country, language, new vs. returning user, UTM parameters, and custom session traits you pass via activate().

Metrics

Define the conversion goals and secondary metrics that Desig tracks and analyzes for each experiment.

Each experiment has one primary metric (used for significance decisions) and up to 10 secondary metrics (monitored but not used for stopping decisions).

Events API

Track custom conversion events and user actions server-side via the Events API.

POST /events

{
  "userId": "usr_abc123",
  "event": "purchase_completed",
  "value": 89.99,
  "timestamp": "2026-05-07T10:30:00Z"
}

Webhooks

Subscribe to real-time events from Desig — experiment started, winner declared, and more.

Configure webhook endpoints in your dashboard under Settings → Webhooks. Desig will POST a JSON payload to your endpoint within 500ms of the triggering event.

Google Analytics 4

Sync Desig experiment assignments to GA4 as custom dimensions for cross-platform analysis.

Once connected, Desig sends a desig_experiment custom event to GA4 every time a user is bucketed into a variation. Use this to create exploration reports in GA4.

Segment

Send Desig experiment data to Segment and forward it to any downstream destination in your data stack.

Enable the Segment integration in Integrations → Segment. Desig fires a Experiment Viewed track call with experiment and variation properties for every assignment.

Shopify Integration Beta

Native Shopify integration — install the Desig app from the Shopify App Store to start testing themes, product pages, and checkout flows without touching code.

Beta: The Shopify integration is currently in closed beta. Contact us to join the early access program.

AI Hypothesis Generator

Desig's AI engine analyzes your site's heatmaps, scroll data, and session recordings to automatically suggest high-confidence test hypotheses.

The AI model is trained on 2M+ experiment results and identifies patterns correlated with high-lift wins. Each suggestion includes a confidence score, estimated impact, and suggested variation mockup.

New in v3.2: AI hypotheses now include before/after SVG wireframe previews directly in the dashboard.