Core API Reference

API Overview

The Shoplift JavaScript API consists of one global object with three methods:

window.shoplift = {
  // Check if visitor is assigned to a test variant
  isHypothesisActive(hypothesisId: string): Promise<boolean>
  
  // Manage visitor analytics consent
  setAnalyticsConsent(consent: boolean): Promise<void>
  
  // Get visitor and test data
  getVisitorData(): VisitorData
}

Method Reference

Method	Purpose	Returns	Async
isHypothesisActive()	Check variant assignment	Promise<boolean>	Yes
setAnalyticsConsent()	Set privacy consent	Promise<void>	Yes
getVisitorData()	Get visitor test data	VisitorData	No

Most Common Usage

Most implementations only need isHypothesisActive():

// Basic test implementation
const isVariant = await window.shoplift.isHypothesisActive('hypothesis-id');

if (isVariant) {
  // Show variant experience
} else {
  // Show control experience
}

Reference Documentation

The window.shoplift Object

The main API interface and entry point for all Shoplift functionality.Covers:

• Object structure and availability

• TypeScript definitions

• Loading strategies

• Error handling patterns

• Browser compatibility

Key Information:

• Automatically injected by Shoplift

• Available globally as window.shoplift

• Should always be checked before use

• Works in all modern browsers

---

isHypothesisActive()

The primary method for checking if a visitor is assigned to a specific test variant.

Covers:

• Complete parameter documentation

• Return value behavior

• Automatic vs manual trigger differences

• URL parameter overrides

• Caching and performance

• Error scenarios

Method Signature:

isHypothesisActive(hypothesisId: string): Promise<boolean>

Key Behaviors:

• Returns true if visitor is in the specified variant

• Returns false if visitor is in control or different variant

• First call triggers assignment for manual trigger tests

• Subsequent calls return cached results

• Respects URL parameter overrides for testing

---

setAnalyticsConsent()

Manually manage visitor analytics consent for custom privacy solutions.

Covers:

• When to use (and when not to use)

• Integration with consent managers

• Shopify Customer Privacy API interaction

• Implementation examples

Method Signature:

setAnalyticsConsent(consent: boolean): Promise<void>

Important Note: Only needed if you have a custom consent solution. Shoplift automatically integrates with Shopify's Customer Privacy API.

---

getVisitorData()

Retrieve comprehensive data about the current visitor and their test assignments.

Covers:

• Complete data structure documentation

• Analytics integration patterns

• Visitor identification

• Test participation tracking

• Debugging uses

Method Signature:

getVisitorData(): VisitorData

Return Structure:

{
  visitor: {
    id: string,
    device: 'desktop' | 'mobile',
    country: string | null,
    // ... more fields
  },
  visitorTests: [
    {
      testId: string,
      hypothesisId: string,
      createdAt: Date,
      // ... more fields
    }
  ]
}

TypeScript Support

All methods are fully typed. Add these definitions to your project:

interface ShopliftAPI {
  isHypothesisActive(hypothesisId: string): Promise<boolean>;
  setAnalyticsConsent(consent: boolean): Promise<void>;
  getVisitorData(): VisitorData;
}

interface Window {
  shoplift?: ShopliftAPI;
}

Common Patterns

Basic Implementation

if (window.shoplift) {
  const isActive = await window.shoplift.isHypothesisActive('test-id');
  // Apply variant logic
}

With Error Handling

try {
  const isActive = await window.shoplift.isHypothesisActive('test-id');
  // Apply variant logic
} catch (error) {
  console.error('Test failed:', error);
  // Default to control
}