Complete Documentation

Fields:

• Experiment Name: Internal identifier (e.g., "Homepage Hero Test")
• Description: What you're testing and why
• Hypothesis: Expected outcome (e.g., "Changing CTA color to green will increase conversions by 15%")
• Activation Delay: Time before revealing experiment (prevents flicker)

Activation Delay Options:

• Immediate (0ms): Show changes instantly
• Fast (100ms): Brief wait for scripts
• Standard (500ms): Allow dependencies to load
• Safe (1000ms): Ensure all assets loaded
• Custom: Enter any millisecond value

Why Activation Delay Matters:

If your site uses JavaScript that modifies the DOM after page load (e.g., React, Vue, Angular), setting an activation delay ensures Segmently's changes are applied AFTER your framework initializes, preventing conflicts or reverts.

Best Practices:

• Use descriptive names (searchable, clear purpose)
• Write specific hypotheses (measurable, testable)
• Start with 100ms delay for most sites
• Increase to 500ms if using React/Vue/Angular

What are Variants?

Variants are different versions of your page shown to visitors. Every experiment has a Control (original) and one or more Variations (your changes).

Control Variant:

• Always exists (cannot be deleted)
• Represents the original page (baseline)
• Can be customized like any other variant!
• ⚠️ Control does NOT mean "unchanged site" - it's just another variant

Creating Variations:

• Click "+ Add Variation"
• Enter variation name (e.g., "Green Button", "Shorter Form")
• Set traffic weight (percentage of visitors)
• Add changes using Visual Editor or Custom Code

Traffic Weights:

• Must sum to 100% across all variants
• 50/50 split: Control 50%, Variation A 50%
• 33/33/34 split: 3 variants equally distributed
• Custom: 25/75, 10/45/45, etc.

Change Types:

• Hide Element: Remove from DOM
• Replace Text: Change wording
• Custom CSS: Style modifications
• Custom JavaScript: Advanced DOM manipulation

Visual Editor Integration:

• Click "Visual Editor" button
• Website loads in iframe
• Hover over elements (blue highlight)
• Click to select element
• CSS selector auto-generated
• Apply changes and save

Selected Element Tiles:

• Each tile prefers the first direct text node of the selected element
• If none exists, it falls back to the first immediate child element text
• If still empty, it uses the first descendant element's direct text before final fallback
• Container-wide concatenated text is avoided for cleaner labels
• This improves identification for nested structures and non-visible elements

Nested Element Reliability:

• When parent and child are both selected, parent changes apply first
• Child element changes apply after parent to prevent unintended overrides
• Saved element changes reapply when reopening the modal after elements are ready
• HTML updates prioritize exact selector matches before using safe fallback
• Selected elements default to visible unless you explicitly choose hidden or removed
• Selected elements with empty HTML (not edited) are ignored to prevent child wipe
• Pending selected-element apply cycles are preserved across snippet reinitialization
• Preview-link mode applies selected elements with the same retry/depth safeguards
• Clearing custom CSS removes previously applied inline properties for that selector
• Localhost preview bypasses session cache to always load fresh experiment changes
• If your page is highly dynamic, keep Activation Delay at 100-500ms for best consistency

On-Site Test Panel:

• When previewing an experiment, a floating Test Panel appears in the bottom-right corner of your page
• Shows the active experiment name and the currently selected segment
• Use the segment dropdown to switch to any other segment without editing the URL manually
• Click View Original to remove the preview parameter and see the unmodified site
• Click Dashboard to open the experiment in a new tab
• Minimize the panel with the ▼ button; its state is remembered across page navigations in the same session
• The panel is CSS-isolated and cannot conflict with your site's styles

URL Targeting:

• Exact: https://example.com/pricing (only this URL)
• Contains: /product/ (anywhere in URL)
• Starts With: https://example.com/blog/ (all blog posts)
• Ends With: /checkout (any checkout page)
• Regex: ^https://example\.com/product/[0-9]+$ (advanced)

Multiple URL Rules:

• Add multiple rules (OR logic)
• Experiment runs if ANY rule matches
• Example: Target /checkout OR /cart

Device Targeting:

• All Devices: Desktop, mobile, tablet (default)
• Desktop Only: Screen width ≥ 1024px
• Mobile Only: Screen width < 768px
• Tablet Only: 768px ≤ width < 1024px

Location Targeting:

• Target visitors by country using ISO 3166-1 alpha-2 codes (e.g. US, GB, DE)
• Only visitors from selected countries are bucketed into the experiment
• Leave the list empty to include all countries (default)
• Visitors whose country cannot be detected are always allowed through

Traffic Percentage:

• Control what % of visitors see experiment
• 100%: All matching visitors participate
• 50%: Only half of visitors see experiment
• 10%: Run on small sample before full rollout
• Useful for testing impact before wide deployment

How Targeting Works:

1. Visitor lands on your website
2. Snippet checks current URL against rules
3. If no match, experiment is skipped
4. If match, check device type
5. If device matches, check visitor country against geo targeting rules
6. If country matches (or no geo rules set), check traffic percentage
7. Assign to variant using deterministic hashing
8. Apply changes and track events

Visitor Type

Restrict the experiment to a specific audience:

• All Visitors: everyone who lands on a matching page
• New Visitors: no prior visit cookie present, first session only
• Returning Visitors: prior visit cookie present, visited before

Behavioral Triggers (Professional+)

Behavioral triggers delay experiment activation until the visitor performs a specific action mid-session. Because changes apply to an already-visible page, anti-flicker CSS is intentionally bypassed for behavioral experiments.

Each trigger fires at most once per page visit. Multiple triggers can be combined; the first async trigger to fire activates the experiment.

What are Goals?

Goals define what "success" means for your experiment. Most experiments track conversions (purchases, signups, clicks), but you can also track custom events and multi-page funnels.

Primary Conversion Goal: How It Connects to Analytics

💡 The Primary Conversion Goal is the direct source of the Conversions tile and Conversion Rate shown on your analytics dashboard. When a visitor triggers your goal (clicks a button, submits a form, reaches a thank-you page, or fires a custom JS event), the snippet sends a conversion event to the API, which is exactly what the analytics tile counts. There is no separate system; the goal is the conversion counter.

• The main metric you're optimizing for
• Used for winner determination in analytics
• Without a Primary Goal set, conversions are only recorded if you manually call window.Segmently.track('conversion') in your own code
• Secondary goals also fire as conversion events (with a different goal_name in metadata) and contribute to the same count

Goal Types:

• Click Element: Tracks clicks on a CSS selector (e.g. #buy-button)
• Form Submit: Tracks when a matching form is submitted
• Page View: Tracks when a visitor reaches a specific URL (e.g. /thank-you)
• Custom Event: Tracks a named JS event fired via window.Segmently.track()

Page View Goal Setup:

1. Choose "Page View" as goal type
2. Enter conversion URL: /thank-you
3. Snippet fires a conversion event whenever
   a bucketed visitor lands on that URL

Custom Event Goal:

// Fire from your own JavaScript
window.Segmently.track('purchase_complete', {
  revenue: 99.99 // Use the 'revenue' key to pipe to Dashboard Analytics total
});
// The event name must match what you entered
// in the "Event Name" field of the goal config

Best Practices:

• Set a Primary Goal before launching; without one, the Conversions tile will always show 0
• Choose ONE clear primary goal per experiment (e.g. purchase, signup, not both)
• Make sure the goal is binary (yes/no per visitor per session)
• Test goal firing in the browser console before launching

What are Funnel Goals?

Funnel goals let you define an ordered sequence of pages a visitor must visit, in order, to count as a conversion. Unlike a single-page goal, funnels reveal where visitors drop off across a multi-step flow (e.g., landing page → product page → checkout → confirmation).

Requires Professional plan or higher. The section is visible in the experiment wizard for all plans, but funnel evaluation is only active for Professional, Business, and Enterprise accounts.

Adding Funnel Steps:

1. Open the Metrics tab in the experiment wizard
2. Scroll to the Multi-Page Funnel Goals section
3. Click + Add Step for each page in the flow
4. Fill in the three fields for each step (see below)
5. Steps are evaluated in order, top to bottom

Step Fields:

• Step Label: A human-readable name shown in analytics (e.g., "Landing Page", "Add to Cart", "Checkout", "Purchase Confirmed")
• URL (contains): The URL path pattern that defines this step (see URL matching rules below)
• Event Name (optional): A custom event name that can also satisfy this step (e.g., add_to_cart). Either the URL match or the event fires; whichever comes first counts.

URL Field: Matching Rules

• Empty value or / → matches the root domain homepage only (i.e., pathname === "/"). Both are treated identically, so leaving the field blank and entering / produce the same result.
• Any other value (e.g., /checkout, /product) → matches any URL whose pathname contains that string.
• Matching is case-sensitive and path-only (the hostname is ignored).

Example: E-commerce Funnel

Step 1: Landing Page
  Label: Landing
  URL: /            ← matches homepage only
  Event: (empty)

Step 2: Product Page
  Label: Product
  URL: /product     ← matches /product, /products/123, etc.
  Event: (empty)

Step 3: Added to Cart
  Label: Add to Cart
  URL: /cart
  Event: add_to_cart  ← fires if JS calls Segmently.track('add_to_cart')

Step 4: Checkout
  Label: Checkout
  URL: /checkout
  Event: (empty)

Step 5: Purchase Confirmed
  Label: Confirmed
  URL: /thank-you
  Event: purchase

Triggering Funnel Events Manually:

For steps where a URL visit isn't enough (e.g., a single-page checkout), use the JS API to fire a step event:

// Fire a named event to satisfy a funnel step
window.Segmently.track('add_to_cart');

// With optional metadata (Use the 'revenue' key to automatically aggregate revenue in Analytics)
window.Segmently.track('conversion', { revenue: 99.99, currency: 'USD' });

How to Test Funnel Goals:

1. Create an experiment with funnel steps and set status to Draft
2. Open your site with the preview URL: yoursite.com?segmently_preview=your-slug:your-segment-id
3. Navigate through each page in order (e.g., visit homepage → /product → /checkout → /thank-you)
4. On pages that use event-based steps, open the browser console and run: window.Segmently.track('your_event_name');
5. After completing all steps, check Dashboard → Analytics for your experiment to see funnel completion data
6. To verify events are being recorded, check the network tab in DevTools for POST requests to /api/v1/events/track

Funnel Analytics (What You'll See):

• Per-variant completion rate at each step
• Drop-off percentage between consecutive steps
• Overall funnel completion rate (step 1 through final step)
• Comparison across Control and all Variants

Tips & Limitations:

• Steps must be completed in sequence; visiting step 3 before step 2 does not count
• A visitor who completes only steps 1 and 2 is counted as a drop-off at step 3
• The same visitor completing the funnel multiple times is deduplicated (counted once)
• Leave the URL blank (not /) when you want the step satisfied purely by a custom event
• For SPA sites where URLs don't change on navigation, rely entirely on event-based steps

Experiment Scheduling (Business+):

• Start Date: Set a future date/time to automatically activate the experiment
• End Date: Set a date/time after which the experiment automatically pauses
• Auto-pause at significance: Toggle to have the experiment pause itself once a variant reaches 95% statistical confidence (requires 30+ visitors per variant)
• Scheduling checks run every 60 seconds server-side; no manual intervention needed
• Useful for timed promotions, product launches, and campaigns across time zones
• You can schedule an experiment from the ellipsis menu on the site page: click the three-dot menu next to any draft experiment and choose Schedule

Cross-Domain Tracking:

• Keeps a visitor in their assigned variant when they navigate from one of your domains to another (e.g. a marketing site to a separate checkout domain)
• Requires the Segmently snippet to be installed on every domain you want to track across, all using the same site API key
• Enable it in the Advanced tab, then enter a comma-separated list of the domains you want to bridge (e.g. store.example.com, checkout.example.com)
• The snippet automatically appends ?_sgmt_vid=<visitor_id> to every outbound link pointing to your listed domains; a MutationObserver handles links added dynamically after page load (SPAs, lazy-loaded content)
• When the visitor lands on the second domain, that domain's snippet reads _sgmt_vid, adopts the visitor ID (matching the existing assignment record), then strips the parameter from the URL bar so it never appears in the address bar or gets bookmarked
• Both domains must be on the same Segmently project; the same API key is shared across all of them

Integrations (Business+):

• Slack Webhook: Enter a Slack Incoming Webhook URL to receive a notification when your experiment reaches statistical significance
• GA4 Measurement ID: Enter your GA4 Measurement ID (e.g., G-XXXXXXX); the snippet automatically calls gtag('event', 'experiment_impression') when a visitor is bucketed, syncing experiment and variant names into GA4
• Mixpanel Project Token: Enter your Mixpanel Project Token; the snippet calls mixpanel.track('$experiment_started') automatically (requires Mixpanel SDK already on page)
• Outbound Webhook URL: Enter any HTTPS endpoint; Segmently will POST a JSON payload for each configured experiment event (experiment.started, experiment.paused, significance.reached)
• GA4 and Mixpanel forwarding only fires if the respective library (window.gtag / window.mixpanel) is already loaded on the client page

Custom JavaScript:

// Example: Change button text dynamically
document.querySelector('.cta-button')
  .textContent = 'Start Free Trial';

// Example: Add click event listener
document.querySelector('.hero-cta')
  .addEventListener('click', () => {
    window.Segmently.trackConversion();
  });

Custom CSS:

.hero-section {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  padding: 80px 20px;
}

.cta-button {
  background-color: #10b981;
  color: white;
  font-weight: bold;
  border-radius: 8px;
}

Execution Order:

1. Anti-flicker CSS injected (hides page)
2. Experiment configuration fetched
3. Variant assigned to visitor
4. Integration events forwarded (GA4, Mixpanel)
5. Visual Editor changes applied
6. Custom CSS injected
7. Custom JavaScript executed
8. Wait for activation delay
9. Anti-flicker removed (page revealed)

Best Practices:

• Test code in browser console first
• Use querySelector carefully (may not exist yet)
• Add error handling for missing elements
• Keep code minimal (performance impact)
• Comment complex logic for future reference
• Use the built-in Prism syntax highlighting to quickly validate selectors, properties, and JavaScript tokens while editing

⚠️ Warning:

Custom code executes on every page view. Ensure it's efficient and doesn't break functionality. Always test in preview mode before launching!

The Integrations tab lets you forward experiment data to external analytics and notification tools. All integration settings are saved per-experiment inside the integrations field.

Slack Notifications (Professional+):

There are two levels of Slack integration: org-level (15 event types) and per-experiment override.

• Org-level (recommended): Configure a single Slack webhook and choose which of the 15 event types to receive; go to Organization → Features & Integrations. Covers experiment lifecycle, project events, member changes, and billing alerts.
• Per-experiment override: Paste a Slack Incoming Webhook URL here to send notifications for this experiment only. Fires on experiment.started, experiment.paused, experiment.archived, and significance.reached.
• The significance.reached event fires automatically (exactly once per experiment) when a variant's two-proportion z-test confidence first crosses 95%.
• Message includes experiment name, winning variant, confidence level, and a direct link to the results page.
• Create Incoming Webhooks at api.slack.com/apps → your app → Incoming Webhooks.

Google Analytics 4 (Business+):

• Enter your GA4 Measurement ID (format: G-XXXXXXXXXX)
• The Segmently snippet auto-fires gtag('event', 'experiment_impression', { experiment_name, variant_name }) when each visitor is bucketed
• Requires the GA4 global site tag (window.gtag) to already be present on your page
• Use BigQuery Export or GA4 Explore reports to cross-segment with experiment variants

Mixpanel (Business+):

• Enter your Mixpanel Project Token
• The snippet fires mixpanel.track('$experiment_started', { experimentName, variantName }) automatically
• Requires the Mixpanel SDK (window.mixpanel) to be loaded on your page before the Segmently snippet runs

Outbound Webhook (Business+):

• Enter any HTTPS endpoint URL
• Choose which events to subscribe to: experiment.started, experiment.paused, significance.reached
• Segmently POSTs a JSON payload with experiment ID, variant info, timestamp, and event type
• Useful for custom dashboards, CRM updates, or CI/CD pipeline triggers

All integrations require a Business plan or higher, except Slack which is available on Professional+. Integration config is stored in the integrations JSONB column on the experiment record.

Attribute targeting lets you define rules based on data your application already knows about the visitor. You push that data into Segmently once per page load using window.Segmently.setAttributes(), and then the snippet evaluates those attributes against your experiment rules before deciding whether to bucket the visitor.

Why attribute targeting matters for revenue:

• Only show a pricing experiment to visitors on a paid plan, never to trial users
• Run a checkout redesign exclusively for visitors whose cart value exceeds $100
• Test a loyalty offer for visitors who have logged in more than 5 times
• Segment enterprise visitors from SMB visitors using your own account data

How it works:

1. You call window.Segmently.setAttributes({plan: 'pro', loginCount: 8}) in your app code
2. The snippet stores these attributes in memory for the current page session
3. When evaluating experiments, the snippet checks all attribute rules against the stored values
4. If every rule passes (AND logic), the visitor is eligible for the experiment
5. If any rule fails, the visitor is skipped entirely: no assignment is made and the original site is shown

Key facts:

• Attribute rules are AND-gated: all rules must pass for the visitor to be bucketed
• Evaluation happens before the assignment API call, so excluded visitors never count against your traffic quota
• Attributes are evaluated in both standard and behavioral-trigger experiments
• Experiments without attribute rules are unaffected: the gate only runs when at least one rule is configured
• Available on: Professional and above

Each attribute rule consists of three fields: Key (the attribute name), Operator, and Value (not used for exists / not_exists).

All string comparisons are case-sensitive. Numeric operators (greater_than, less_than) parse both sides via parseFloat(). If either side is not a valid number, the rule fails (visitor excluded).

Feature flags (also called feature toggles) let you control which visitors see a new feature at runtime. You deploy the code with the flag off, then enable it for a percentage of visitors directly from the Segmently dashboard, no code push needed.

Feature flags vs A/B experiments:

• Flags: On/off toggle for code-level feature availability. No visual editor, no variant comparison. Best for gradual rollouts and kill switches.
• Experiments: Compare two or more versions of a page or element with statistical analysis. Best for measuring which design or copy performs better.

Plan requirement: Feature flags are available on Professional, Business, and Enterprise plans.

To create a flag:

1. Open your project in the Segmently dashboard
2. Click "Feature Flags" in the project navigation
3. Click "New Flag"
4. Enter a name and a unique flag key (e.g. new-checkout-ui)
5. Set the initial rollout percentage and status, then save

Flag states:

• Active: The flag is live. isEnabled() returns true for visitors within your rollout percentage.
• Inactive: The flag is off for everyone. isEnabled() always returns false.
• Archived: Permanently disabled. Use this when a flag is no longer needed.

Rollout percentage: Controls the fraction of visitors for whom the flag is enabled. Set to 100% to enable for all visitors, or start lower (e.g. 5%) for a gradual rollout.

Once the snippet is installed, you can evaluate flags using the JavaScript SDK. All flags for a project are fetched in a single request and cached for the page lifetime, so calling isEnabled() multiple times has no extra network cost.

Check a single flag:

const enabled = await window.Segmently.isEnabled('new-checkout-ui')

if (enabled) {
  // show new checkout flow
} else {
  // show original checkout
}

Get all flags at once:

const flags = await window.Segmently.getAllFlags()
// flags = { "new-checkout-ui": true, "dark-mode": false, ... }

if (flags['dark-mode']) {
  document.body.classList.add('dark')
}

Both methods are async and return a Promise. Make sure the Segmently snippet has loaded before calling them. If the snippet is in your <head>, it is available by the time your inline scripts run. For dynamically loaded scripts, wait for the segmently-snippet-ready postMessage event.

The kill switch is one of the most valuable properties of feature flags. If a new feature causes errors or unexpected behavior in production, you can disable it for all visitors immediately from the dashboard, no git commit or deployment needed.

To kill switch a flag:

1. Open the flag from your project's Flags page
2. Change the status from "Active" to "Inactive"
3. Click "Save Changes"

Within seconds, isEnabled() will return false for all visitors. The flag and its configuration are preserved so you can re-enable it when the issue is resolved.

Best practice: Wrap every significant new feature in a flag before shipping. The cost is minimal and the safety net is invaluable.

Experiment States:

• Draft: Being configured, not live yet
• Live: Running and tracking visitors
• Paused: Temporarily stopped (data preserved)
• Archived: Completed/ended (removed from active list)

Quick Actions:

• ▶️ Start: Launch draft experiments
• ⏸️ Pause: Temporarily stop tracking
• ▶️ Resume: Continue paused experiments
• 📦 Archive: Move to archived list
• ♻️ Reinstate: Restore archived experiments

View Options:

• Active experiments shown by default
• Archived experiments in collapsible section
• Count badge shows archived experiments (e.g., "3 Archived")

How It Works:

• Snippet injects CSS to hide page content immediately
• Fetches experiment configuration and variant assignment
• Applies changes (DOM manipulation, CSS injection)
• Waits for activation delay (0ms, 100ms, 500ms, 1s, or custom)
• Removes anti-flicker to reveal final result

Activation Delay Options:

• Immediate (0ms): Show changes instantly
• Fast (100ms): Brief wait for scripts to load
• Standard (500ms): Allow dependencies to initialize
• Safe (1000ms): Ensure all assets loaded
• Custom: Set your own timing

Failsafe:

• 5-second timeout always reveals content (prevents permanent hiding)
• Users assigned to variant ONLY see their variant (never original first)
• All segments can be customized (Control is NOT special)

Experiment Setup:

• Create unlimited variants with custom names
• Set traffic allocation (50/50, 33/33/34, custom weights)
• Control traffic percentage (run on 10%, 50%, 100%)

URL Targeting:

• Exact match: https://example.com/page
• Contains: /product/ anywhere in URL
• Starts with: https://example.com/blog/
• Ends with: .html or /checkout
• Regex: Advanced pattern matching

Device Targeting:

• Desktop only, mobile only, or tablet only
• All devices (default)

Geo / Country Targeting:

• Target by country using ISO 3166-1 alpha-2 codes (US, GB, DE, CA, etc.)
• Visitors from non-listed countries are excluded from the experiment
• Leave empty to allow all countries (default)

What is the Visual Editor?

The Visual Editor lets you select elements on your website by hovering and clicking - just like Optimizely. No CSS selector knowledge required! It uses the Segmently snippet already installed on your site.

How It Works (Technical):

1. Visual Editor opens your website in iframe
2. Snippet detects it's in iframe and sends "ready" message
3. Editor enables selection mode in snippet
4. Snippet adds hover overlay and click handlers
5. User hovers → blue highlight appears
6. User clicks → element data sent to editor
7. Editor displays CSS selector and element details
8. User applies changes (hide, text, CSS)

Opening Visual Editor:

• Go to Experiment → Variants tab
• Select a variant (Control or Variation)
• Click "Visual Editor" button
• Enter URL to edit (or use target URL)
• Modal opens with your website loaded

Element Selection:

• Hover: Blue overlay highlights element
• Click: Element selected, details shown
• Info Displayed: Tag name, classes, ID, text content
• CSS Selector: Auto-generated (e.g., .hero-section .cta-button)
• Manual Override: Edit selector if auto-gen isn't specific enough

Change Types You Can Apply:

• Hide Element: display: none (removes from page)
• Replace Text: Change button text, headlines, etc.
• Custom CSS: Color, size, position, fonts, etc.
• Custom JavaScript: Advanced DOM manipulation

⚠️ Snippet Required:

If you see "Segmently Snippet Required" banner, the snippet isn't installed on your website yet. Add it to the <head> tag and refresh. Visual Editor only works when snippet is present!

Why This Approach?

• ✅ Works with modern SPAs (React, Next.js, Vue, Angular)
• ✅ No CORS issues (snippet runs on your domain)
• ✅ No browser extension required
• ✅ No bookmarklet to paste
• ✅ Works automatically (snippet already installed)
• ✅ Identical to Optimizely's approach

Troubleshooting:

• Element selection not working? Check if snippet is installed (view browser console for "✅ Segmently loaded")
• Wrong element selected? CSS selector may need refinement - edit manually
• Changes not showing? Check selector matches intended element (use browser DevTools)
• Website not loading? Check for X-Frame-Options header blocking iframes

Best Practices:

• Test selectors in browser DevTools first (document.querySelector)
• Use specific selectors (avoid body > div > div)
• Prefer classes over IDs when possible
• Preview changes before saving
• Test on mobile/desktop if targeting multiple devices

Alternative: Manual CSS Selectors:

If Visual Editor isn't working or you prefer manual control, you can enter CSS selectors directly in the Variants tab. Use browser DevTools to find selectors: Right-click element → Inspect → Copy selector.

Accessing Analytics:

• Experiment-Specific: Experiment menu → "View Analytics" (available for all states)
• Overall Dashboard: Main navigation → "Analytics" (cross-site view)

Key Metrics Explained:

1. Total Visitors

• Count of unique visitors assigned to each variant
• Tracked via page_view events
• Visitor = unique visitor_id (determined by fingerprinting or cookie-free ID)
• Same visitor seeing page multiple times = 1 visitor (not multiple)

2. Conversions

• Count of visitors who completed your goal
• Tracked via conversion events (trackConversion() or URL-based)
• Multiple conversions from same visitor = 1 conversion
• Binary metric: Either converted or didn't

3. Conversion Rate

• Formula: (Conversions / Total Visitors) × 100
• Expressed as percentage (e.g., 5.2%)
• Primary metric for winner determination
• Example: 52 conversions / 1000 visitors = 5.2%

4. Statistical Significance

• Measures confidence that a variant's improvement is real and not due to random chance
• Calculated using a two-proportion z-test, the industry-standard method for A/B test analysis
• Compares each treatment variant's conversion rate against the Control variant
• Formula: z = |p2 − p1| / √(pPooled × (1−pPooled) × (1/n1 + 1/n2))
• Expressed as a percentage confidence level (e.g., 95%, 99%)
• 95%+ = Statistically significant; winner is declared
• <95% = Inconclusive; keep collecting data
• Requires at least 10 visitors per variant to compute (returns 0 otherwise)

5. Confidence Level

• Directly derived from the z-test p-value: confidence = (1 − pValue) × 100
• Capped at 99.9% to prevent misleading "100% certain" displays
• 95% confidence = 95 in 100 experiments would show the same outcome
• 99% = Very strong result; rare to be wrong
• When significance is first reached, a significance.reached Slack / webhook notification fires automatically (once per experiment)

6. Duration

• Number of days experiment has been running
• Calculated from launch date to now
• Minimum 7-14 days recommended for most tests
• Accounts for weekly traffic patterns

7. Average Time on Page

• Average seconds visitors spend on page
• Engagement metric (higher = more engaged)
• Tracked automatically by snippet
• Excludes bounces (<5 seconds)

8. Bounce Rate

• Percentage of visitors who left without interaction
• Formula: (Bounces / Total Visitors) × 100
• Lower = better (means people engage)
• Bounce = <5 seconds on page or immediate exit

9. Revenue (Optional)

• Total revenue attributed to each variant
• Tracked via trackConversion({ value: 99.99 })
• Useful for e-commerce experiments
• Shows average order value per variant

Winner Determination Logic:

1. Fetch all variant analytics (visitors, conversions, conversion rate)
2. Run a two-proportion z-test comparing each treatment variant against Control
3. Winner = the treatment variant with the highest z-test confidence that also beats Control's conversion rate
4. If the winning confidence ≥ 95%, a winner is declared and the banner is shown
5. If no variant reaches 95% confidence, show "No clear winner yet; collect more data"
6. The first time 95% is reached, a one-time significance.reached notification fires via Slack / outbound webhook

Winner Callout Banner:

• Green banner at top when winner found
• Shows variant name and conversion rate
• Displays confidence level (e.g., "97% confidence")
• Only appears when 95%+ threshold met

Variant Performance Comparison:

• Side-by-side cards for each variant
• Shows all key metrics in one view
• Visual bars indicate conversion rate differences
• Best performer highlighted with border/badge
• Sort by visitors, conversions, or rate

Overall Analytics Dashboard:

• Cross-site view of all experiments
• Filter by: Site, Status, Time Range (7d/30d/90d/all)
• Sortable table by: Date, Visitors, Conversions, Rate
• Quick links to experiment-specific analytics
• Summary stats: Total experiments, active, paused, archived

When to Stop an Experiment:

• ✅ Winner declared with 95%+ confidence
• ✅ Run for at least 7-14 days (capture weekly patterns)
• ✅ Sufficient sample size (1000+ visitors recommended)
• ⚠️ Don't stop early just because one variant looks better
• ⚠️ Statistical significance may be false positive with small sample

Best Practices:

• Run experiments for full weeks (Mon-Sun)
• Don't peek at results daily (increases false positives)
• Wait for 95% confidence before declaring winner
• Consider external factors (holidays, promotions)
• Validate with secondary metrics (time on page, bounce rate)
• Document learnings even if no clear winner

Key Metrics:

• Total visitors per variant
• Conversion count & rate
• Statistical significance (95% confidence threshold)
• Winner determination with confidence level

Engagement Metrics:

• Average time on page
• Bounce rate
• Revenue per variant (optional)

Timeline Visualization:

• Daily visitor trends
• Conversion rate over time
• Export to CSV and JSON

Automatic Tracking:

• Page views (tracked automatically when snippet loads)
• Bounce events (user leaves without interaction)
• Stored in PostgreSQL with JSONB metadata

Database Schema:

• events table: id, project_id, visitor_id, experiment_id, variant_id
• event_name: 'page_view', 'conversion', 'bounce'
• event_data: JSONB field for extensibility
• created_at: timestamp for analysis

Batch Tracking:

• POST /api/v1/events/batch endpoint
• Insert multiple events with transactions
• Reduces server load for high-volume sites

Assignment Tracking:

• Deterministic variant assignment (consistent hashing)
• hash(visitor_id + experiment_id) % 100 < traffic_percentage
• Stored in assignments table (UNIQUE constraint)
• Prevents duplicate assignments
• Weight-based variant distribution

Manual Tracking:

// Track conversion
window.Segmently.trackConversion();

// Track with value
window.Segmently.trackConversion({
  value: 99.99
});

Automatic Tracking:

• Page views (tracked automatically)
• Bounce events (user leaves without interaction)

Manual Tracking:

// Track conversion
window.Segmently.trackConversion();

// Track with value
window.Segmently.trackConversion({
  value: 99.99
});

Site Configuration:

• Unified Conversion Rules with named events (conversion, login, registration)
• Single condition or multi-step sequence detection
• URL, URL parameter, localStorage, and cookie detection methods
• Real-time condition tester for URL and URL parameter rules

1. Profile Settings:

• Update name, email, organization
• View current subscription tier
• Account creation date

2. Security:

• Change password (requires current password)
• Password requirements: 6+ characters
• Password reset via email (when email service enabled)

3. Team & Permissions:

• View all team members with roles and status
• Transfer ownership (owner only)
• Suspend/activate members (owner only)
• Remove team members (owner only)
• Seat count display (e.g., "2/2 seats")

4. Notifications:

• Email notifications toggle
• Experiment results alerts
• Weekly reports (when available)
• Security alerts

5. Billing:

• View current plan and pricing
• Manage subscription (cancel, reactivate)
• Access Stripe Customer Portal
• View payment history and invoices
• Upgrade/downgrade plans

Team Invitation System:

• Secure Tokens: 32-byte cryptographically secure tokens
• 7-Day Expiration: Invitations expire after one week for security
• Email Verification: Checks if invited email already has an account
• Intelligent Routing: Automatically directs users to login or signup
• One-Click Acceptance: Seamless team joining experience

Invitation Acceptance Flow (3 States):

• Existing User: Redirects to login with email pre-filled, then auto-accepts invitation and adds to team
• New User: Shows invitation-focused signup form (displays team name and role), creates account, auto-logs in, joins team immediately
• Already Logged In: Auto-accepts invitation and redirects to dashboard with success message

Why This Matters:

• No duplicate accounts created by mistake
• Existing users don't need to create new credentials
• New users see the exact team they're joining before signup
• Zero friction - users land on dashboard immediately after joining
• Perfect for collaborative A/B testing teams

Team Roles:

• Owner: Full control, can transfer ownership, invite/remove members
• Admin: Manage experiments and settings (future enhancement)
• Member: View and edit experiments (future enhancement)

Member Status Badges:

• Active (Green): Can access all features
• Suspended (Red): Login/API access disabled
• Pending (Amber): Invitation sent but not yet accepted

Owner Actions:

• Invite Member: Send invitation email with secure token
• Cancel Invitation: Revoke pending invitations before acceptance
• Transfer Ownership: Make another member the owner
• Suspend Member: Temporarily block access (no login, API disabled)
• Activate Member: Restore suspended account
• Remove Member: Delete from team permanently (with restrictions)

Team Member Removal Rules (Critical Business Logic):

• Cannot Remove Yourself: Owner must transfer ownership first before leaving
• Must Have One Member: Organizations must have at least one active member
• Must Have One Admin: At least one owner/admin must remain
• Owner-Only Action: Only owners can remove team members
• UI Feedback: Disabled remove button shows reason (e.g., "Last admin", "You")

Why Removal Rules Matter:

• Prevents accidental organization lockout
• Ensures continuous access to sites and experiments
• Protects data ownership and billing continuity
• Forces proper ownership transfer process

Team Limits by Tier:

• Free: 0 additional members (just you)
• Professional ($599/mo): 1 team member
• Business ($999/mo): 2 team members
• Enterprise ($9,999/mo): Unlimited team members

Invitation Security:

• Tokens validated on every acceptance attempt
• Expired invitations automatically rejected
• One-time use tokens (cannot reuse after acceptance)
• Email verification prevents unauthorized access
• Invitation cancellation instantly invalidates tokens

Use Cases:

• Agencies: Collaborate with clients on their experiments
• Marketing Teams: Multiple marketers managing A/B tests
• Product Teams: Engineers, designers, PMs working together
• Organizations: Each organization maintains separate team structure
• Multiple Organizations: Enterprise users can create additional organizations and switch between them from the header menu

Enterprise accounts can create and switch between multiple organizations. Each organization operates independently with its own sites, experiments, team members, and billing.

How to Create a New Organization:

1. Open the header menu (top right)
2. Click your organization name to open the org switcher
3. Click New organization
4. Enter a name and press Enter or click Create

How to Switch Organizations:

1. Open the header menu
2. Click your current organization name to open the org switcher
3. Click any organization in the list to switch to it

Each Organization Has Its Own:

• Sites and experiments
• Team members and roles
• Subscription and billing
• API keys and integrations
• Analytics data

Common Use Cases:

• Agencies: Separate organizations per client to keep data isolated
• Enterprise teams: Different business units with independent billing
• White-label: Brand-specific organizations for resellers

Available on Enterprise plans only. Non-Enterprise users can still be added as members of Enterprise-owned organizations by their team owners.

Each site has a configuration page where you define how the Segmently snippet detects and tracks events from visitor activity. Conversion Rules are a unified system for tracking conversions, logins, and registrations all in one place.

Payment Processing:

• Powered by Stripe (secure, PCI compliant)
• Credit cards, debit cards, digital wallets
• Automatic billing on renewal
• Instant plan activation

Subscription Management:

• Cancel anytime (access until period end)
• Annual plan cancellations stop auto-renewal only (no prorated refunds)
• Reactivate canceled subscriptions
• View upcoming renewals and amounts
• Access payment history and invoices

Stripe Customer Portal:

• Update payment methods securely
• Download invoices and receipts
• View billing history
• Manage subscription details

Plan Changes:

• Upgrade instantly (prorated billing)
• Downgrade at period end
• Limits enforced immediately

Badge Appearance:

• Bottom-right corner of client websites
• Segmently logo with "Powered by Segmently" text
• Links to segmently.us
• Small, non-intrusive design

Technical Implementation:

• Iframe isolation (prevents CSS/JS removal)
• MutationObserver reattaches if removed
• All styles use !important (no override)
• Only shown when subscription_tier === 'free'

Removal:

• Upgrade to Professional or higher
• Badge instantly removed from all sites
• Snippet automatically checks tier on load

Free Tier ($0/mo):

• Up to 5,000 visitors/month
• Snippet and project access only (no experiments), 1 site, 1 owner
• 3 days data retention
• “Powered by Segmently” badge (required)
• Community support

Professional ($599/mo):

• Unlimited visitors
• 1 experiment, 1 site, 1 team member
• 7 days data retention
• Full analytics, funnel goals, Slack notifications
• No branding, priority support

Business ($999/mo):

• Unlimited visitors
• 2 experiments, 1 site, 2 team members
• 30 days data retention
• Advanced analytics, GA4/Mixpanel/webhook integrations, REST API

Enterprise ($9,999/mo):

• Unlimited visitors, experiments, sites, team members
• 1 year data retention
• Dedicated account manager, 99.99% SLA, custom webhook integrations

Limit Enforcement:

• “+ New Site” button disabled when at limit
• “+ New Experiment” button disabled when at limit
• “Invite Member” button disabled when at limit
• Upgrade prompts with tier-specific messaging
• Badge shows current usage (e.g., “1/1 Sites”)
• Experiment data is automatically purged after each tier's retention window

Authentication:

• JWT tokens with 30-day expiration
• Database validation on every request
• Auto-logout on account suspension/deletion
• Bcrypt password hashing (cost 10+)

Privacy:

• No cookies stored on visitor browsers
• No cross-site tracking
• GDPR compliant by design
• Full data ownership

API Security:

• API key validation on every event
• Rate limiting per IP address
• Input sanitization (XSS protection)
• Disabled accounts = disabled API keys instantly

Match Types:

Exact: https://example.com/pricing
Only matches this exact URL

Contains: /product/
Matches any URL with /product/ anywhere

Starts With: https://example.com/blog/
Matches all blog posts

Ends With: /checkout
Matches any checkout page

Regex: ^https://example\.com/product/[0-9]+$
Advanced pattern matching

Experiments only run on matching URLs - visitors won't be tracked elsewhere

Every click, scroll, and mouse movement your visitors make is captured by the Segmently snippet and aggregated server-side. The heatmap dashboard renders this data as a colour gradient overlay on top of a screenshot-accurate view of your page. Hot spots (red, orange) show high activity; cold spots (blue, transparent) show low activity.

Heatmaps answer questions that A/B test numbers alone cannot, such as: Are visitors clicking a non-clickable element? Do they ever reach your CTA? Are they reading the pricing section before they leave?

Heatmap types available:

• Click Heatmap: radial gradient dot for every click recorded
• Scroll Depth: horizontal bar chart showing what percentage of visitors reached each 5% scroll increment
• Mouse Moves: density map of cursor movement paths (Business+)
• Top Elements: ranked table of CSS selectors by total click count

Plan requirements:

As long as the standard Segmently snippet is on your page and your plan includes heatmaps, tracking begins automatically on every page load. No separate script tag, no extra API calls, no manual initialisation.

What the snippet tracks (based on your plan tier):

• Clicks: every click on any element, with normalised x/y coordinates relative to the page (0–1 range)
• Scroll depth: the maximum scroll percentage reached during each page visit (e.g., max_depth: 75 means the visitor scrolled 75% down the page)
• Mouse moves: sampled every 100ms, normalised coordinates (Business+)
• Rage clicks: when a visitor clicks the same element 3 or more times within two seconds (signals frustration or confusion)
• Dead clicks: clicks that land outside of any interactive element (a, button, input, select, textarea, label)
• Session recordings: full DOM snapshots and mutation events streamed as compressed chunks (Enterprise)

Verify tracking is active:

1. Open your site in a browser and open DevTools (F12)
2. Go to the Network tab and filter by batch
3. Click around your page. You should see POST /api/v1/events/batch requests firing.
4. In the request payload you will see events with event_name: "heatmap_click", "heatmap_scroll", etc.

Note: The snippet waits until the page is fully loaded before enabling heatmap tracking. This ensures coordinate calculations are accurate and do not conflict with the anti-flicker protection used by A/B experiments.

The click heatmap overlays a radial gradient blur on a 900×540 canvas for every recorded click, scaled to the actual page dimensions. Areas that receive many clicks accumulate brighter, larger gradients. The result is an immediate visual understanding of where visitor attention and interaction concentrate.

Using the click heatmap dashboard:

1. Navigate to Dashboard > Heatmaps from the main navigation
2. Select your Site from the dropdown
3. Choose the Page URL you want to analyse (populated from actual click data)
4. Select a Device filter: Desktop, Mobile, or Tablet
5. The canvas updates automatically with no reload required.

Rage clicks and dead clicks:

• Rage click: three or more rapid clicks on the same element. Usually indicates a broken CTA, a slow-loading page, or user frustration. The snippet auto-detects these and sends a separate heatmap_rage_click event.
• Dead click: a click that lands on a non-interactive element (text, image, blank area). High dead-click rates on a specific area can indicate that visitors expect something to be clickable but it is not.

Reading the intensity scale:

• Red/orange: very high click density (most popular area)
• Yellow/green: moderate click density
• Blue/transparent: low or zero clicks

Data window: The default view shows the last 30 days. Heatmap data is aggregated in daily snapshots by the background scheduler, so new clicks typically appear within a few minutes during active testing periods.

The scroll depth chart shows what percentage of visitors reached each vertical slice of the page. The snippet records the maximum scroll depth for each page view in the max_depth field. Server-side aggregation then buckets these values into 5% steps (0–5%, 5–10%, …, 95–100%).

How to interpret scroll data:

• The top bar (0–5%) always shows close to 100%; nearly every visitor sees the very top of the page
• A sharp drop at a specific depth means visitors are leaving at that point; your content above that fold is not compelling enough to scroll further
• If your CTA is at 70% depth but only 20% of visitors reach it, that is a structural problem: move the CTA up or add a sticky version
• A plateau (depth suddenly levels off) often corresponds to a visual break in the page layout; visitors think the page ends there

The fold line:

"Above the fold" typically corresponds to the first 15–25% of page depth (depending on page length). Use scroll data combined with click heatmaps to understand whether key content above the fold is actually driving engagement.

Device filter matters here: Mobile visitors often scroll more than desktop visitors on long-form pages (smaller viewport = more scrolling to see the same content). Always compare Desktop vs Mobile scroll data separately before making layout decisions.

Research consistently shows that mouse movement tracks eye movement with roughly 80–90% correlation on desktop. Where visitors move their cursor is where they are focused. The mouse move heatmap makes this visible as a density gradient overlay.

How it is collected:

• The snippet samples cursor position every 100ms while the page is active
• Coordinates are normalised to 0–1 relative to the full page dimensions so data is resolution-independent
• Samples are batched and sent as heatmap_move events

Using move data alongside click data:

• Areas with high move density but low click density: visitors are reading that content but not acting on it. Consider adding a CTA near this area.
• Areas with high click density but low move density: impulse clicks, often from users who already know what they want (return visitors, direct-nav users).
• Large areas of zero move density: visitors may not be scrolling there at all, or the content is not holding attention.

Business and Enterprise only. Mouse move tracking is not available on Free or Professional plans. If your plan does not include it, the Moves tab will display a plan upgrade prompt.

The Top Elements tab shows the most-clicked CSS selectors on a given page, sorted by total clicks across all recorded sessions. This is useful when you want a precise answer rather than a visual approximation.

Selector generation:

When a click is recorded, the snippet generates a stable CSS selector for the clicked element. It follows this priority order:

1. #id if the element has a unique ID
2. tag.class (tag name plus the first non-dynamic class)
3. tag[data-attr] (data attribute, if present)
4. Fallback path using parent chain (up to 3 levels)

Practical uses:

• Use the top-clicked element selector directly in A/B experiments as a Visual Editor target
• Identify elements being rage-clicked (check the Rage Clicks column next to each selector)
• Find elements with unexpectedly high click rates; these are candidates for experiment testing

Filtering tip: Use the Device filter in combination with the URL filter to compare which elements desktop vs mobile visitors click most. Mobile users often interact with completely different elements.

Session recordings let you watch a replay of exactly what each visitor saw and did on your site, frame by frame. Unlike heatmaps (which aggregate thousands of visitors), recordings show individual journeys, ideal for diagnosing specific UX problems, understanding edge cases, or validating experiment results.

How recordings work:

1. When a new session starts, the snippet sends POST /api/v1/sessions/start and receives a session_id
2. The snippet captures a full DOM snapshot plus all subsequent mutations (layout shifts, dynamic content, React/Vue rerenders)
3. Events are compressed and streamed as chunks to POST /api/v1/events/session-chunk every few seconds
4. At the end of the session (page unload or 30-minute idle), the session record is finalised with duration and metadata

What is recorded:

• All mouse movements, clicks, and scroll positions
• DOM mutations (text changes, element additions/removals, style changes)
• Form input events (field focus, blur; values are masked by default for privacy)
• Page navigation and URL changes (supports SPA routing)
• Viewport size and device type

Privacy and data masking:

All input field values (type="password", type="email", and standard text fields) are masked to *** in the recording stream before transmission. Sensitive content is never sent to Segmently servers.

The Sessions dashboard:

• Navigate to Dashboard > Sessions
• Each row shows: session date/time, entry URL, device type, session duration, rage-click count, and whether the visitor converted
• Filter by site and date range
• Session playback is rendered directly in the browser, with no plugin or extension required

Enterprise only. Session recordings require the Enterprise plan. The Sessions menu item and all recording endpoints are gated at both the frontend and backend. If your organisation is on a lower tier, the sessions page will display an upgrade option.

All endpoints require a valid JWT token in the Authorization: Bearer <token> header, except POST /sessions/start and POST /events/session-chunk which use an API key.

No data showing after installation:

• Confirm your plan includes heatmaps (Professional+). Free accounts see a lock screen.
• Check the browser Network tab for POST /events/batch requests. If none appear, the snippet may not be loading. Verify the data-api-key attribute on the script tag.
• Heatmap data is aggregated in batches. New installs may take a few minutes before data first appears in the dashboard.

Coordinates look off / clicks not lining up with the page:

• Coordinates are normalised (0–1 range) based on the page dimensions at the time of click. The dashboard canvas scales them back to a 900×540 render area. If your page has dynamic height (infinite scroll, lazy-loaded sections), coordinates from early in a session may not match your current page layout.
• Always use the Device filter to compare desktop vs mobile data separately, as coordinate spaces differ significantly between viewport sizes.

Session recordings missing chunks:

• Recordings stream in real time. If a visitor closes the tab mid-session, the final chunk may not be transmitted. Shorter sessions with abrupt exits may have incomplete recordings.
• Verify that your Content Security Policy (CSP) does not block connect-src https://segmently.us, which is required for chunk uploads.

Mouse move tab is locked:

Mouse Move Heatmaps require a Business or Enterprise plan. If you are on Professional or Free, the tab displays a plan upgrade prompt. Upgrade in Settings > Billing to unlock.