Pular para o conteúdo principal

​
Two Integration Paths

PathBest forFile
Liquid snippetOnline Store 2.0 themes (standard)alana-predictive-search.liquid
Hydrogen componentHeadless Hydrogen storefrontsAlanaSearch.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: 
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:
SettingValue
alana_api_keyYour ak_xxx API key
alana_api_urlhttps://app.alana.shopping
Or set directly in config/settings_data.json: 
{
  "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: 
{% 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

cp adapters/shopify/components/AlanaSearch.tsx app/components/AlanaSearch.tsx

​
Step 2 — Use in a route

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

PropTypeDefaultDescription
apiKeystringrequiredYour Alana search API key
apiUrlstringhttps://app.alana.shoppingAPI base URL
hitsPerPagenumber20Results per search
placeholderstringSearch 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: 
<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
Last modified on March 12, 2026