Docs
  • INTRO
    • Welcome to Shoplift
    • What to Test
    • Quickstart
      • Install Shoplift
      • Create a Test
      • Edit Your Variant
      • Launch Your Test
  • TEST
    • Template Testing
      • Overview
      • Guides
        • Guide: How to Use Shopify Magic to Generate New Theme Blocks for Testing
        • Guide: Testing Individual Pages
        • Guide: Testing One-Click Payment Methods
        • Guide: Testing App Blocks
        • Guide: Testing Different Template Types
      • Theme Compatibility
      • Template Management
      • Switching Themes
      • Shopify Markets
      • Shopify Translate & Adapt
    • Theme Testing
      • Overview
      • Guides
        • Guide: Testing a Navigation Menu
        • Guide: Testing a Mini Cart
      • Theme Management
      • Theme Development
      • Switching Themes
    • URL Testing
      • Overview
      • Guides
        • Guide: Testing URLs
        • Guide: Testing Product Properties
    • JavaScript API Testing
      • isHypothesisActive
      • setAnalyticsConsent
      • getVisitorData
    • Lift Assistâ„¢
      • What is Lift Assistâ„¢?
      • How To Use Lift Assistâ„¢
      • Brand Styles
    • Audience Targeting
      • Devices
      • New and Returning Visitors
      • Custom Audiences (UTMs, Referring Domains, and Geo-targeting)
    • Test Management
      • Test Compatibility
      • Mutual Exclusion
      • QA Checklist
      • Scheduling Tests
      • Pausing Tests
      • Implementing Winning Tests
    • Performance
      • Pagespeed
      • Shopify Caching
      • CDNs and Edge Delivery
  • ANALYZE
    • Reports
      • Overview
      • Metrics
        • Goals & Reporting Metrics
        • Metric Views
      • Test Progress
      • Statistical Significance
      • Channel Groups
    • Tracking
      • Visitor Attribution
      • Web Pixel
      • Liquid Snippet
      • Anti-Flicker
      • Analytics Discrepancies
  • integrate
    • Integrations and Tooling
      • GA4 (Beta)
        • Integrate GA4 (Shopify)
        • Integrate GA4 with Google Tag Manager
        • Integrate GA4 with Elevar
        • Analyze Test Data In Google Analytics
        • Disabling the GA4 Integration
      • Subscription Apps
      • Page Builder Apps
      • Reporting Tools
      • Heatmapping Tools
      • Custom Integrations
  • ADMIN
    • Plans and Billing
      • Subscription Plans
      • Uninstalling Shoplift
    • Users and Permissions
      • Managing Team Access
      • Managing User Notifications
    • Privacy and Compliance
      • Customer Data and GDPR
  • PARTNERS & DEVELOPERS
    • Shoplift Partner Program
    • Testing on Development Stores
  • SUPPORT
    • Frequently Asked Questions
    • Get Help
    • Give Feedback
Powered by GitBook

Contact Us

  • Get help
  • Give feedback
  • Request a feature

Helpful Links

  • Shoplift
  • Shopify App Store
On this page
  • Overview
  • Script-based tests
  • Visitor allocation options
  • The 'shoplift' object
  • Methods
  • Examples

Was this helpful?

  1. TEST

JavaScript API Testing

PreviousGuide: Testing Product PropertiesNextisHypothesisActive

Last updated 5 months ago

Was this helpful?

Overview

Shoplift provides a JavaScript API that you can leverage on your store to create custom script-based tests.

With our API, you can leverage the benefit of Shoplift's visitor allocation, segmentation, and analytics features while defining your own test experiences outside of the framework of template, theme, or URL redirect tests.

While script-based tests are the primary intent of the API, it can also be used to extend the capabilities of template, theme, and URL redirect tests if you wish to implement additional script-based changes for them.

Script-based tests

By default, the Shoplift script is inserted directly after the opening <head> tag in your theme.liquid layout files and should be loaded before anything else on your store.

This is important for visitor allocation to variants to be as fast as possible, to ensure minimal disruption or "flicker effect." We strongly recommend keeping the script at the top of your <head>.

If you need to move the scripts location for any reason, it must remain above any usage of the API.

We provide two types of script-based tests. By default, these tests do not do anything except split your visitors into your A and B experiences.

When creating a script-based test, Shoplift creates a control and a variant "hypothesis", each with their own ID. On the test draft screen you are able to see and copy these hypothesis IDs for usage in the API. These IDs will remain the same when the test is launched.

Visitor allocation options

Script tests may use either "automatic" or "manual" approaches to visitor allocation (think of this like a test trigger).

Automatic visitor allocation

Tests that use automatic visitor allocation will allocate visitors between A and B experiences in the same way as our theme tests, allocating visitors to an experience on pageload as soon as they first navigate to the store while the test is running. This is a good fit for testing elements that are visible to all visitors, such as chat widgets and popups.

Manual visitor allocation

Tests that use manual visitor allocation will only allocate visitors to an A or B experience after calling the isHypothesisActive method (see below). This is a good fit for testing elements that are only visible after a visitor interacts with something, such as mini carts or nested navigation menus.

The 'shoplift' object

When the Shoplift script is loaded, we expose a global object called shoplift, which serves as the primary entry point for the API.

Methods

The following uses TypeScript type notation.

isHypothesisActive(hypothesisId: string): Promise<boolean>

isHypothesisActive takes a hypothesisId string as its only argument, and returns an async Promise that will resolve to true if the current visitor is assigned to that hypothesis. It will resolve to false if the visitor is not assigned to that hypothesis, or if the test is not actively running.

If the test uses manual visitor allocation, then this method will split the visitor into A or B before returning, and synchronize the determination with Shoplift in the background.

The Promise returned by this function will resolve immediately unless you are using a manual split test that also uses GeoIP targeting. If you are using a manual split test with GeoIP targeting, then we must wait for the GeoIP to resolve before splitting the visitor, which will result in waiting for a network call.

Examples

Manual allocation for a Mini Cart test

In this example, we have created a test with Manual traffic allocation. To trigger the allocation we can create a simple method that we would then bind to the 'onClick' event of the mini cart:

async function onMiniCartClick() {
  const variantId = "aa800953-3e22-4335-a53b-50f61db17538"; // ID of the Variant Hypothesis from my test.
  const onVariant = await shoplift.isHypothesisActive(variantId);
  if (onVariant) {
    // Variant is active
  }
}

Assignment to a hypothesis will not happen until the isHypothesisActive() call is triggered.