Skip to main content

Install the Website Widget

This guide takes a public website from package installation to a mounted Qanivo conversation. The Widget is a browser client for a configured Website Widget ConnectionInstance. It uses the public installation identity (siteKey) for bootstrap and short-lived session grants for visitor actions.

Prerequisites​

Before loading the Widget, configure the Website Widget connection with:

  • a public site key, for example ww_pk_live_example;
  • the exact HTTPS origin of the site that will load the Widget, such as https://www.example.invalid;
  • a Qanivo API base URL, such as https://api.example.invalid;
  • the public API contract version 1.0.

The allowed-origin policy is enforced by Qanivo. A site key is not a secret and cannot authorize session actions. Local, file, data, JavaScript, malformed, non-HTTPS, and unapproved origins fail closed.

Package installation​

Install the framework-independent package with pnpm:

pnpm add @qanivo/widget

Create and mount one Widget instance:

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

const widget = createQanivoWidget({
  siteKey: '<YOUR_PUBLIC_SITE_KEY>',
  apiBaseUrl: 'https://api.example.invalid',
  storage: 'session',
  locale: 'auto',
});

await widget.mount();
widget.open();

mount() rejects if configuration, origin validation, or session initialization fails. Register error, disabled, visitor.banned, session.expired, and offline.submitted handlers before mounting when the host needs operational feedback.

Script-tag installation​

For plain HTML or a CMS, load the published browser artifact and provide the required data attributes:

<script
  src="https://cdn.example.invalid/widget.js"
  data-qanivo-site-key="<YOUR_PUBLIC_SITE_KEY>"
  data-qanivo-api-base="https://api.example.invalid"
  data-qanivo-locale="auto"
  data-qanivo-locale-parameter="lang"
  data-qanivo-storage="session"
  data-qanivo-persist-ui="true"
  async>
</script>

The script facade auto-bootstraps scripts containing data-qanivo-site-key. It creates the instance, calls mount(), and dispatches qanivo:widget:bootstrap on document with a ready or failed status. The global facade exposes QanivoWidget.getInstance(siteKey), getInstances(), open(siteKey), close(siteKey), toggle(siteKey), and destroy(siteKey).

Use the SRI hash from the package release's dist/integrity-manifest.json when adding integrity and crossorigin="anonymous"; do not substitute a guessed hash. The package-specific SRI and provenance procedure remains in qanivo-widget/INSTALLATION.md.

First successful flow​

  1. Serve the page from its configured HTTPS origin.
  2. Load the package or script tag with the public site key and API base URL.
  3. Call mount() or let auto-bootstrap mount the script-tag instance.
  4. Wait for ready, then open the launcher or call open().
  5. Send a short text message and observe the returned clientOperationId, canonical messageId, and delivery state.

The browser sends X-Qanivo-Widget-Version: 1.0 on public API requests. Session-scoped requests also send Authorization: Bearer <accessGrant>. Side-effecting requests use an Idempotency-Key; the runtime keeps the same key for duplicate-safe retry.

Next steps​