Widget — Troubleshooting

Quick checks for common widget integration issues.

Troubleshooting

A guided walk-through. Open your browser's DevTools console before testing — most issues surface as a clear warning starting with [Skryx Widget].

# Widget doesn't appear at all

Check the snippet loaded:

typeof window.SkryxWidget
// → "object" if loaded; "undefined" if the script didn't run

If undefined:

  • Make sure the <script> tag is in the page (View Source — Find "skryx").
  • Check the URL is exactly https://cdn.skryx.io/widget.js (no typos).
  • Check your CSP allows script-src https://cdn.skryx.io.

Check the target input was found:

document.querySelector('YOUR_DATA_TARGET_VALUE')
// → an element, or null if the selector doesn't match

If null, fix the data-target selector. Open the search field in DevTools, right-click → Copy → Copy selector — paste that into data-target.

The widget is talking to your account but the query returned nothing. Common causes:

  • Wrong index — in Search Widget → Catalogue, ensure the right index is selected (tenants with multiple indexes default to the first).
  • Empty index — Auto-Pilot might still be running. Check Indexes → [your index] → Documents count.
  • Schema field mismatch — your products live under a field name we don't auto-detect. The widget pulls title from title / name, image from image_url / image / thumbnail / photo, price from price / price_value, URL from url / permalink / product_url. Rename / alias the field in your import pipeline, or contact support to add your bespoke field to the auto-detect list.

# "401 SK-WG-401" or "403 SK-WG-403" in DevTools

Auth failure. In API Keys, confirm:

  • The key starts with pk_live_ (not sk_admin_ or sk_live_).
  • The key is not revoked (status column shows green).
  • Allowed origins includes the EXACT origin showing in the request (scheme + host + port). https://www.shop.com ≠ https://shop.com. Add both if you serve on apex + www.

# Categories column is empty even though I have categories

The widget needs a schema field literally named category, categories, category_name, cat, collection, or product_type. If your tenant uses a different field name (e.g. cat_path), open Indexes → schema and either:

  • Rename the field, or
  • Add an alias via the schema API (the original keeps working)

Per-tenant category field will be a configurator setting in v2.

You're on the Free plan. The footer is forced on for Free tenants and removable on Starter and up — upgrade in Settings → Plan. Your preference is preserved across upgrade / downgrade.

# Multiple dropdowns appear at once

Your platform (Shopify, WooCommerce) probably has a built-in predictive search that's also firing. Disable it:

  • Shopify — DevTools → Network → search for /search/suggest.json → matches a predictive-search element. Hide via CSS: predictive-search { display: none; }
  • WooCommerce — Settings → Products → General → uncheck "Product search". Or CSS-hide .woocommerce-search-results.

# Widget renders behind another element

Probably a z-index collision with a sticky header. The widget host element uses z-index 2147483640 (max minus a few). If something on your page sits above that, lower it. Last-resort override:

[data-skryx-widget] { z-index: 2147483647 !important; }

# Latency feels slow (>500ms per keystroke)

  • First keystroke on a brand-new prefix is always slower because the suggestion cache is cold (Redis). Subsequent uses of the same prefix are near-instant.
  • Bigger budget: the widget search backend targets <50ms p95 on warm cache. If you consistently see 500ms+, file a ticket with a HAR file — likely a network path issue (cdn vs api routing) or a tenant index missing a hot column.

# Changes in the configurator don't show up

The widget caches its config in localStorage for 1 hour. Hard-refresh (Cmd+Shift+R / Ctrl+F5), or run from DevTools:

window.SkryxWidget.reload();

This clears the local cache and re-fetches.

# I'm still stuck

Email support@skryx.io with:

  1. The HAR file from your DevTools Network tab (capture a failing keystroke)
  2. The output of window.SkryxWidget.config from the console
  3. The store URL where the widget runs

Response within 4h on Pro+, 1h on Scale+.

esc