# Getting Started The Shoplift JavaScript API gives you programmatic control over A/B test entry criteria and experiences, visitor consent, and test data retrieval. Use it to build custom test experiences that go beyond what template, theme, and URL tests offer. ### How the Script Loads Shoplift automatically injects and maintains its script in your theme's `` section. You don't need to add any script tags — the script is managed for you and: * Loads before other scripts to minimize flicker * Initializes automatically on every page load * Provides the global `window.shoplift` object * Updates automatically when new versions are released ### The `window.shoplift` Object Once the page loads, three methods are available on the global `window.shoplift` object: ```typescript interface ShopliftPublic { isHypothesisActive(hypothesisId: string): Promise; setAnalyticsConsent(consent: boolean): Promise; getVisitorData(): ExternalVisitorData; } declare global { interface Window { shoplift?: ShopliftPublic; } } ```

Method	Purpose	Returns	Async
`isHypothesisActive()`	Check if visitor is assigned to a specific test variant	`Promise<boolean>`	Yes
`setAnalyticsConsent()`	Sets the visitor's analytics consent state	`Promise<void>`	Yes
`getVisitorData()`	Returns visitor info and all test assignments	`ExternalVisitorData`	No

### Quick Start Most JavaScript API test implementations only need `isHypothesisActive()`. Here's the minimal pattern: ```javascript // 1. Check that Shoplift is loaded if (window.shoplift) { // 2. Check the visitor's variant assignment const isVariant = await window.shoplift.isHypothesisActive('your-hypothesis-id'); // 3. Render the appropriate experience if (isVariant) { // Variant (B) experience } else { // Control (A) experience } } ``` The `hypothesisId` is the unique identifier for your test variant. You'll find it in the Shoplift dashboard when you create a JavaScript API test:

### Safely Checking for Shoplift The `window.shoplift` object may not be available immediately (e.g., if your script runs before Shoplift's script has loaded). You can use a polling pattern to wait for it: ```javascript function waitForShoplift(callback, maxAttempts = 50) { let attempts = 0; function check() { if (window.shoplift) { callback(window.shoplift); } else if (attempts < maxAttempts) { attempts++; setTimeout(check, 100); } else { console.warn('Shoplift did not load within the expected time.'); } } check(); } // Usage waitForShoplift(async (shoplift) => { const isVariant = await shoplift.isHypothesisActive('your-hypothesis-id'); // ... }); ``` ### When to Use the JavaScript API The JavaScript API is the right choice when you need to: * **Control trigger timing** — assign visitors to tests only when they perform a specific action (open a cart, click a tab, scroll to a section) * **Modify dynamic content** — elements that load after the initial page render (AJAX carts, React components, lazy-loaded sections) * **Set third-party consent management state —** if your consent management platform doesn't integrate with Shopify's Customer Privacy API, you can set consent state * **Combine targeting conditions** — factor in more advanced targeting conditions like cookie presence or user behavior before including a visitor in a test and showing a variant * **Integrate with third-party tools** — pass test data to analytics platforms or interact with other apps programmatically