Smart Search

Smart Search is an optional bundle under 10 KB gzip for Shopify, WooCommerce, BigCommerce, generic sites, and headless commerce. It uses your public site ID to obtain an origin-bound runtime token. It never sends Typesense credentials or merchant secrets to the browser.

Install the bundle

<script
  defer
  src="https://dashboard.upsur.ge/sdk/upsurge-search.min.js"
  data-site-id="site_replace_me"
  data-base-url="https://dashboard.upsur.ge"
  data-locale="en-US"
></script>

Add the surfaces you need. Keep native markup inside each element so the store remains usable while search loads and when the API is unavailable.

<upsurge-autocomplete search-path="/search">
  <form action="/search" method="get" role="search">
    <label for="native-search">Search products</label>
    <input id="native-search" type="search" name="q">
    <button type="submit">Search</button>
  </form>
</upsurge-autocomplete>

<upsurge-search-results per-page="12">
  <p><a href="/collections/all">Browse all products</a></p>
</upsurge-search-results>

<upsurge-collection-grid slug="trail-favorites" per-page="12">
  <p><a href="/collections/all">Browse all products</a></p>
</upsurge-collection-grid>

The results element reads q from the page URL unless a query attribute is present. It includes brand and category facets, an in-stock filter, sorting, and pagination. Autocomplete starts at two characters, waits 150 ms, cancels superseded requests, and supports Arrow Up, Arrow Down, Enter, and Escape.

Published same-origin keyword redirects are followed automatically. Listen for the cancelable upsurge:smart-search-redirect event or set follow-redirects="false" when a client-side router owns navigation.

Headless API

Use the exported client when your storefront owns the renderer:

const client = new window.UpsurgeSearch.Client({
  siteId: 'site_replace_me',
  baseUrl: 'https://dashboard.upsur.ge',
  personalizationConsent: () => consentManager.allowsPersonalization(),
});

const result = await client.search({
  q: 'waterproof trail shoes',
  page: 1,
  per_page: 12,
  sort: 'relevance',
  facets: ['brand', 'categories'],
  filters: { in_stock: true },
});

const collection = await client.queryCollection('trail-favorites', {
  page: 1,
  per_page: 12,
});

client.trackResultClick(result, result.products[0], 1);

The client also exposes getCollection. Pass {signal} as the second argument to cancel a search or collection request.

Analytics and privacy

If the core SDK is already available as window.upsurge, search automatically uses its device, session, and merchant user IDs. Current trackers receive canonical search, search_result_click, smart_collection_impression, and smart_collection_click events; older tracker versions use the compatible trackSearch and smart_search_result_click fallback. A queryless Smart Collection browse emits its collection impression without inventing a blank search event. Equivalent upsurge:smart-search-search, upsurge:smart-search-result_click, and collection-impression DOM events are dispatched for custom analytics listeners.

The SDK retries transient transport and server failures. If the Events API rejects a batch as invalid, the SDK reports the error through onError and discards that rejected batch so it cannot block later events.

Personalization context is sent only when personalizationConsent returns true. Upsurge redacts queries before analytics persistence and shows aggregate query reporting only after five distinct sessions. Do not add email, secrets, or arbitrary customer traits to search callbacks.

Platform setup

Shopify

Add the Upsurge Smart Search theme app block and choose Autocomplete, Search results, or Smart Collection. The app proxy supplies the linked site ID and API origin. Liquid-rendered forms and product links remain as fallbacks.

WooCommerce

Enable Smart Search in the Upsurge plugin, then insert the Upsurge Smart Search block or use a shortcode:

[upsurge_smart_search mode="autocomplete"]
[upsurge_smart_search mode="results" per_page="12"]
[upsurge_smart_search mode="collection" slug="trail-favorites"]

BigCommerce

Load the bundle through Script Manager in the footer and place the elements in Stencil templates. Keep the existing Stencil search form or catalog grid as the element's child fallback.

Generic, headless, and SSR

Use the script install on any HTTPS merchant site and register every production or preview origin. For SSR, call the storefront endpoints from your server using a site-scoped secret with search:read, render a native first response, and use the public browser client for later interactions. Never serialize the server secret into HTML or hydration data.

Accessibility and customization

The components use Shadow DOM, visible focus rings, 44-pixel primary controls, live loading/error announcements, responsive grids, and reduced-motion safeguards. Built-in labels support English, Spanish, French, and German.

Override visual tokens from merchant CSS:

upsurge-search-results {
  --upsurge-search-font: "Inter", sans-serif;
  --upsurge-search-action: #172033;
  --upsurge-search-action-text: #fff;
  --upsurge-search-focus: #2457ff;
  --upsurge-search-radius: 10px;
}

The site must return the search:read capability and have Smart Search enabled with a healthy index and published configuration before browser requests succeed.