> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Shopify Installation

> Integrate Alana Search into Shopify via Liquid snippet (Online Store 2.0) or the Hydrogen React component

## Two Integration Paths

| Path                   | Best for                           | File                             |
| ---------------------- | ---------------------------------- | -------------------------------- |
| **Liquid snippet**     | Online Store 2.0 themes (standard) | `alana-predictive-search.liquid` |
| **Hydrogen component** | Headless Hydrogen storefronts      | `AlanaSearch.tsx`                |

***

## Option A: Liquid Snippet (Online Store 2.0)

### Step 1 — Add the snippet

Copy `alana-predictive-search.liquid` to your theme's `snippets/` directory via the Shopify Admin theme editor or CLI:

```bash theme={null}
shopify theme pull
cp adapters/shopify/snippets/alana-predictive-search.liquid snippets/
shopify theme push
```

### Step 2 — Configure API credentials

In **Shopify Admin → Online Store → Themes → Customize → Theme Settings**, add:

| Setting         | Value                        |
| --------------- | ---------------------------- |
| `alana_api_key` | Your `ak_xxx` API key        |
| `alana_api_url` | `https://app.alana.shopping` |

Or set directly in `config/settings_data.json`:

```json theme={null}
{
  "current": {
    "alana_api_key": "ak_your_api_key",
    "alana_api_url": "https://app.alana.shopping"
  }
}
```

### Step 3 — Render the snippet

In your theme's search template (e.g., `sections/predictive-search.liquid` or the search form partial), add:

```liquid theme={null}
{% render 'alana-predictive-search' %}
```

The snippet automatically:

1. Finds `input[type="search"]`, `input[name="q"]`, or `#Search-In-Template`
2. Attaches autocomplete to the input
3. Intercepts form submit to call Alana search
4. Renders results in `#alana-results-container`

### What the Liquid snippet provides

* Autocomplete dropdown on keypress (200ms debounce)
* Full search results grid on form submit
* Spell correction suggestion with click-to-search
* `detail-page-view` event on product card click
* Persistent visitor ID via `localStorage`

***

## Option B: Hydrogen Component (Headless)

### Step 1 — Copy the component

```bash theme={null}
cp adapters/shopify/components/AlanaSearch.tsx app/components/AlanaSearch.tsx
```

### Step 2 — Use in a route

```tsx theme={null}
import { AlanaSearch } from '~/components/AlanaSearch';

export default function SearchPage() {
  return (
    <AlanaSearch
      apiKey="ak_your_api_key"
      apiUrl="https://app.alana.shopping"
      hitsPerPage={20}
      placeholder="Search products..."
    />
  );
}
```

### Component props

| Prop          | Type     | Default                      | Description               |
| ------------- | -------- | ---------------------------- | ------------------------- |
| `apiKey`      | `string` | required                     | Your Alana search API key |
| `apiUrl`      | `string` | `https://app.alana.shopping` | API base URL              |
| `hitsPerPage` | `number` | `20`                         | Results per search        |
| `placeholder` | `string` | `Search products...`         | Input placeholder text    |

### Environment variable pattern

Store the API key in `.env`:

```
ALANA_API_KEY=ak_your_api_key
```

Then pass it to the component:

```tsx theme={null}
<AlanaSearch apiKey={process.env.ALANA_API_KEY!} />
```

***

## Security Notes

* Use a **search-only API key** — never a service-role key
* The Liquid snippet exposes `window.AlanaShopify` as a frozen object (`Object.freeze`) to prevent prototype pollution
* All HTML from the Alana API (highlight snippets) is sanitized to `<em>` and `<mark>` tags only before rendering