Skip to main content

Install the FAQ widget on your storefront

The Clione FAQ widget is a single <script> tag that injects:

  1. A visible HTML accordion of FAQs on the page, so shoppers can read them.
  2. An invisible FAQPage JSON-LD block in the page <head>, so search engines and AI crawlers can index them.

The widget auto-detects the current entity (product, category, page) and pulls the right FAQs from Clione — including any global FAQs you've defined (shipping, returns, warranty).

To author FAQs, see FAQ editor. This page is only about installing the widget on the storefront once the FAQs exist.

Before you install​

  1. You need an API key with products:read scope and at least one allowed domain whitelisted. Generate it under Store → Settings → API Keys (see FAQ editor).
  2. Decide where on the page the FAQ accordion should appear. Most stores put it directly under the product description, above related products.
  3. Plan-gated: the FAQ feature is available on Growth and above. Starter accounts can enrich and propagate, but cannot use the FAQ editor or widget.

BigCommerce — Stencil (classic storefront)​

Option A — Edit your theme​

  1. BigCommerce admin → Storefront → Themes → click Advanced → Edit theme files on your active theme.
  2. Open templates/components/products/product-view.html (path varies slightly by theme — search for {{description}} to find the product description block).
  3. Paste the snippet right after the description block:
<div id="clione-faq"></div>
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target="#clione-faq"
  async
></script>
  1. Click Save at the top right. Stencil rebuilds the theme. The widget appears on every product page within ~30 seconds.

For category pages: open templates/pages/category.html and add the same snippet. The widget auto-detects category context.

Option B — Use BC's Script Manager (no theme edit)​

Useful if you don't want to touch the theme but accept that the widget appears in a fixed location (usually the footer).

  1. BigCommerce admin → Storefront → Script Manager → Create a Script.
  2. Name: Clione FAQ widget.
  3. Description: Renders FAQ accordion + FAQPage JSON-LD.
  4. Location on page: Footer.
  5. Select pages where script will be added: Storefront pages → pick Product pages (and Category pages if you want).
  6. Script type: Script.
  7. Script contents:
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target=".productView, .category"
  async
></script>
  1. Save.

The data-target CSS selector tells the widget where to inject the accordion. .productView works for most Stencil themes on product pages; .category for category pages.

Verify​

  1. Open any enriched product page in incognito.
  2. Scroll to find the FAQ accordion below the description.
  3. View source (Ctrl/Cmd + U) and search for FAQPage — you should see the JSON-LD block.
  4. If the accordion didn't appear, check the browser console for errors (most often: API key not whitelisted for this domain — see Troubleshooting).

BigCommerce — headless / Catalyst​

Same as the Schema Injector: render server-side from your frontend. Use the FAQ API directly:

const res = await fetch(`https://api.clione.ai/api/v1/public/faq/render?entityType=product&entityId=${productId}`, {
  headers: { 'x-api-key': process.env.CLIONE_API_KEY },
})
const { htmlBlock, jsonLd } = await res.json()
// htmlBlock → render in your product page
// jsonLd → render in <head>

See FAQ API for the full spec.

Shopify — Online Store (Liquid themes)​

Option A — Edit your theme​

  1. Shopify admin → Online Store → Themes → on your live theme, click the three-dot menu → Edit code.
  2. Open sections/main-product.liquid (or templates/product.liquid on older themes).
  3. Find the product description block (search for {{ product.description }}).
  4. Paste the snippet right after:
<div id="clione-faq"></div>
<script
  src="https://api.clione.ai/embed.js"
  data-api-key="sk_live_..."
  data-target="#clione-faq"
  async
></script>
  1. Click Save. The widget appears on every product page immediately.

For collection pages: open sections/main-collection-product-grid.liquid (or similar) and paste the same snippet. For content pages: sections/main-page.liquid.

Option B — Use the theme editor (no code)​

If your theme supports custom HTML blocks (Dawn does, most paid themes do):

  1. Theme editor → open a product template → Add block → Custom Liquid (or Custom HTML).
  2. Paste the snippet from above.
  3. Save.

The widget appears wherever the block is placed in the section order. You can drag it up/down to position above or below related products.

Verify​

  1. Open any enriched product page in incognito.
  2. The FAQ accordion should appear in the slot you chose.
  3. View source and search for FAQPage JSON-LD.

Notes for Shopify​

  • The FAQ widget is independent of the Clione theme app block. The app block handles Product JSON-LD; the FAQ widget handles FAQPage JSON-LD. Both can be active without conflict.
  • The widget injects its accordion into the DOM via JavaScript, so server-rendered crawlers (Googlebot now executes JS, but old crawlers don't) will not see the accordion text. They WILL see the FAQPage JSON-LD because the widget inserts it into <head> before any first paint — but if you need server-rendered FAQ text, switch to the FAQ API and render in Liquid yourself.

Shopify — Hydrogen / headless​

Same as BigCommerce headless. Use the FAQ API directly from your Hydrogen route loader and render both the accordion HTML and the JSON-LD in your component.

Common to both platforms​

Allowed domains​

The API key validates the request's Origin header against the Allowed Domains list you set when generating the key. If the widget tries to load on a domain not in the list, the API returns 403 and nothing renders.

  • For production: list your real storefront domain (shop.example.com or example.com).
  • For staging: include the staging domain (staging.shop.example.com) or use wildcards (*.example.com).
  • For local testing: add localhost and 127.0.0.1.

Update the whitelist any time under Store → Settings → API Keys → Edit domains on the key row.

"Powered by Clione" badge​

The widget shows a small Powered by Clione badge at the bottom of the accordion by default.

  • On Growth, Pro, and Agency plans you can hide the badge from Org → Settings → Branding.
  • On Starter and during the trial, the badge is forced on and the toggle is disabled. This is documented in our Terms of Service.

Auto-detection of the current entity​

The widget tries detection in this order:

  1. Explicit override on the script tag (data-entity-type + data-entity-id) — use this if your platform doesn't expose recognizable URLs or OG tags.
  2. OpenGraph meta tags — <meta property="og:type" content="product"> + <meta property="product:retailer_item_id" content="...">.
  3. URL patterns — Shopify /products/<handle>, BigCommerce /product/<slug>, WooCommerce body class, etc.

If detection fails, the widget falls back to showing only global FAQs (shipping, returns, etc.) and skips entity-specific ones. To force entity detection on a custom theme, use the explicit override:

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

(Replace {{ product.id }} with whatever templating syntax your platform uses.)

Troubleshooting​

"403 Forbidden" in the browser console — The current page's domain isn't in the API key's allowed domains list. Update the list under Store → Settings → API Keys.

Accordion appears but JSON-LD doesn't — Race condition. The JSON-LD is added to <head> slightly after first paint on slow connections. Reload and check again.

Accordion is empty for some products but full for others — The empty ones have no FAQs assigned. Open the product in Clione → FAQs tab → add at least one entity-specific FAQ, or rely on global FAQs only.

Widget shows "Powered by Clione" but I'm on Pro — Hard refresh after toggling the branding off; the widget caches the policy for 5 minutes. If it persists, check Org → Settings → Branding — the toggle might not have saved.

On BigCommerce Stencil, the widget loads but the JSON-LD doesn't include the product context — Stencil's BCData global sometimes isn't ready when the widget runs. The widget retries up to 3 times with 500ms delay, so this is usually transparent — but if you see this on a custom theme, ensure the script is loaded async (not defer), AFTER the page's main JS bundle.