getVisitorData()

Retrieve visitor information and test assignments for analytics and debugging.

getVisitorData()

Returns comprehensive data about the current visitor and their A/B test assignments. This is a synchronous method — it returns data immediately without a Promise.

The primary use case is sending Shoplift test data to third-party analytics platforms (Segment, Heap, Hotjar, etc.) so you can analyze test results alongside your existing metrics.

Signature

window.shoplift.getVisitorData(): VisitorData

Parameters

None.

Returns

VisitorData — an object containing two properties:

interface VisitorData {
  visitor: Visitor | null;
  visitorTests: TestRelation[];
}

visitor

Information about the current visitor. May be null if the visitor hasn't been initialized yet.

interface Visitor {
  id: string;                       // Unique Shoplift visitor ID (UUID)
  shopifyAnalyticsId: string | null; // Shopify's analytics visitor ID
  device: 'desktop' | 'mobile';     // Device type
  country: string | null;           // ISO 3166-1 alpha-2 country code (e.g., 'US', 'CA')
  createdAt: Date;                  // Timestamp of visitor's first visit
  storedAt: Date;                   // Timestamp of last data update
  utmSource: string;                // UTM source parameter
  utmMedium: string;                // UTM medium parameter
  utmCampaign: string;              // UTM campaign parameter
  utmContent: string;               // UTM content parameter
  referrer: string;                 // Original referring URL
}

visitorTests

An array of test assignments for the current visitor. Each entry represents one test the visitor is participating in.

interface TestRelation {
  testId: string;        // Unique test identifier
  hypothesisId: string;  // The hypothesis (variant) ID the visitor is assigned to
  isThemeTest: boolean;  // Whether this is a full theme test
  themeId?: number;      // Shopify theme ID (only present for theme tests)
  createdAt: Date;       // Timestamp when the visitor was assigned
  isSaved: boolean;      // Whether the assignment has been persisted
}

Basic Usage

const data = window.shoplift.getVisitorData();

if (data.visitor) {
  console.log('Visitor ID:', data.visitor.id);
  console.log('Device:', data.visitor.device);
  console.log('Country:', data.visitor.country);
}

data.visitorTests.forEach((test) => {
  console.log(`Test ${test.testId}: assigned to ${test.hypothesisId}`);
});

Common Patterns

Send Test Data to an Analytics Platform

This is the core pattern used by all custom analytics integrations. Retrieve visitor data and forward it to your analytics tool:

function sendShopliftDataToAnalytics() {
  if (!window.shoplift) return;

  const { visitor, visitorTests } = window.shoplift.getVisitorData();
  if (!visitor || visitorTests.length === 0) return;

  visitorTests.forEach((test) => {
    // Replace with your analytics platform's API
    trackEvent('Experiment Viewed', {
      experiment_id: test.testId,
      variant_id: test.hypothesisId,
      visitor_id: visitor.id,
      device: visitor.device,
      country: visitor.country,
    });
  });
}

document.addEventListener('DOMContentLoaded', () => {
  // Wait for Shoplift, then send data
  const interval = setInterval(() => {
    if (window.shoplift) {
      clearInterval(interval);
      sendShopliftDataToAnalytics();
    }
  }, 100);
});

For platform-specific implementations, see the integration guides for Segment, Heap, Hotjar, Microsoft Clarity, and Adobe Analytics.

Debugging in the Console

Quick way to inspect the current visitor state:

// Dump all visitor data
console.table(window.shoplift.getVisitorData().visitor);

// List all active test assignments
window.shoplift.getVisitorData().visitorTests.forEach((t) => {
  console.log(`${t.testId} → ${t.hypothesisId} (${t.isThemeTest ? 'theme' : 'element'})`);
});

Conditional Logic Based on Test Participation

Check whether a visitor is in any test before running custom logic:

const { visitorTests } = window.shoplift.getVisitorData();

if (visitorTests.length > 0) {
  // Visitor is participating in at least one test
  console.log(`Active in ${visitorTests.length} test(s)`);
}

// Check for a specific test
const myTest = visitorTests.find((t) => t.testId === 'specific-test-id');
if (myTest) {
  console.log('Assigned variant:', myTest.hypothesisId);
}

Edge Cases

• Visitor not initialized: If called before Shoplift has fully initialized, visitor will be null and visitorTests will be an empty array. Use a polling pattern to wait for data.

• No active tests: If the visitor isn't participating in any tests, visitorTests will be an empty array. visitor data will still be available.

• UTM parameters: UTM fields are populated from the visitor's landing page URL. They'll be empty strings if no UTM parameters were present.

• Country detection: The country field uses GeoIP and may be null if the visitor's location couldn't be determined.