Skip to main content

Embed widget

The embed widget is a single <script> tag that injects FAQ content + JSON-LD into any storefront page.

Basic usage​

<div id="clione-faq"></div>
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target="#clione-faq"
  async
></script>

That's it. The script:

  1. Detects the current entity (product / category / page) automatically
  2. Fetches FAQs from Clione's public API
  3. Injects a visible HTML accordion into #clione-faq
  4. Injects an invisible <script type="application/ld+json"> with FAQPage schema into <head>

How context is detected​

The embed script defers all detection to DOMContentLoaded to ensure platform globals (like BigCommerce's window.BCData) are available. On BC Stencil pages, it retries up to 3 times with 500ms delay if BCData isn't populated yet.

Priority order:

  1. Explicit override on the script tag:

    <script
      src="https://api.clione.ai/embed.js"
      data-api-key="sk_live_..."
      data-entity-type="product"
      data-entity-id="SKU-001"
    ></script>

  2. BigCommerce detection (checked before URL patterns):

    • window.BCData.product_attributes.product_id — most reliable for BC Stencil
    • [data-product-id] DOM attribute — BC Stencil product containers
    • [data-category-id] DOM attribute — BC Stencil category pages

  3. OpenGraph meta tags — if the page has:

    <meta property="og:type" content="product">
    <meta property="product:retailer_item_id" content="SKU-001">

    the widget picks them up.

  4. URL patterns:

    • Shopify: /products/:handle, /collections/:handle, /pages/:handle
    • BigCommerce: /products/:slug, /product/:slug, /categories/:slug, /category/:slug
    • WooCommerce: body class .single-product + postid-N

  5. If no context is detected, the widget logs to the console and renders nothing.

Security​

The API key is public in the script tag — don't put an admin-scoped key there. Use products:read scope only.

The key is validated on every request against its allowedDomains whitelist (Origin / Referer). Requests from non-whitelisted origins return 403.

Styling​

The accordion supports CSS custom property overrides via data-style-* attributes on the script tag:

<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target="#clione-faq"
  data-style-accent="#6C63FF"
  data-style-bg="#FFFFFF"
  data-style-fg="#1A1A2E"
  data-style-border="#E0E0E0"
  data-style-radius="8px"
  data-style-font="'Inter', sans-serif"
  data-style-font-size="14px"
  data-style-spacing="12px"
  data-style-theme="minimal"
></script>

All style attributes are optional. The storefront's own CSS provides defaults for any unset properties.

BigCommerce Script Manager​

When adding the embed script via BC Script Manager, use the Essential category. Non-Essential categories (Functional, Analytics) wrap scripts with type="text/plain" + data-bc-cookie-consent, which prevents execution entirely until the shopper accepts cookies.

Debugging​

Console logs​

Open the browser console and filter for [Clione]. The widget logs its progress:

[Clione] embed.js: fetching FAQ for product/123 (detected via bc-window)
[Clione] embed.js: rendered 5 FAQ entries for product/123 (detected via bc-window)

Check JSON-LD injection​

// List all JSON-LD blocks on the page
document.querySelectorAll('script[type="application/ld+json"]').forEach((el, i) => {
  console.log(`--- Block ${i} ---`);
  console.log(JSON.parse(el.textContent));
});

Look for a FAQPage type in the output. If Clione's embed script injected it, it will be a standalone FAQPage block in <head>.

Find the rendered FAQ element​

document.querySelector('.clione-faq')

If null, the FAQ widget didn't render. Check the console logs for errors.

Test signal endpoints​

Every enriched entity exposes four signal formats:

GET /api/v1/{platform}/products/{id}.jsonld   → JSON-LD (application/ld+json)
GET /api/v1/{platform}/products/{id}.llm      → LLM-optimized JSON
GET /api/v1/{platform}/products/{id}.md       → Markdown (text/markdown)
GET /api/v1/{platform}/products/{id}.meta     → All signals + links to other formats

The .meta endpoint returns a links object pointing to all other formats — use it as the discovery entry point.

Troubleshooting checklist​

If nothing renders:

  • BC Stencil: Is the script in the Essential category in Script Manager? Non-Essential scripts don't execute.
  • BC Stencil: Does window.BCData exist? Open Console and type BCData. If undefined, the script retries 3 times — check for retry logs.
  • All platforms: Is the API key valid? Check for HTTP 403 in the Network tab.
  • All platforms: Is the current domain in the key's allowedDomains whitelist?
  • All platforms: Are there approved FAQ entries for this entity in the Clione dashboard?
  • Fallback: Add explicit data-entity-type + data-entity-id attributes to bypass auto-detection.