JavaScript API Tests

JavaScript API tests enable you to create sophisticated A/B tests directly in your theme code, giving you complete control over test logic and visitor experiences. While Shoplift's template, theme, and URL tests handle many use cases, JavaScript API tests are perfect for:

• Interactive elements (mini carts, navigation menus, popups)

• Complex tests with custom logic

• User-triggered experiences that shouldn't load immediately

• Conditional content based on multiple factors

JavaScript API vs Other Test Types

Understanding when to use the JavaScript API versus other Shoplift test types:

Use JavaScript API Tests When You Need:

• Custom trigger logic - Show variants based on user actions (clicks, scrolls, form submissions)

• Complex conditions - Combine multiple factors (device type + location + user behavior)

• Dynamic content - Modify content that loads after page load (AJAX carts, React components)

• Third-party integrations - Work with apps that need programmatic control

• Performance optimization - Load test variations only when needed (manual allocation)

Use Other Test Types For:

• Template tests - Simple content swaps in Liquid templates

• Theme tests - Testing entirely different themes

• URL tests - Redirecting to different pages or URLs

Basic Usage

const isVariant = await window.shoplift.isHypothesisActive(
  'aa800953-3e22-4335-a53b-50f61db17538'
);

if (isVariant) {
  showVariantExperience();
} else {
  showControlExperience();
}

Test Triggers

JavaScript API tests support two test participation strategies (triggers).

Automatic Trigger

• Visitors are assigned immediately when the page loads

• Best for always-visible elements

• Test runs even if JavaScript API isn't called

• Use for: hero banners, global UI changes, chat widgets

Manual Trigger

• Visitors are only assigned when isHypothesisActive() is called

• Perfect for user-triggered interactions

• Reduces unnecessary test participation

• Use for: mini carts, dropdown menus, modal popups

You can choose your strategy when creating the test in Shoplift.

For more information see Test Triggers