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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.shoplift.ai/test/javascript-api/core-api-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.