> ## 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.

# Nuvemshop Installation

> Add Alana Search to any Nuvemshop store with a single script tag

## Installation

Add one script tag to your Nuvemshop Admin → **Design → Scripts**:

```html theme={null}
<script
  src="https://cdn.alana.shopping/nuvemshop/alana-search-snippet.js"
  data-api-key="ak_your_api_key"
  data-api-url="https://app.alana.shopping">
</script>
```

That's it. The snippet automatically initializes on `DOMContentLoaded`.

## Configuration

| Attribute      | Required | Default                      | Description               |
| -------------- | -------- | ---------------------------- | ------------------------- |
| `data-api-key` | ✅ Yes    | —                            | Your Alana search API key |
| `data-api-url` | No       | `https://app.alana.shopping` | API base URL              |

## How It Works

The snippet:

1. Finds the Nuvemshop search form via these selectors (in order):
   * `#search-form`
   * `form[action="/search"]`
   * `form[action*="search"]`
   * `.search-form`
   * Falls back to `input[name="q"]` and traverses to the parent `<form>`
2. Intercepts form submit — calls `POST /api/v1/search` instead of native search
3. Attaches an autocomplete dropdown to the search input (200ms debounce)
4. Renders a product grid in `#alana-search-results` at the top of `<main>`
5. Updates the URL to `/search?q=...` without page reload (`history.pushState`)
6. Restores search state on direct navigation to `/search?q=...`

## Autocomplete

The dropdown appears after 2+ characters and shows up to 5 suggestions from `/api/v1/autocomplete`. Each suggestion shows the search term and result count. Clicking a suggestion performs an immediate search.

## Event Tracking

The snippet tracks:

| Event              | Trigger                      |
| ------------------ | ---------------------------- |
| `search`           | After each successful search |
| `detail-page-view` | On product card click        |

Events are sent to `/api/v1/events` with a persistent visitor ID stored in `localStorage` under `_alana_vid`.

## Programmatic API

The snippet exposes a frozen global for programmatic use:

```javascript theme={null}
// Trigger a search programmatically
window.AlanaSearch.search("tênis running", 0, 20);

// Get autocomplete suggestions
window.AlanaSearch.autocomplete("tênis").then(({ suggestions }) => {
  console.log(suggestions);
});
```

<Note>
  `window.AlanaSearch` is frozen with `Object.freeze` to prevent prototype
  pollution from third-party scripts on the page.
</Note>

## Troubleshooting

**`[Alana Search] No search form found`**

* Your theme doesn't use a standard search form selector
* Add `name="q"` to your search input, or contact Alana Support with your theme name

**Autocomplete not appearing**

* Confirm the script tag is loading (check Network tab in browser DevTools)
* Check the browser console for `[Alana Search] Initialized successfully.`

**Products show "No image"**

* Ensure products in your catalog have `image_url` set
* Trigger a catalog sync from Workspace → Products → Sync