Test Triggers

When creating JavaScript API tests, you'll need to choose between Automatic and Manual triggers. This determines when and how visitors become eligible to participate in your test.

Automatic Trigger

With automatic triggers, visitors enter the test immediately when the page loads, before any JavaScript API calls.

How it works:

// Visitor is ALREADY in the test before this code runs
const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
// This just checks their assignment

Characteristics:

• Test participation triggered on page load

• Every visitor who meets targeting criteria enters the test

• Test participation tracked even if feature isn't used

• Best for always-visible elements

Use Cases:

• Hero banners

• Navigation changes

• Global UI elements

• Chat widgets

• Promotional bars

• Footer modifications

Example: Automatic Trigger for Hero Banner

// Test triggers for ALL visitors immediately on page load
document.addEventListener('DOMContentLoaded', async () => {
  const showNewHero = await window.shoplift.isHypothesisActive('hero-v2-id');
  
  if (showNewHero) {
    document.querySelector('.hero').innerHTML = newHeroContent;
  }
  // Even visitors who scroll past immediately are in the test
});

Manual Trigger

With manual triggers, visitors only enter the test when your code calls isHypothesisActive() for the first time.

How it works:

// No test participation yet
button.addEventListener('click', async () => {
  // Test participation triggered NOW, on first call
  const isActive = await window.shoplift.isHypothesisActive('hypothesis-id');
  // Visitor is now permanently assigned to a variant
});

Characteristics:

• Test participation triggered by JavaScript call

• Only visitors who trigger the action enter the test

• More accurate test results (only engaged users)

• Reduces test pollution from unengaged visitors

Use Cases:

• Mini carts

• Quick view modals

• Dropdown menus

• Search overlays

• Product quick-add features

• Any user-triggered interaction

Example: Manual Trigger for Mini Cart

// Test only triggers when visitors actually open the cart
document.querySelector('.cart-icon').addEventListener('click', async () => {
  // First click triggers test participation
  const useNewCart = await window.shoplift.isHypothesisActive('cart-v2-id');
  
  if (useNewCart) {
    openNewMiniCart();
  } else {
    openStandardCart();
  }
  // Only cart users are in the test data
});

Choosing the Right Test Trigger

Decision Framework

• Is the tested element always visible?

  • Yes → Automatic trigger

  • No → Manual trigger

• Should all visitors be in the test?

  • Yes → Automatic trigger

  • No → Manual trigger

• Is it activated by user action?

  • Yes → Manual trigger

  • No → Automatic trigger

• Do you want to measure engagement rate?

  • Yes → Manual trigger

  • No → Either works

Aspect	Automatic Trigger	Manual Trigger
When test triggers	Page load	First API call
Visitors in test	All who meet targeting	Only those who interact
Best for	Always-visible elements	User-activated features
Sample size	Larger (all visitors)	Smaller (engaged users only)
Statistical significance	Reached faster	Takes longer
Data quality	Includes unengaged users	Only engaged users
Performance impact	Immediate assignment	Deferred assignment