Skip to main content

Configure the Website Widget

The Widget has two configuration layers. Qanivo owns connection configuration such as allowed origins, capabilities, limits, retry policy, navigation policy, and media policy. The browser package accepts bounded presentation, locale, storage, identity-provider, page-context, and host integration options. Browser options do not grant permissions or replace server policy.

Runtime options​

This is a complete starting point for a typed integration:

import { createQanivoWidget } from '@qanivo/widget';

const widget = createQanivoWidget({
  siteKey: '<YOUR_PUBLIC_SITE_KEY>',
  apiBaseUrl: 'https://api.example.invalid',
  storage: 'session',
  persistUiState: true,
  locale: 'auto',
  localeParameter: 'lang',
  pageContext: {
    enabled: true,
    allowedQueryKeys: ['lang', 'article'],
    redactedQueryKeys: ['token', 'code'],
    includeHash: false,
    includeReferrer: false,
    reportOnChange: true,
    custom: { application: 'customer-portal' },
  },
  assetAllowedDomains: ['media.example.invalid'],
  requestTimeoutMs: 15_000,
  streamConnectTimeoutMs: 20_000,
});

await widget.mount();

storage: 'session' keeps short-lived continuity, UI state, and drafts scoped to the current browser tab. Use memory when the host does not want browser persistence. The browser package does not support localStorage for Widget continuity.

Locale and direction​

Locale resolution is:

  1. an explicit runtime locale, unless it is auto;
  2. the permitted URL parameter, defaulting to qanivoLocale when configured;
  3. the document language and metadata;
  4. the browser language list;
  5. the configured Widget fallback.

Any bounded BCP 47 locale tag may be used. Translation dictionaries use stable keys and are validated for shape and size. Direction is inferred for recognized RTL languages and may be explicitly set with direction. Keep URLs, identifiers, timestamps, and other technical values direction-safe; do not localize them as display prose.

Appearance and launcher​

Appearance is token-based. Arbitrary HTML and arbitrary CSS are not accepted from public configuration. The connection can provide bounded colors, typography, panel dimensions, logo, launcher position, label, icon, shape, and offsets. Supported launcher positions are bottom-right, bottom-left, top-right, and top-left.

{
  "appearance": {
    "theme": "system",
    "primaryColor": "#5b4bdb",
    "surfaceColor": "#ffffff",
    "textColor": "#172033",
    "headerTextColor": "#ffffff",
    "fontFamily": "system-ui, sans-serif",
    "headerTitle": "Customer support",
    "launcherPosition": "bottom-left",
    "launcherDisplay": "icon-label",
    "launcherLabel": "Need help?",
    "launcherIcon": "support",
    "launcherShape": "rounded",
    "launcherSize": 62,
    "launcherOffsetX": 24,
    "launcherOffsetY": 24
  }
}

The runtime still applies contrast, viewport, touch-target, reduced-motion, RTL/LTR, and safe-value validation. Backend configuration can disable the feature or narrow its bounds.

Page context​

Page context is optional, bounded, and untrusted. It may include a normalized URL, path, title, locale, direction, viewport, and explicitly allowed scalar values. Query values are excluded unless their exact names are listed in allowedQueryKeys; sensitive names remain blocked. Hashes, referrers, tokens, credentials, private fragments, and arbitrary DOM content are excluded by default.

await widget.updatePageContext({
  section: 'billing',
  article: 'getting-started',
});

Page context cannot change identity, permissions, routing authority, AI mode, or security policy.

Media and asset hosts​

Images, videos, screenshots, stickers, posters, and Lottie assets must come from an explicit backend or developer host allowlist. Prefer the backend assetPolicy.allowedDomains configuration. A browser-side assetAllowedDomains value can add visitor-safe hosts; it must not be used to broaden a server policy unintentionally.

{
  "assetPolicy": {
    "allowedDomains": ["media.example.invalid"],
    "allowDataImages": false
  },
  "media": {
    "viewer": {
      "enabled": true,
      "images": true,
      "videos": true,
      "screenshots": true,
      "allowDownload": false
    }
  }
}

Data images require explicit opt-in and remain size/type bounded. Asset URLs must not contain Widget grants, provider credentials, or unrestricted long-lived signatures.

Script-tag attributes​

The auto-bootstrap path accepts data-qanivo-site-key, data-qanivo-api-base, data-qanivo-locale, data-qanivo-direction, data-qanivo-locale-parameter, data-qanivo-storage, data-qanivo-persist-ui, data-qanivo-auto-open, data-qanivo-target, and data-qanivo-style-nonce. Invalid storage values fail explicitly. A style nonce is only needed for the legacy stylesheet fallback; modern browsers use adopted stylesheets.

See sessions and identity for server-generated identity assertions and security and production for CSP, host isolation, and accessibility controls.