Embed in your app

The widget installs with one script tag, and everything on this page builds on it: which key to use, how to load it in a single-page app, how to mount it inline instead of floating, and what a strict Content-Security-Policy needs to allow.

Get your embed key

The widget authenticates with a publishable key. Publishable keys are safe to ship in your page source — they identify your workspace but hold no secret capability.

1. 1
   Open API keys in the dashboardGo to Settings → API keys in your workspace dashboard.
2. 2
   Copy the publishable keyCopy the key that starts with pk_test_ for development or pk_live_ for production — never a secret gak_ key, which belongs on your server only.
3. 3
   Match the key to the environmentThe widget infers the environment from the key’s prefix; add data-env only when you need to override it explicitly.

The script tag

Paste the tag right before the closing body tag of every page the assistant should appear on. It must keep type="module" — the widget is an ES module and fails to load without it.

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_test_..."
  data-position="bottom-right"
  data-env="development"
></script>

That’s the whole install: the launcher appears in the chosen corner, and everything else is designed in the dashboard. The full list of attributes lives in the configuration reference.

React, Vue, and other single-page apps

In a single-page app the simplest install is still the static tag in your index.html — the widget survives client-side navigation on its own. If you prefer to control mounting from your component tree, inject the script in an effect and unmount on cleanup:

import { useEffect } from 'react';

export function SyncanixWidget({ embedKey }: { embedKey: string }) {
  useEffect(() => {
    const script = document.createElement('script');
    script.type = 'module';
    script.src = 'https://cdn.syncanix.com/widget.js';
    script.setAttribute('data-key', embedKey);
    document.body.appendChild(script);
    return () => {
      window.syncanix?.unmount();
      script.remove();
    };
  }, [embedKey]);
  return null;
}

The same pattern works anywhere with a mount and cleanup hook — onMounted/onUnmounted in Vue, ngOnInit/ngOnDestroy in Angular, onMount in Svelte.

Mount inline instead of floating

By default the widget floats as a launcher in a page corner. To place the chat inside your own layout — a help panel, a sidebar, a full page — use data-chat-size="embedded" and point data-mount-target at a CSS selector for the container the widget should fill:

<div id="assistant-panel"></div>

<script
  type="module"
  src="https://cdn.syncanix.com/widget.js"
  data-key="pk_live_..."
  data-chat-size="embedded"
  data-mount-target="#assistant-panel"
></script>

Send your user’s identity

Without identity the assistant treats every visitor as anonymous. To let it act as the signed-in user, register a token provider — the widget calls it before each turn, so a refreshed token is always sent. The full setup for every auth mode lives in authenticating your users.

window.syncanix?.setTokenProvider(async () => {
  // Called before each turn — return the signed-in user's current token.
  return auth.getTokenSilently();
});

Content-Security-Policy requirements

If your site ships a strict CSP, allow these three things before you embed:

script-src  https://cdn.syncanix.com;
connect-src https://api.syncanix.com;
style-src   'unsafe-inline';

• script-src must allow cdn.syncanix.com — where widget.js and its lazy chunks are served from.
• connect-src must allow api.syncanix.com — where the widget streams conversations.
• style-src must allow 'unsafe-inline' — the widget injects its styles inside its own Shadow DOM, so they never touch or read your page’s styles.
• Pages enforcing Trusted Types are supported out of the box — the widget never feeds a string sink.

Next steps