Das Widget in Ihr Produkt einbauen

Bauen Sie das StrikeUp-Widget mit zwei Tags in Ihre Web-App ein: dem Widget-Skript und einem Aufruf von window.initStrikeUpChatWidget mit dem Anwendungs-Token Ihres Widgets und den Daten der angemeldeten Person. Das funktioniert in reinem HTML genauso wie in React, Vue, Angular oder jedem serverseitig gerenderten Framework, denn es gibt kein Paket zu installieren. Danach erscheint auf Ihren Seiten die Startschaltfläche (oder der Bereich bzw. der eingebettete Chat, den Sie gewählt haben), und der Assistent weiß, mit welcher Ihrer Nutzerinnen und Nutzer er spricht. Rechnen Sie mit etwa fünfzehn Minuten, die meisten davon für das Ersetzen der Platzhalter durch echte Werte aus Ihrer App.

Bevor Sie beginnen

Sie brauchen	Wo Sie es finden
Ein Widget mit mindestens einem Toolkit	KonfigurierenEmbed; dort legen Sie mit der gestrichelten Karte „New widget“ auch eines an
Den Einbettungscode des Widgets, der sein Anwendungs-Token enthält	KonfigurierenEmbed, unter Einbettungscode. Keine andere Ansicht zeigt das Token
Die gewünschte Darstellungsart und die Seiten, auf denen das Widget erscheinen soll	KonfigurierenUser Interface; siehe Darstellungsarten und eigene Auslöser
Zugriff auf die Seitenvorlage oder das Root-Layout Ihrer App und die ID, die Ihre App für die angemeldete Person verwendet	Ihre eigene Codebasis

Jede angemeldete Person in Ihrem StrikeUp-Workspace kann die Ansicht Embed öffnen und den Code in die Zwischenablage übernehmen. Das Widget braucht keinen Tarif und keinen Funktionsschalter.

Schritte

Den Einbettungscode übernehmen. Öffnen Sie KonfigurierenEmbed, wählen Sie oben die Karte Ihres Widgets und scrollen Sie zu Einbettungscode. Wählen Sie die englisch beschriftete Schaltfläche Copy embed code unter dem Code. Sie zeigt kurz Copied!; der Code liegt jetzt in Ihrer Zwischenablage.

Kopieren Sie die beiden Tags von Embed und ersetzen oder löschen Sie vor der Veröffentlichung jeden Platzhalter your_….
Was dieser Screenshot zeigt
Ansicht
Embed (/admin/configure/embed?widgetId=…)
Hervorgehoben
button “”, embed-code-block-bottom, enabled. copies the script tag and the initStrikeUpChatWidget call to the clipboard
Außerdem sichtbar
script tag with src …/widget.js and data-api-url (development URLs in this capture); initStrikeUpChatWidget with applicationToken and your_… placeholders for the user fields; Start of Custom Trigger Button Snippets
Zweck
where developers get the install code

Der Code hat diese Form. Übernehmen Sie die Skript-URL und data-api-url genau so, wie die Ansicht Embed sie zeigt. Die StrikeUp-API liegt unter https://api.strikeup.io; die Skript-URL steht hier als Platzhalter.
```
<script src="https://<your widget script URL>" data-api-url="https://api.strikeup.io"></script>
<script>
  window.initStrikeUpChatWidget({
    "applicationToken": "<your widget's application token>",
    "userId": "your_customer_id",
    "userDisplayName": "your_customer_display_name",
    "userEmail": "your_customer_email",
    "userCompanyId": "your_…",
    "userCompanyName": "your_…",
    "handoffUserId": "your_handoff_user_id"
  });
</script>
```
Jeden Platzhalter your_… ersetzen oder löschen. Die Platzhalter sind wörtlicher Text. Veröffentlichen Sie den Code unverändert, wird jede besuchende Person zum selben Kunden namens your_customer_id, und alle teilen sich einen Chatverlauf. Füllen Sie jedes Feld aus der angemeldeten Person Ihrer App oder löschen Sie die Zeile:
```
<script>
  window.initStrikeUpChatWidget({
    applicationToken: "<your widget's application token>",
    userId: "cus_48210",                         // Ihre dauerhafte ID für diese Person
    userDisplayName: "Rosie Kendall",
    userEmail: "rosie.kendall@example.com",
    userCompanyId: "SAP-5531",                   // die Company ID ihres Unternehmens im CRM
    userCompanyName: "Sample & Partners Ltd"
  });
</script>
```
Verwenden Sie eine ID, die sich für diese Person nie ändert, etwa Ihren Datenbankschlüssel, und keine E-Mail-Adresse, die sich ändern kann. Sie hält Chats, Erinnerungen und gespeicherte Toolkit-Zugangsdaten zusammen. Löschen Sie handoffUserId, wenn Sie Chats nicht an einen Helpdesk übergeben. Was jedes Feld bewirkt, steht unter Nutzer identifizieren und Kontext übergeben.
Beide Tags am Ende des <body> einfügen. Setzen Sie sie in das Layout, das jede Seite Ihrer App verwendet, direkt vor </body>, und zwar das Script-Tag zuerst. Lassen Sie das Script-Tag schlicht, ohne async oder defer: Der Inline-Aufruf funktioniert, weil das Skript bereits gelaufen ist. Setzen Sie das Skript nicht in den <head>. Dort startet das Widget zwar, aber ein Teil des Skripts scheitert, weil der Seiteninhalt noch nicht existiert: Das Widget prüft seine URL-Regeln nicht mehr neu, wenn sich Besucher in einer Single-Page-App bewegen, und das Ereignis strikeupChatWidgetLoaded wird nie ausgelöst.

Lädt Ihre App Skripte asynchron, starten Sie das Widget aus dem Ereignis, das das Skript nach dem Laden auslöst:
```
<script src="https://<your widget script URL>" data-api-url="https://api.strikeup.io" async></script>
<script>
  window.addEventListener("strikeupChatWidgetLoaded", function () {
    window.initStrikeUpChatWidget({ applicationToken: "<your widget's application token>", userId: "cus_48210" });
  });
</script>
```
Oder legen Sie die Aufrufwarteschlange vor allem anderen selbst an; das Widget-Skript übernimmt sie und spielt sie beim Laden ab:
```
<script>
  window._strikeupChatWidgetQueue = window._strikeupChatWidgetQueue || [];
  window.initStrikeUpChatWidget = window.initStrikeUpChatWidget ||
    function (config) { window._strikeupChatWidgetQueue.push(config); };
  window.initStrikeUpChatWidget({ applicationToken: "<your widget's application token>", userId: "cus_48210" });
</script>
```
Den Chat in Ihr Layout einbetten (optional). Um den Chat in einem Abschnitt Ihrer Seite zu zeigen, statt ihn darüber schweben zu lassen, schalten Sie in der Ansicht Embed In einen Container einbetten ein. Der Code erhält ein Container-Element und zwei Optionen. Geben Sie dem Container eine feste Höhe: Ohne Höhe fällt das Widget auf null zusammen.
```
<div id="strikeup-widget" style="width: 100%; height: 600px;"></div>
<script>
  window.initStrikeUpChatWidget({
    applicationToken: "<your widget's application token>",
    userId: "cus_48210",
    displayType: "inline",
    container: "#strikeup-widget",
    portalDisplayType: "inline"            // optional: das Kundenportal im selben Container öffnen
  });
</script>
```
Für ein Inline-Widget schalten Sie In einen Container einbetten ein und geben dem Element auf Ihrer Seite eine feste Höhe.
Was dieser Screenshot zeigt
Ansicht
Embed (/admin/configure/embed?widgetId=…)
Hervorgehoben
note “Tipp: Geben Sie dem Container eine explizite Höhe. Ohne Höhe wird das Widget auf null reduziert.”, embed-code-card-inline-option, shown because the inline option is on. none (hint)
Außerdem sichtbar
Embed inside a container switched on; Container selector #strikeup-widget; Open Customer Portal inline switch, off; Inject Authorization box with Demo Billing API and Demo Accounts API
Zweck
the inline variant of the install code (not saved; it only changes the generated snippet)

Der Container muss existieren, wenn der Aufruf läuft. Der Schalter ändert nur den erzeugten Code; am Widget wird nichts gespeichert.

Das Widget in Ihrer Content Security Policy erlauben (optional). Sendet Ihre Website einen Content-Security-Policy-Header, erlauben Sie die Hosts des Widgets in diesen Direktiven. Verwenden Sie die Hosts aus den beiden URLs in der Ansicht Embed.

Direktive	Erlauben	Warum
`script-src`	Den Host des Widget-Skripts, dazu eine Nonce oder einen Hash für das Inline-Init-Skript (oder `'unsafe-inline'`)	Lädt das Widget-Skript und führt Ihren Init-Aufruf aus
`connect-src`	Den Host von `data-api-url` (`https://api.strikeup.io`)	Ihre Seite holt die Einstellungen des Widgets von der StrikeUp-API
`frame-src` (oder `child-src`)	Den Host des Widget-Skripts	Der Chat und Diagramme in voller Größe laufen in Frames von diesem Host
`style-src`	Nichts zusätzlich	Das Widget setzt seine Styles über das DOM. Ohne `'unsafe-inline'` verliert nur der kleine Pfeil am Reiter der Seitenleiste seine Drehanimation

Senden Sie einen Permissions-Policy-Header, schalten Sie microphone und clipboard-write für den Host des Widgets nicht ab: Der Chat nutzt sie für die Spracheingabe und die Kopierschaltflächen. Die Spracheingabe braucht außerdem eine Seite, die über HTTPS (oder von localhost) ausgeliefert wird.

Eine Seite laden und das Widget prüfen. Öffnen Sie Ihre App im Browser. Mit der Standard-Darstellungsart Popup erscheint unten rechts eine runde Startschaltfläche mit Sprechblasen-Symbol; wählen Sie sie, und der Chat öffnet sich.

Wenn der Einbau funktioniert, erscheint die Startschaltfläche in der Ecke jeder Seite, die die URL-Regeln des Widgets zulassen.
Was dieser Screenshot zeigt
Ansicht
(host page (https://app.example.com/))
Hervorgehoben
button “”, bottom-right, closed (popup display type). opens the chat window
Außerdem sichtbar
Neutral host page with placeholder layout; Round blue launcher with chat-bubble icon, bottom-right
Zweck
what a successful install looks like

Zur Prüfung in der Browserkonsole führen Sie aus:
```
window.StrikeUpChat.onReady(function (type) { console.log("widget:", type); });
```
Es gibt die Darstellungsart aus, etwa popup, sobald der Chat bereit ist. Es gibt null aus, wenn das Token oder die Adresse in data-api-url falsch ist.

Was danach passiert

Bei jedem Seitenaufruf liest das Widget-Skript data-api-url aus seinem eigenen Tag und holt mit dem Anwendungs-Token die gespeicherten Einstellungen des Widgets von der StrikeUp-API. Danach prüft es die URL-Sichtbarkeitsregeln des Widgets gegen den Pfad der Seite, zeichnet Startschaltfläche, Bereich oder eingebetteten Chat und lädt den Chat-Frame. Die Arten Popup und Modal laden den Chat-Frame beim ersten Klick, alle anderen mit der Seite. Im Frame durchläuft die besuchende Person Anmeldung und Toolkit-Autorisierung, falls Ihr Widget sie braucht, und sieht dann den Willkommensbildschirm.

Einstellungen, die Sie in StrikeUp ändern, etwa Farben, Darstellungsart oder URL-Regeln, erreichen die Besucher beim nächsten Laden einer Seite; Sie ändern Ihren Code nicht und liefern nichts neu aus. Jedes Laden wird im Trichter im Dashboard als „Widget Loaded“ gezählt. Darstellungsarten, die den Chat-Frame mit der Seite laden, können für einen Seitenaufruf zwei Ladevorgänge erfassen.

So prüfen Sie, ob es funktioniert hat:

Startschaltfläche, Bereich oder eingebetteter Chat erscheinen, und StrikeUpChat.onReady meldet die Darstellungsart.
Im Netzwerk-Tab Ihres Browsers liefert die Anfrage an die StrikeUp-API, die mit Ihrem Anwendungs-Token endet, den Status 200.
Nach einem ersten Chat erscheint die Person unter CRMKunden mit der ID, die Sie als userId übergeben haben.

Optionen

Wahl	Wann Sie sie wählen	Wirkung
Eine schwebende Art (Popup, Seitenleiste oder Panel), gewählt unter User Interface	Hilfe, die auf jeder Seite verfügbar ist	Eine Startschaltfläche oder ein Bereich, der immer da ist
`displayType: "inline"` mit `container`	Der Chat gehört in Ihr Layout, etwa auf eine Hilfeseite	Der Chat füllt Ihr Element, ohne Startschaltfläche
Eine Art mit eigenem Auslöser, gewählt unter User Interface	Sie möchten Ihre eigene „KI fragen“-Schaltfläche	Keine Startschaltfläche; Ihre Schaltfläche ruft `StrikeUpChat.open()` auf
`portalDisplayType: "inline"`	Inline-Einbettungen, die das Kundenportal nutzen	Das Portal ersetzt den Chat im Container, statt ein großes Fenster zu öffnen
`displayType` im Aufruf einer Seite gesetzt	Eine Seite braucht eine andere Darstellungsart als der Rest Ihrer App	Überschreibt die gespeicherte Darstellungsart nur auf dieser Seite

Single-Page-Apps und Frameworks

Laden Sie das Skript einmal, in der HTML-Hülle oder im Root-Layout, und rufen Sie initStrikeUpChatWidget auf, sobald die Person bekannt ist. Routenwechsel brauchen keinen neuen Aufruf: Das Widget prüft seine URL-Regeln neu, wenn sich der Pfad ändert. Ein erneuter Aufruf von initStrikeUpChatWidget mit derselben userId ändert am offenen Chat nichts. Ein Aufruf mit einer anderen userId, etwa wenn sich ohne Neuladen eine andere Person anmeldet, entfernt das Widget und startet es für die neue Person neu. Wird das Skript versehentlich zweimal geladen, schadet das nicht.

// React: das Widget starten, sobald die angemeldete Person bekannt ist
useEffect(() => {
  if (!user) return;
  window.initStrikeUpChatWidget({ applicationToken: WIDGET_TOKEN, userId: user.id, userDisplayName: user.name });
}, [user?.id]);

Rufen Sie window.StrikeUpChat.destroy() auf, um das Widget von der Seite zu nehmen, zum Beispiel wenn sich die Person von Ihrer App abmeldet. Es entfernt Startschaltfläche, Bereich und Chat-Frame, beendet die Live-Verbindung des Chats und gibt Ihrer Seite ihr ursprüngliches Padding zurück. Nur das Script-Tag zu entfernen, entfernt das Widget nicht.

Die Skriptdatei

Laden Sie das Skript von der URL in der Ansicht Embed und behalten Sie seinen Dateinamen. Das Widget findet sein eigenes Tag am Namen widget.js, liest daraus data-api-url und lädt den Chat-Frame aus demselben Ordner. data-api-url ist das einzige Attribut, das das Tag liest; Position, Farben und Begrüßung stammen aus den Einstellungen des Widgets in StrikeUp.

Wenn etwas schiefgeht

Symptom	Was Sie prüfen	Lösung
Nichts erscheint, und die Konsole zeigt keinen Fehler	Den Netzwerk-Tab: Die Anfrage nach den Einstellungen liefert 404 (Token falsch oder Widget gelöscht) oder scheitert (falsche `data-api-url`). Dann die URL-Sichtbarkeitsregeln des Widgets für diesen Pfad. Bei Inline den Container	Den Code erneut unter KonfigurierenEmbed kopieren; die URL-Regeln anpassen; dem Container eine Höhe geben
`TypeError: window.initStrikeUpChatWidget is not a function`	Das Script-Tag ist `async`, `defer`, per Code hinzugefügt oder steht nach Ihrem Aufruf	Das schlichte Tag vor dem Aufruf, das Ereignis `strikeupChatWidgetLoaded` oder die Warteschlange aus den Schritten verwenden
Die Konsole zeigt `[StrikeUpChat] displayType "inline" requires a valid container (CSS selector or Element). Widget not mounted.`	Der Selektor in `container` trifft beim Aufruf kein Element	Das Element zuerst rendern oder das Element selbst übergeben
Der Chat-Frame zeigt „Widget-Konfigurationsfehler“ und „Bitte kontaktieren Sie den Website-Administrator.“	Das Token ist für die API, die der Chat-Frame verwendet, nicht gültig	Den Code erneut aus der Ansicht Embed des richtigen Workspace kopieren
Das Widget erscheint auf manchen Seiten und auf anderen nicht	Die URL-Regeln des Widgets: Jedes `*` trifft genau ein Pfadsegment	Für die fehlenden Pfade unter KonfigurierenUser Interface ein Muster ergänzen
Alle Besucher sehen denselben Chatverlauf	`userId` ist noch `your_customer_id` oder ein anderer fester Wert	Die eigene ID jeder Person übergeben
Die Mikrofon-Schaltfläche fehlt	Die Seite wird nicht über HTTPS ausgeliefert, oder eine `Permissions-Policy` sperrt `microphone`	Die Seite über HTTPS ausliefern und das Mikrofon erlauben
Besucher sehen nach einer Aufnahme „Too many voice messages right now. Please try again later.“ oder „Transcription failed (429)“	Die Spracherkennung ist auf 10 Aufnahmen pro Minute je Netzwerkadresse eines Besuchers, 60 pro Minute je Widget und 2.000 pro Tag je Unternehmen begrenzt	Besucher können tippen oder nach einer Minute erneut aufnehmen; das Tageslimit gibt innerhalb von 24 Stunden wieder frei. Brauchen Sie höhere Limits, fragen Sie den StrikeUp-Support
Das Widget reagiert nicht mehr auf Routenwechsel, und das Lade-Ereignis wird nie ausgelöst	Das Script-Tag steht im `<head>`	Beide Tags ans Ende des `<body>` verschieben