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

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', {
  value: 99.99
});
// 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
window.Segmently.track('purchase', { value: 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 project 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 project 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.

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 projects and experiments
• Protects data ownership and billing continuity
• Forces proper ownership transfer process

Team Limits by Tier:

• Free: 0 additional members (just you)
• Professional ($299/mo): 1 team member
• Business ($999/mo): 3 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 projects, 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:

• Projects 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.

Project Settings:

• Set project base URL
• Configure conversion tracking methods
• Define login/registration pages
• Manage API keys (view, regenerate)

Experiment Management:

• View active, paused, and archived experiments
• Quick status changes (start, pause, archive)
• Reinstate archived experiments

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):

• Unlimited visitors
• 1 experiment, 1 project, 1 team member
• 3 days data retention
• “Powered by Segmently” badge (required)
• Community support

Professional ($499/mo):

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

Business ($1,499/mo):

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

Enterprise ($9,999/mo):

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

Limit Enforcement:

• “+ New Project” 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 Projects”)
• 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