Clueless

Clueless Widget Integration

Launch the Clueless shopping assistant, configure script parameters, and connect your product feed.

Clueless Widget Integration Guide

Bring the Clueless conversational assistant to your storefront in just a few minutes. This guide covers the loader snippet, optional configuration flags, diagnostics, and how to ingest your product catalog so the assistant can answer inventory questions with confidence.

1. Add the loader snippet

Embed the loader script on every page that should host the widget. We recommend placing it as close to the end of the <head> element as possible so it boots as soon as the DOM becomes interactive.

Minimal loader
<script
  async
  data-clueless-widget
  data-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://widget.clueless.chat/widget/loader.iife.js"
></script>

Where to place the script

  • Direct HTML / platforms with template access – Paste the snippet right before </head> in your global layout (e.g. Shopify theme.liquid, WooCommerce header.php, Custom React/Vue SSR template).

  • Google Tag Manager – Create a Custom HTML tag, paste the snippet, trigger on All Pages, and publish. The loader works with both standard and consented container deployments.

  • Single-page applications (React, Vue, Next.js, etc.) – Dynamically inject the script once after hydration:

    const script = document.createElement("script");
script.async = true;
script.setAttribute("data-clueless-widget", "");
script.setAttribute("data-publishable-key", publishableKey);
script.src = "https://widget.clueless.chat/widget/loader.iife.js";
document.head.appendChild(script);

2. Generate a preconfigured snippet

Use the generator to pre-fill optional parameters before handing the code to your developers or agency partners.

Embed Code Generator

<script
  async
  data-clueless-widget
  data-publishable-key="YOUR_PUBLISHABLE_KEY"
  src="https://widget.clueless.chat/widget/loader.iife.js"
></script>

Where to add this code:

  • Direct HTML: Add to your website's <head> section
  • Google Tag Manager: Create a Custom HTML tag with "All Pages" trigger
  • React/Vue/Angular: See the integration guide for framework-specific instructions

3. Loader attributes & query parameters

Customize behaviour by adding data attributes to the <script> tag. All options also support query-string equivalents (e.g. src="...loader.iife.js?tenantId=...").

AttributeTypeDefaultWhen to use
data-publishable-keystringRequiredAuthenticates your storefront. Each environment (production, staging) receives its own key.
data-tenant-idUUID stringAuto-resolves from publishable keyOverride the tenant when running multiple brands under one key or in local sandboxes.
data-server-urlURLAuto (Clueless API)Point the widget to a different Clueless API host (e.g. staging). ?serverUrl=https://api.example.com also works.
data-chat-endpointURL<server-url>/chatProvide a fully qualified chat endpoint if your API uses custom routing or proxies.
data-cssURL path/widget.cssServe a tenant-specific stylesheet for the iframe shell. Useful for brand-specific theming.
data-iframeURL<loader-origin>/app/Override the iframe location (e.g. QA builds hosted on Vercel).
data-debugbooleanfalseEnable verbose console logging. Setting the attribute with no value or data-debug="true" turns logging on; ?debug=1 does the same.
data-ga-id / data-ga-secretstringsnullWire Google Analytics 4 measurement IDs and secrets so widget events forward into your GTM data layer after consent.

Tip: the loader copies all data-* attributes onto its Shadow DOM host. You can safely set custom attributes for your own telemetry as long as they are prefixed with data-.

Publishable key policies

  • Origin allowlists – keys accept an optional comma-separated list of origins (or wildcard subdomains like https://*.example.com). Requests from other origins are rejected with 403 Origin not allowed.
  • Rate limiting – by default we honour the rate limit values stored with the key or fall back to PUBLISHABLE_KEY_RATE_LIMIT_MAX_REQUESTS / PUBLISHABLE_KEY_RATE_LIMIT_WINDOW_SECONDS. Adjust these environment variables before creating new keys or edit the record in the admin CLI to tighten limits.
  • Rotation & revocation – run bun run scripts/create-publishable-key.ts <label> to issue a new key, then call POST /api/publishable-keys/:id/revoke or POST /api/publishable-keys/:id/rotate from an authenticated admin session. Update your storefront snippet with the new value and remove the old key from any GTM containers.
  • Observability – API logs and traces now include publishable_key_id and publishable_key_hash so security teams can monitor usage and detect abuse. Filter logs with publishable_key_id=<UUID> to audit a specific storefront.
  • Environment enforcement – keys prefixed with pk_live_ are only accepted when PUBLISHABLE_KEY_ENVIRONMENT=live. Set the variable in .env.local to force staging environments to reject production keys.

4. Programmatic control and lifecycle events

Once the iframe signals readiness, the loader exposes a controller at window.cluelessWidget:

window.cluelessWidget?.open();
window.cluelessWidget?.close();
window.cluelessWidget?.toggle();
window.cluelessWidget?.postMessage({ type: "PING" });
const context = window.cluelessWidget?.getContext();

Listen for lifecycle events if you need to coordinate UI changes or analytics:

  • clueless-widget-ready – Fired after the iframe confirms it mounted successfully. event.detail.controller contains the same controller instance shown above.
  • clueless-widget-error – Fired if the iframe fails to boot (network errors, authorization, CSP violations).
window.addEventListener("clueless-widget-ready", (event) => {
  console.info("Widget ready", event.detail.controller.getContext());
});

window.addEventListener("clueless-widget-error", (event) => {
  console.error("Widget failed to load", event.detail);
});

5. Verify your installation

  1. Open the site in an incognito window and confirm the chat trigger appears in the lower-right corner.
  2. Click the trigger and ask “Show me something new from your favourite brand” to validate that conversations start.
  3. Open DevTools (top-level browsing context) and run window.cluelessWidget?.getContext() – you should see product/route metadata for the current page.
  4. Check for console warnings or CSP violations; if you see blocked resources, allow requests to widget.clueless.chat and your configured API host.
  5. Inspect your GTM dataLayer for events prefixed with clueless_widget_ when the assistant opens, closes, or navigates.

6. Troubleshooting checklist

  • Widget never appears: verify the script tag includes data-publishable-key, there are no duplicate CSP rules, and the script is not blocked by an ad blocker. Adding data-debug will print loader progress to the console.
  • Stuck in “Authorizing…” – confirm the publishable key is active and the site can reach your Clueless API host (no mixed-content or firewall blocks).
  • Clicking product card links fails: ensure your site permits window.location.* redirects from scripts and that PDP URLs exist in your product feed (see next section).
  • Multiple widgets render: only include one loader snippet per page. Remove older snippets from tag managers or theme partials.

7. Keep the product feed in sync

The assistant relies on a structured product feed so it can recommend in-stock items. Provide at least one of the following to the Clueless team:

  1. Hosted feed URL – We accept Google Merchant-style RSS/Atom XML feeds. Each item should include id, title, description, link, price, availability, image_link, brand, product_type, and gender indicators when available.
  2. Locale configuration – If you sell in multiple markets, supply price/locale multipliers or let us know which currency to prioritize. We normalize prices to cents internally.
  3. Authentication, if required – Share HTTP basic credentials or signed URLs if the feed is not publicly accessible.

Once your feed is ready:

  1. Sign in to the Clueless Merchant Admin and open Catalog → Product Feed.
  2. Paste the secure feed URL, choose the default currency, and save.
  3. We queue the ingestion job immediately—no API calls or emails required.

You can revisit the same screen to see the latest sync status, next scheduled crawl, and any validation errors we detected (missing prices, unreachable images, etc.). Failed rows can be downloaded as a CSV for quick remediation.

8. What happens next?

  • Dashboard analytics will start populating as soon as customers interact with the assistant.
  • You can customize greetings, suggested prompts, and brand priorities from the Clueless dashboard or through your customer success manager.
  • As your product feed changes, e.g. due to changes in inventory or new products being added, the ingestion will re-run using a nightly scheduler, so the assistant always stays up to date.

Still have questions? Reach us at support@clueless.chat – we reply within one business day.

On this page

Clueless Widget Integration Guide1. Add the loader snippetWhere to place the script2. Generate a preconfigured snippet3. Loader attributes & query parametersPublishable key policies4. Programmatic control and lifecycle events5. Verify your installation6. Troubleshooting checklist7. Keep the product feed in sync8. What happens next?