> For the complete documentation index, see [llms.txt](https://docs.shoplift.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.shoplift.ai/test/javascript-api/core-api-reference.md).

# Core API Reference

### API Overview

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

```typescript
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

<table><thead><tr><th width="195.9765625">Method</th><th>Purpose</th><th>Returns</th><th>Async</th></tr></thead><tbody><tr><td>isHypothesisActive()</td><td>Check variant assignment</td><td>Promise&#x3C;boolean></td><td>Yes</td></tr><tr><td>setAnalyticsConsent()</td><td>Set privacy consent</td><td>Promise&#x3C;void></td><td>Yes</td></tr><tr><td>getVisitorData()</td><td>Get visitor test data</td><td>VisitorData</td><td>No</td></tr></tbody></table>

### Most Common Usage

Most implementations only need `isHypothesisActive()`:

```javascript
// 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:**

```typescript
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:**

```typescript
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:**

```typescript
getVisitorData(): VisitorData
```

Return Structure:

```typescript
{
  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:

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

interface Window {
  shoplift?: ShopliftAPI;
}
```

### Common Patterns

#### Basic Implementation

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

#### With Error Handling

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