Skip to main content

Install the Schema Injector

Plans: Starter ✓ · Growth ✓ · Pro ✓ · Agency ✓ (Schema Injector is included on every plan)

The Schema Injector is the small piece of code that puts Clione's JSON-LD structured data into your storefront's HTML so search engines and AI crawlers can read it.

Without it, the enriched JSON-LD lives in Clione's database but never reaches your live store. Crawlers see the same store they always did.

The mechanism is different on each platform — and even on each variant of each platform. This page walks through all of them.

Which path applies to you?​

Your setupWhat to installHow
BigCommerce, Stencil theme (classic / hosted storefront)A managed script tag that Clione installs via BC's Scripts API.One-click from Settings, see below.
BigCommerce, headless / Catalyst (Next.js, Hydrogen-like)The @clione/seo SDK or a direct call to the SEO Signals API.Developer task — see Headless integrations.
Shopify, Online Store theme (any Liquid theme — Dawn, Sense, custom)The Clione theme app block (no script tag).Toggle on in the theme editor, see below.
Shopify, Hydrogen / headlessThe @clione/seo SDK or direct API.Developer task — see Headless on Hydrogen.

If you're not sure whether you're on classic or headless, you almost certainly aren't headless — headless requires a custom-built frontend repo that your developer team deployed separately.

BigCommerce — Stencil (classic storefront)​

Step 1 — Open Settings for the store​

  1. Sidebar → pick the BigCommerce store.
  2. Settings (inside the store, not the global account settings).
  3. Scroll to the Schema Injector card.

The card shows one of three states:

  • Not installed — green install button + a "what this does" note.
  • Installed — installation date, last verified date, link to view the live script on your storefront.
  • Error — usually a credential or scope problem (see Troubleshooting).

Step 2 — Install​

Click Install Schema Injector.

What happens behind the scenes:

  1. Clione creates an internal API key automatically (you don't need to manage it).
  2. Clione calls BigCommerce's Scripts API to register a script_tag of kind src that loads from https://api.clione.ai/embed/schema-injector/<your-store-id>.js.
  3. BigCommerce starts serving that script on every storefront page.
  4. The card refreshes to show the installed state.

The script's job is to fetch the enriched JSON-LD for the current page (detected via OG tags + URL pattern) and inject it into the <head> as <script type="application/ld+json">. Crawlers see it immediately on the next page load.

Step 3 — Verify​

  1. Open any enriched product page in an incognito window.
  2. View page source (Ctrl/Cmd + U).
  3. Search for application/ld+json.
  4. You should see Clione-generated Product schema with the enriched title, description, keywords, and (if reviews are enabled) aggregateRating.

You can also click Preview JSON-LD on the Schema Injector card to see what Clione would inject for a specific page without leaving the dashboard.

Step 4 — Uninstalling​

Click Uninstall on the card. Clione calls BigCommerce's Scripts API to delete the script tag. The card returns to "Not installed". No data is removed on Clione's side — you can re-install at any time.

Notes for BigCommerce​

  • Existing embed.js detected — If Clione finds a manually-installed embed.js script tag on your store (left over from a previous integration), the install flow detects it and asks whether to coexist or replace. The Schema Injector and the FAQ widget render different JSON-LD types (Product vs FAQPage), so they can safely coexist.
  • Comment marker — The injected script is preceded by an HTML comment (<!-- Clione Schema Injector -->) so you can spot it in page source and confirm it's actually rendering.
  • Currency — JSON-LD priceCurrency uses the store currency from BigCommerce's /v2/store endpoint, NOT a hardcoded value. Verify your store's currency is correct under Settings → Store Profile in BC admin.

BigCommerce — headless / Catalyst​

There is no Schema Injector to install — your frontend renders its own <head>. Use the @clione/seo SDK to fetch enriched signals and render them yourself:

import { getSignals } from '@clione/seo'

const signals = await getSignals('product', productId, {
  apiKey: process.env.CLIONE_API_KEY,
  storeId: process.env.CLIONE_STORE_ID,
})

// signals.jsonLd is a ready-to-render Product schema object

See Headless on Next.js for the full integration. The dashboard Schema Injector card will say "Headless channel detected — install not applicable".

Shopify — Online Store (Liquid themes)​

Step 1 — Make sure the Clione custom app is installed​

The theme app block is bundled with the Clione custom app you installed during Connect Shopify. If you skipped the app install or uninstalled it, no app block will appear in your theme editor.

To confirm: Shopify admin → Settings → Apps and sales channels → Develop apps → Clione AI → check that App status is "Installed".

Step 2 — Enable the block in your live theme​

  1. Shopify admin → Online Store → Themes.
  2. Find your live theme → click Customize.
  3. In the theme editor, click the puzzle icon (App embeds) in the left rail.
  4. Scroll to find Clione JSON-LD.
  5. Toggle it on.
  6. Click Save (top-right).

The block targets the <head> region, so the JSON-LD is rendered server-side by Liquid on every page. No JavaScript is needed and crawlers see it on the very first request.

Step 3 — Verify​

  1. Open any enriched product page in an incognito window.
  2. View page source (Ctrl/Cmd + U).
  3. Search for application/ld+json.
  4. You should see Clione-generated Product schema.

If a product hasn't been enriched yet, the metafield is empty and the Liquid block emits nothing — no broken empty script tag. This is intentional.

Step 4 — Enable the block in other themes​

If you swap themes or work in a theme preview, you need to enable the block again — Shopify's app embeds are per-theme, not store-wide.

Notes for Shopify​

  • meta_title and meta_description do NOT require the theme app block. Shopify natively renders those via global.title_tag and global.description_tag in every theme. Only JSON-LD needs the block.
  • No script tag is injected. Unlike BigCommerce, Shopify's JSON-LD is rendered server-side by Liquid reading a metafield. There is no embed.js to install for JSON-LD.
  • Collection and page JSON-LD are planned but not shipped yet. Today only Product schema is rendered by the block. Collections and pages still get meta title and description.

Shopify — Hydrogen / headless​

Same as BigCommerce headless: there is no theme to add the block to. Use the @clione/seo SDK or call the SEO Signals API directly from your frontend.

See Headless on Hydrogen.

Troubleshooting​

BigCommerce​

"Install failed: 422 invalid field [html]" — Historical bug, fixed in the current Schema Injector implementation (uses kind=src instead of inline HTML). If you see this on a fresh install, open a support ticket — your tenant may be pinned to an old release.

"Install failed: 403" — The Content scope on your BigCommerce API token is Read-only or None. The Schema Injector needs Modify to register a managed script. Update the scope on the BC API token, then click Install again.

JSON-LD doesn't appear in page source after install — Open the product page directly (not a category preview) and force a hard refresh (Ctrl/Cmd + Shift + R). The script needs to execute, so it works for crawlers that run JS (Google, Bing, ChatGPT). For non-JS crawlers, the script tag itself is visible in source but the JSON-LD block injected by JS is only there after execution — see Stencil non-JS crawlers for the alternative server-side injection path.

Card shows "Installed" but Verify fails — The script is registered but not running. Common causes: the storefront is password-protected (use a preview code — see Verification doc), or the store is using a custom domain that doesn't resolve. Open the storefront in incognito and confirm it loads at all.

Shopify​

"Clione JSON-LD" not visible in App embeds — The custom app was installed after the theme. Re-install: Shopify admin → Develop apps → Clione AI → API credentials → Uninstall app → Install app. Reload the theme editor and the block should now appear.

Block enabled but no JSON-LD in source — The product is not enriched. Open the product in the Clione dashboard → check Enrichment status → enrich if needed. JSON-LD is only rendered for products with non-empty clione.jsonld metafield.

JSON-LD appears but data looks stale — Shopify metafields are eventually consistent. Allow up to 60 seconds after enrichment for the new value to be reflected on the storefront. If it persists, use the Re-push to storefront button on the product's Propagation tab.

How the BigCommerce Scripts API integration works​

The BC Schema Injector is a single, globally-loaded script registered via BigCommerce's Scripts Manager API. Under the hood:

  • Endpoint: POST /v3/content/scripts with payload { name, src, kind: "src", location: "head", visibility: "all_pages", consent_category: "essential" }.
  • The src URL is https://api.clione.ai/embed/schema-injector/<storeId>.js.
  • The script's job is to (a) detect the page entity by reading the og:type and the path, (b) call Clione's public embed endpoint for the JSON-LD for that entity, and (c) write a <script type="application/ld+json"> block into <head>.
  • An HTML comment marker <!-- Clione Schema Injector --> is printed before the JSON-LD so you can verify presence even if the JSON-LD itself is empty (e.g. for unenriched entities).

Why a src script and not inline HTML​

Earlier versions used inline HTML; BC's Scripts API rejected the field with a 422 in some cases. The current implementation uses kind=src exclusively, which BC accepts without restrictions.

Detection of an existing manual embed.js​

If you previously installed Clione's embed.js manually (older integration path), the Schema Injector install flow detects it and prompts you. The Schema Injector renders Product schema; the manual embed.js renders FAQ and possibly Product schema as well. Choose:

  • Coexist — both run. The Schema Injector deduplicates Product blocks to avoid double-emission.
  • Replace — uninstall the manual embed.js and install only the Schema Injector.

How the Shopify Theme App Extension works​

The Theme App Extension ships in the Clione custom app. Once enabled per theme, it injects three things:

  1. A <meta name="clione:version" content="..."> tag.
  2. An HTML comment marker <!-- clione:jsonld -->.
  3. The JSON-LD block, read from the metafields.clione.jsonld per entity.

Per page type:

  • Product — Product schema, BreadcrumbList, FAQPage (if FAQs exist for the product).
  • Collection — CollectionPage (planned, not shipped).
  • Page — WebPage (planned, not shipped).
  • Article — Article (planned).

Why a Theme App Extension and not a Custom Liquid section​

A Theme App Extension is a Shopify-managed integration that updates without merchants needing to re-paste code. Custom Liquid sections require manual updates every time we ship a schema change. The Extension also survives theme updates — Custom Liquid sections may be wiped on theme reinstalls.

Multi-theme behaviour​

The Extension is enabled per theme, not store-wide. If you preview a different theme, you'll need to enable the Extension in that theme too. The Clione dashboard surfaces a list of themes with their Extension status under Store → Settings → Schema Injector → Themes.

Detection of headless / Catalyst (BigCommerce)​

Clione attempts to detect whether your BC store is using a headless channel (Catalyst, BigCommerce Stencil headless, custom front-end) before showing the Install button. Detection signals:

  • The store has a channel_type of storefront with platform != 'bigcommerce'.
  • The Storefront URL setting points to a non-bigcommerce.com domain that doesn't match the Stencil pattern.

If detected, the Schema Injector card shows a banner: "Headless channel detected — install the @clione/seo SDK instead. See Headless on Next.js."

You can override the detection (rare — only if you have both a Stencil and a headless channel) by clicking Install anyway in the banner.

Per-platform install summary​

PlatformWhat gets installedWhere it goesOne-click install?Removable?
BigCommerce StencilSingle script tag via Scripts APIAll storefront pages, headYesYes (Uninstall button)
BigCommerce Catalyst / headlessNothing — use SDKN/AN/AN/A
Shopify Online StoreTheme App ExtensionAll storefront pages, headOne-click in theme editorYes (toggle off in theme editor)
Shopify Hydrogen / headlessNothing — use SDKN/AN/AN/A