# 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 --- # Agent Instructions: 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: ``` GET https://docs.shoplift.ai/api-reference/getting-started.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.