Installation
Add one script tag to your Nuvemshop Admin → Design → Scripts:
<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>
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:
- Finds the Nuvemshop search form via these selectors (in order):
#search-formform[action="/search"]form[action*="search"].search-form- Falls back to
input[name="q"] and traverses to the parent <form>
- Intercepts form submit — calls
POST /api/v1/search instead of native search
- Attaches an autocomplete dropdown to the search input (200ms debounce)
- Renders a product grid in
#alana-search-results at the top of <main>
- Updates the URL to
/search?q=... without page reload (history.pushState)
- 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 |
/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:
// 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);
});
window.AlanaSearch is frozen with Object.freeze to prevent prototype
pollution from third-party scripts on the page.
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
