Configuration

Control behavior, styling, and catalog strategy.

The widget API is intentionally small. Most retailers configure it once in the storefront theme and let Sillage handle recommendation quality, localization, and attribution.

Initialization options

Name	Type	Required	Default	Description
containerId	string	No	-	ID of the DOM element where the widget mounts. Omit only when using floating app-snippet mode.
apiKey	string	Yes	-	Your sw_test_* or sw_live_* widget key.
locale	'en' \| 'ar'	No	ar	Widget language and reading direction.
theme	'light' \| 'dark' \| 'auto'	No	auto	Visual theme for the widget UI.
mountMode	'inline' \| 'floating'	No	inline	Use 'floating' for app-store snippets that should create their own storefront mount.
catalog	'auto' \| MerchantProduct[]	No	auto	'auto' uses products connected to the API key. Pass an array only when this page should recommend from its own product list. Merchants only need product identity; Sillage enriches scent data.
apiBaseUrl	string	No	script origin	Override only for previews or self-hosted API environments.
style.primaryColor	#RRGGBB	No	-	Accent color. Low-contrast values fall back to Sillage gold.
style.borderRadius	string	No	-	Controls widget shape for cards, buttons, and pills. Use a CSS value such as 16px.
style.fontFamily	string	No	-	Optional font stack inherited by the widget.
style.displayFontFamily	string	No	-	Optional font stack for display headings.
style.backgroundColor	#RRGGBB	No	-	Optional widget background color.
style.surfaceColor	#RRGGBB	No	-	Optional card and panel surface color.
style.textColor	#RRGGBB	No	-	Optional primary text color.
branding.enabled	boolean	No	-	Opt into merchant branding. Requires a logo URL.
branding.logoUrl	string	No	-	Merchant logo URL shown in the launcher, entry, loading, and empty states.
branding.eyebrowText	string	No	-	Optional replacement for the entry screen eyebrow label.
branding.launcherText	string	No	-	Optional floating launcher label.
branding.ctaText	string	No	-	Optional replacement for the entry CTA.
branding.resultsCta	string	No	-	Optional replacement for the powered-by footer CTA. Powered by Sillage remains visible.
onRecommendation	(results) => void	No	-	Callback after recommendations are returned.
onProductClick	(product) => void	No	-	Callback before opening a product URL.

Product source: connected catalog vs page products

Decision	Connected catalog	Page products
What it means	The widget recommends from products already linked to this API key.	The page sends a product list directly when it initializes the widget.
Best for	Main storefronts and production launches with stable inventory.	Demos, seasonal edits, landing pages, or headless pages with a small product set.
Recommendation quality	Best: Sillage matches and enriches products from its perfume database.	Good: Sillage matches product identity first; accords and notes are optional hints only.
Maintenance	Keep the connected catalog updated when inventory changes.	The widget only sees the products passed on that page load.

Page products example

Pass page products

SillageWidget.init({
  containerId: 'sillage-widget',
  apiKey: 'sw_test_your_key',
  catalog: [
    {
      merchant_product_id: 'oud-velvet-50ml',
      name: 'Velvet Oud',
      house: 'Maison Parfum',
      price: 420,
      currency: 'SAR',
      product_url: 'https://store.example/products/velvet-oud'
    }
  ]
});

Merchant branding example

Merchant branding is opt-in. When enabled, the merchant logo appears in the widget chrome and the footer switches to a quieter attribution while still showing Powered by Sillage.

White-label the widget chrome

SillageWidget.init({
  containerId: 'sillage-widget',
  apiKey: 'sw_live_your_key',
  theme: 'auto',
  branding: {
    enabled: true,
    logoUrl: 'https://store.example/logo.svg',
    eyebrowText: 'Maison Parfum',
    launcherText: 'Find your scent',
    ctaText: 'Start scent finder',
    resultsCta: 'View your Sillage profile',
    style: {
      primaryColor: '#8a5a30',
      backgroundColor: '#fffaf2',
      surfaceColor: '#ffffff',
      textColor: '#1c1711',
      displayFontFamily: 'Georgia, serif'
    }
  }
});