In Ihre App einbetten

Das Widget wird mit einem einzigen Script-Tag installiert, und alles Weitere auf dieser Seite baut darauf auf: welcher Schlüssel, wie Sie es in einer Single-Page-App laden, wie Sie es inline statt schwebend einbinden und was eine strikte Content-Security-Policy erlauben muss.

Holen Sie Ihren Einbettungsschlüssel

Das Widget authentifiziert sich mit einem veröffentlichbaren Schlüssel. Veröffentlichbare Schlüssel dürfen gefahrlos im Quelltext Ihrer Seite stehen: Sie identifizieren Ihren Arbeitsbereich, tragen aber keine geheime Berechtigung.

1. 1
   Öffnen Sie die API-Schlüssel im DashboardGehen Sie im Dashboard Ihres Arbeitsbereichs zu Einstellungen → API-Schlüssel.
2. 2
   Kopieren Sie den veröffentlichbaren SchlüsselKopieren Sie den Schlüssel, der mit pk_test_ (Entwicklung) oder pk_live_ (Produktion) beginnt — niemals einen geheimen gak_-Schlüssel, der nur auf Ihren Server gehört.
3. 3
   Schlüssel und Umgebung abgleichenDas Widget leitet die Umgebung aus dem Präfix des Schlüssels ab; fügen Sie data-env nur hinzu, wenn Sie sie ausdrücklich überschreiben müssen.

Das Script-Tag

Fügen Sie das Tag direkt vor dem schließenden body-Tag jeder Seite ein, auf der der Assistent erscheinen soll. type="module" muss erhalten bleiben: Das Widget ist ein ES-Modul und lädt ohne dieses Attribut nicht.

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

Das ist die gesamte Installation: Der Launcher erscheint in der gewählten Ecke, alles Weitere gestalten Sie im Dashboard. Die vollständige Attributliste steht in der Konfigurationsreferenz.

React, Vue und andere Single-Page-Apps

In einer Single-Page-App bleibt die einfachste Installation das statische Tag in Ihrer index.html — das Widget übersteht clientseitige Navigation von selbst. Wenn Sie das Einbinden lieber aus Ihrem Komponentenbaum steuern, injizieren Sie das Script in einem Effekt und entfernen es beim Aufräumen:

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;
}

Dasselbe Muster funktioniert überall mit Mount- und Cleanup-Hooks: onMounted/onUnmounted in Vue, ngOnInit/ngOnDestroy in Angular, onMount in Svelte.

Inline statt schwebend einbinden

Standardmäßig schwebt das Widget als Launcher in einer Seitenecke. Um den Chat in Ihr eigenes Layout zu setzen — ein Hilfepanel, eine Seitenleiste, eine ganze Seite — verwenden Sie data-chat-size="embedded" und richten data-mount-target auf einen CSS-Selektor des Containers, den das Widget füllen soll:

<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>

Übermitteln Sie die Identität Ihres Nutzers

Ohne Identität behandelt der Assistent jeden Besucher als anonym. Damit er als der angemeldete Nutzer handelt, registrieren Sie einen Token-Provider: Das Widget ruft ihn vor jedem Zug auf, sodass stets ein frisches Token gesendet wird. Die vollständige Einrichtung jedes Auth-Modus steht in Nutzer authentifizieren.

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

Content-Security-Policy-Anforderungen

Wenn Ihre Seite eine strikte CSP ausliefert, erlauben Sie vor dem Einbetten diese drei Dinge:

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

• script-src muss cdn.syncanix.com erlauben — von dort werden widget.js und seine nachgeladenen Teile ausgeliefert.
• connect-src muss api.syncanix.com erlauben — dorthin streamt das Widget die Unterhaltungen.
• style-src muss 'unsafe-inline' erlauben — das Widget injiziert seine Styles in sein eigenes Shadow DOM, sie berühren die Styles Ihrer Seite also nie.
• Seiten mit erzwungenen Trusted Types funktionieren ohne Anpassung: Das Widget bedient nie einen String-Sink.

Nächste Schritte