Take the embed widget live

Going live with the embed widget

What you are actually launching

The Fynd embed widget is a script you add to your storefront. Shoppers see a launcher bubble and can open a conversation with your AI product advisor. Answers come from your connected catalog (sitemap, feed, Catalog API) and custom knowledge. The widget talks to Fynd through your embed key: a public credential that may appear in HTML, similar to an analytics site key.

This article is an operational guide: where to place the script, which attributes to set, how to think about PDP versus listing pages, and the mistakes teams most often make before go-live.

Preparation: checklist before you paste code

Complete these steps before putting the snippet on production:

1. Knowledge is ready: at least one sync with products or chunks (check Knowledge or the playground: "Live knowledge active").
2. Bot is configured: persona, welcome text, disclaimer, and suggested prompts are filled in.
3. Playground tests passed: see the separate article on testing before launch.
4. Domain is configured: under Shop settings: primary domain and allowed domains.
5. Embed builder reviewed: position, launcher, and bot slug are correct.

Without knowledge the widget still loads, but answers stay empty or generic. Without the correct domain you will see Origin not allowed in production.

The script snippet: field by field

Open Embed builder (Embed code) in the Fynd dashboard. Choose bot, position, and launcher; the system generates a ready-made snippet. A typical example:

<script
  src="https://your-fynd-domain/widget/fynd.js"
  data-key="pk_live_…"
  data-bot="default"
  data-position="right"
  data-launcher="💬"
  async>
</script>

src: Loads fynd.js from your Fynd installation. Always use HTTPS and your official Fynd domain, not a local copy unless you are deliberately developing.

data-key: Your embed key. Ties chat traffic to your shop. Copy it from Shop settings or the embed page. Do not confuse it with a Catalog API key (sk_live_…); that must never go in the browser.

data-bot: Slug of the bot persona shoppers will talk to. Often default initially. Each additional bot has its own slug (e.g. outdoor, b2b). A wrong slug means a different persona, different prompts, or no bot at all.

data-position: right (default) or left. Controls where the launcher and chat panel appear.

data-launcher: Emoji or short label (max. 8 characters) on the launcher button. Examples: 💬, Help, AI.

data-launcher-icon (optional), URL to an icon image. Replaces the emoji label when you want a brand icon.

async: Loads the script without blocking the page. Recommended on every production page.

You may set data-api in development when testing against another API base; leave it out in production.

Where to place the script

Paste the snippet before </body> on every page where the advisor should be available. Many shops load it site-wide via:

• a theme footer (WooCommerce, Shopify theme.liquid, Magento layout)
• a tag manager (Google Tag Manager); ensure consent tooling does not permanently block the script
• a CMS "custom code" field

Site-wide versus per page type

Site-wide (recommended starting point): One snippet in the footer or global layout. The widget appears everywhere with the same bot. Fynd sends the current page URL with each message (window.location.href), so RAG can use "where the visitor is" as context.

Product detail pages only (PDP): Some teams deliberately start on PDPs to keep a pilot focused. Place the script only in the PDP template. Downside: visitors on category or home pages see no advisor.

Listing and category pages: Useful when shoppers compare options or have not picked a product yet. The same embed works; test questions like "What suits beginners?" or "Difference between model A and B?".

Checkout and account: Usually do not embed unless you explicitly want pre-sale advice there. The launcher can overlap payment buttons or cookie banners. Always test on mobile.

There is no separate "PDP mode" in the script. The difference is where you load it and which URL the visitor has when they type.

Open versus closed by default

On a live storefront the widget starts closed: shoppers see only the launcher bubble; the chat panel opens after a click. That is the default and most common setup, low intrusion, easy entry.

In the playground the widget opens inline immediately so you can test quickly. Do not mimic that on production unless you deliberately use FyndWidget.mount() with open: true via custom JavaScript. For normal script-tag embeds: expect closed by default.

Considerations:

• Closed: Less visual noise; good for broad rollout.
• Programmatic open: Only via custom integration; not needed for standard shops.

Theme colors and appearance

Colors live per bot under Theme: primary, accent, background, text. Defaults are blue/orange on white; adjust to match your brand.

You can also fine-tune colors in the playground under "Appearance". Saving writes to the bot and embed settings (launcher, position, avatar). Check contrast: light text on a light background makes disclaimers unreadable.

Avatar URL: Photo or logo in the chat header. Launcher icon URL: Replaces emoji on the bubble. Host images on HTTPS with reliable delivery; broken URLs fall back to initials.

Fynd branding: On Starter and Growth, branding appears in the chat unless you upgrade to Pro (hide on Pro). Configure this in Embed builder.

Welcome message, disclaimer, and suggested prompts

These fields live under Bot persona → Widget copy, not in the script.

Welcome message: First line in the chat. Briefly explain what the bot does and invite a question. Do not imply a human agent if it is a bot.

Disclaimer: Short notice under the header (e.g. that answers rely on catalog data and may contain errors). No medical or legal claims unless formally approved.

Suggested prompts: Up to eight, one per line. Tappable chips for visitors. Use real shop wording: "Which size fits…?", "Difference between X and Y?", "What is your return policy?"

Fallback when knowledge is missing: Text when RAG finds nothing. Stay honest; refer to support if needed.

Save the persona and reload the widget on your shop to see changes. Browser cache or CDN may delay updated config; hard refresh after major changes.

Mobile testing

The widget is responsive: the panel scales to screen width, the product slider scrolls horizontally. Check on real devices:

• Does the launcher cover your sticky "Buy" button or cookie banner?
• Is the composer reachable with the keyboard open (iOS Safari)?
• Are suggested prompts readable without horizontal scrolling?
• Does the product slider work with touch?

Also test landscape on phones. Left position (data-position="left") can help if you already have WhatsApp chat on the right.

Domain and security

Under Shop → Access & embed:

Primary domain: Reference for page URL in the playground and context.

Allowed domains: Comma-separated list (e.g. shop.com, www.shop.com). Fynd checks Origin/Referer. If your production hostname is missing, the widget fails with Origin not allowed. For local development add localhost; * or empty allows all origins (development only, not production.

Changed domain after migration (www → apex, new TLD)? Update allowed domains before you cut over DNS.

Go-live checklist

Use this list on launch day:

• Embed key in snippet matches the active shop
• data-bot slug exists and is the intended persona
• Allowed domains include production hostname(s)
• Script loads on PDP, category, home, and mobile (Network tab: 200 on fynd.js)
• No duplicate script tags (duplicate launchers)
• Consent/cookie tool does not block the script after acceptance
• Welcome text, disclaimer, and prompts reviewed
• At least five real product questions tested on production (not only playground)
• Product links in answers open the correct PDP
• Lead capture (if enabled) does not ask for unnecessary fields
• APP_DEBUG off on the Fynd server; no stack traces visible to visitors
• Analytics (Growth+); note start date for later comparison

Common mistakes

Wrong domain: Staging key on production or vice versa; or forgot allowed domains after launch. Symptom: widget visible but messages fail. Fix: check domains and key.

Confusing debug mode: Retrieval debug appears in the playground, not on the live shop. Shoppers do not see debug by default. Never put Catalog API keys in theme code "for testing".

Wrong bot slug: Typo in data-bot (defualt) or old slug after a bot rename. Symptom: wrong persona, empty knowledge, or missing bot config. Fix: compare slug in Bots overview with snippet.

Double embed: Script twice in footer plus GTM. Duplicate launchers and events. Fix: one source of truth.

No knowledge: Widget live while sync still running. Fix: wait for sync, test again.

Launcher covers UI: Switch position to left or use a shorter launcher label.

Theme update removes snippet: Document embed location in your runbook; test after every theme deploy.

Pro vs branding expectation: Expecting white label while the plan shows branding. Fix: check plan or branding option in embed builder.

After go-live: first week

• Review analytics (opens, messages, product clicks, leads, unanswered questions) daily in the first week.
• Add FAQs for questions the bot cannot answer.
• Re-run playground scenarios after catalog changes (new collection, price updates).
• Document embed snippet, bot slug per locale/market, and sync owner internally.

The embed is deliberately simple: one script, clear attributes, strong dependence on good knowledge and domain configuration. Teams that manage those tightly get a reliable advisor on every page where shoppers ask for help.