providers-evo-search-sdk

This library was generated with Nx.

Building

Run nx build providers-evo-search-sdk to build the library.

Headless React integration

For headless storefronts (Hydrogen, Next.js, Remix, custom React apps) where the EdgeTag pixel is already installed and the EvoSearch provider is enabled on the tag, this package exports a React hook from the /hooks subpath.

Install:

npm install @blotoutio/providers-evo-search-sdk

Wrap your app once:

import { EvoSearchProvider } from '@blotoutio/providers-evo-search-sdk/hooks'

export default function Root({ children }) {
  return <EvoSearchProvider>{children}</EvoSearchProvider>
}

Use the hook in any search component:

import { useEvoSearch } from '@blotoutio/providers-evo-search-sdk/hooks'

function HeaderSearch() {
  const { query, setQuery, results, suggestions, loading, trackClick } = useEvoSearch()
  return (
    <>
      <input value={query} onChange={(e) => setQuery(e.target.value)} />
      {loading && <span>Loading…</span>}
      <ul>
        {suggestions.map((s) => (
          <li key={s.phrase}>{s.phrase}</li>
        ))}
      </ul>
      <ul>
        {results.map((p) => (
          <li key={p.id} onClick={() => trackClick(p.id)}>
            {p.title}
          </li>
        ))}
      </ul>
    </>
  )
}

Tracking interactions

EvoSearch needs three interaction signals to power the dashboard: searches, result clicks, and cart/purchase events. In a headless integration, only trackClick requires code on your side.

Searches — handled server-side

Search volume, top queries, and zero-result queries are measured automatically from the search API. No client code needed.

Result clicks — trackClick

Call trackClick(productId) when a user clicks a result, passing the id field from the search result:

{
  results.map((p) => (
    <li key={p.id}>
      <button type='button' onClick={() => trackClick(p.id)}>
        {p.title}
      </button>
    </li>
  ))
}

Add-to-cart / purchase — use your existing EdgeTag tags

If you already send EdgeTag AddToCart and Purchase events via the EdgeTag SDK, you're done — EvoSearch receives them server-side and attributes them to searches automatically.

Important: The product id in trackClick must match the product id in your EdgeTag commerce tags. If your commerce tags use SKUs or variant ids, normalize them to product id on both sides, or search-to-cart attribution will report zero.

For full API reference, see the design spec in the Blotout solutions repo or the docs site.

Disabling the default UI (headless mode)

When you want to render search results with your own React components instead of the default Lit custom element, flip Disable default UI in the EvoSearch provider settings (edgetag admin → providers → EvoSearch). With this toggle on:

• The CDN serves a lighter core.min.js bundle instead of index.min.js — no Lit element, no default DOM.
• The React hook from the /hooks subpath continues to work — it reads the EvoSearch API from the same registry the default UI would have used.
• Changes take up to 25 minutes to propagate via the edge cache (max-age=1500 on the /load response).

The EdgeTag pixel must still be loaded on your storefront for the SDK to register and the React hook to receive an API.

/load endpoint cache

CDN responses for /load cache for ~25 minutes (max-age=1500). Toggling Disable default UI in the admin form takes up to that long to propagate across edge nodes — bake the delay into release planning.