Den Assistenten Ihre API im Namen des Nutzers aufrufen lassen

Wenn der Assistent Ihre API aufruft, soll er als die Person handeln, mit der er spricht, mit deren eigenem Schlüssel oder Login, damit Ihre API deren Berechtigungen anwendet und deren Aktionen protokolliert. Diese Anleitung richtet das ein: Der Assistent sendet dann bei jedem Tool-Aufruf die eigenen Zugangsdaten des jeweiligen Endkunden. Kunden geben sie entweder einmal im Widget ein, oder Ihre Seite übergibt sie beim Start des Widgets, sodass niemand danach gefragt wird. Rechnen Sie mit etwa dreißig Minuten, die meisten davon dafür, die Zugangsdaten in der Seite aus Ihrer eigenen App zu lesen.

Bevor Sie beginnen

Sie brauchen	Wo Sie es finden
Ein Toolkit, dessen Autorisierung personenbezogene Werte verlangt: dynamische Header mit {{placeholder}}-Werten, Benutzername und Passwort oder einen automatischen Token-Endpunkt	Konfigurieren › Toolkits, die Autorisierungskonfiguration des Toolkits; siehe Toolkits
Dieses Toolkit ist dem Widget zugeordnet (1 bis 5 Toolkits pro Widget)	Konfigurieren › Embed, die Toolkits des Widgets
Das eingebaute Widget, mit der eigenen userId jeder Person	Das Widget in Ihr Produkt einbauen und Nutzer identifizieren und Kontext übergeben
Angemeldete Endkunden (empfohlen)	Gespeicherte Zugangsdaten gehören dem Kunden; die Anmeldung von Endkunden stellt sicher, dass die richtige Person sie nutzt
Für die Übergabe von Ihrer Seite: die Zugangsdaten der Person in der Seite	Ihre eigene App

Jede angemeldete Person in Ihrem Workspace kann die Toolkit- und die Embed-Ansicht ansehen; ändern erfordert die Rolle Admin, und bei allen anderen schlägt das Speichern fehl mit “This action requires the Admin role.” Die Ansicht Autorisierungsprotokolle braucht die Rolle Admin schon zum Lesen.

Auf der Seite des Toolkits

• OAuth - Dynamischer Token-Ablauf sendet das Zugriffstoken, das ein Kunde gespeichert hat: Es füllt die Platzhalter in den dynamischen Headern des Toolkits, etwa Authorization mit Bearer {{accessToken}}.
• Benutzerdefinierter Auth-Endpunkt - Automatisches Token-Abrufen kann {secret} in Headern und Body der Token-Anfrage verwenden. StrikeUp füllt den Platzhalter in der ersten Token-Anfrage und bei jeder Erneuerung.
• Nur Admins können die Autorisierungskonfiguration eines Toolkits speichern; gespeicherte Werte werden daher nie mit *** überschrieben.

Die Einzelheiten stehen unter Toolkits.

Schritte

1. Prüfen, wonach Ihr Toolkit fragt. Die Autorisierungsart des Toolkits entscheidet, ob Endkunden im Widget einen Autorisierungsschritt sehen und was Ihre Seite stattdessen übergeben kann.

   Toolkit-Autorisierung	Werden Nutzer im Widget gefragt?	Was sie eingeben	Was Ihre Seite in authData übergibt
   Keine - Keine Autorisierung erforderlich	Nie	Nichts	Nichts; Einträge werden ignoriert
   Benutzerdefinierter Token - API-Schlüssel oder Bearer-Token, nur statische Header	Nie	Nichts	Nichts nötig
   Benutzerdefinierter Token - API-Schlüssel oder Bearer-Token mit Schema für dynamische Autorisierungs-Header (Optional)	Ja	Ein Feld pro {{placeholder}} in den Header-Werten	Die fertigen Header: { "<Header-Name>": "<full header value>" }
   Basic Auth - Benutzername und Passwort	Ja	Benutzername und Passwort	{ "username": "…", "password": "…" }
   Benutzerdefinierter Auth-Endpunkt - Automatisches Token-Abrufen, ohne eigene Platzhalter	Nie: StrikeUp holt das Token, wenn sich der Chat verbindet	Nichts	Nichts nötig
   Benutzerdefinierter Auth-Endpunkt - Automatisches Token-Abrufen mit Benutzerdefinierte Platzhalter (Optional)	Ja	Ein Feld pro Platzhalter	{ "<placeholder key>": "<value>" }

   Werden Nutzer gefragt, zeigt das Widget nach dem Verbinden des Chats einen Autorisierungsschritt, ein Toolkit nach dem anderen, mit „Überspringen“ und „Weiter“ bzw. „Abschließen“. Genau das vermeiden Sie, wenn Sie die Werte übergeben.

   

   Ohne mitgegebene Zugangsdaten fragt das Widget jeden Nutzer einmal pro Toolkit; geben Sie sie mit, entfällt dieser Schritt.

   Was dieser Screenshot zeigt

   Ansicht

   Autorisierung erforderlich (host page › widget (panel))

   Hervorgehoben

   button “Überspringen”, authorization-card-buttons, enabled. skips this toolkit; the assistant cannot use it for this user in this browser

   Außerdem sichtbar

   Progress 1 / 2; Toolkit Demo Billing API; Fields Account Number and Access Key; Next button, links Why do I need this? and Where to get credentials?

   Zweck

   what end users see when a toolkit needs their credentials

2. Sicherstellen, dass das Toolkit am Widget hängt. Öffnen Sie Konfigurieren › Embed, wählen Sie die Karte des Widgets und prüfen Sie, dass das Toolkit zu den Toolkits des Widgets gehört. Zugangsdaten für ein Toolkit, das nicht am Widget hängt, werden abgewiesen.

3. Das Toolkit in den Einbettungscode aufnehmen. Schalten Sie in derselben Ansicht im englisch überschriebenen Kasten Inject Authorization das Toolkit ein. Der Einbettungscode erhält ein Array serverAuthorizations mit einem Eintrag pro Toolkit: seiner serverId und einem Objekt authData mit Beispielwerten.

   

   Inject Authorization ergänzt je Toolkit einen Eintrag serverAuthorizations; füllen Sie authData mit den Werten des angemeldeten Nutzers.

   Was dieser Screenshot zeigt

   Ansicht

   Embed (/admin/configure/embed?widgetId=…)

   Hervorgehoben

   code “”, embed-code-block, contains one entry for Demo Billing API. none (copy with Copy embed code)

   Außerdem sichtbar

   initStrikeUpChatWidget with applicationToken and placeholders; serverAuthorizations with serverId and authData; Copy embed code button

   Zweck

   passing a user's toolkit credentials from your page

   Für Toolkits mit dynamischen Headern zeigt das Beispiel immer "Authorization": "Bearer customer_token". Ersetzen Sie es durch die eigenen Header-Namen Ihres Toolkits, genau wie sie in seinem Schema für dynamische Autorisierungs-Header (Optional) definiert sind, mit dem vollständigen Header-Wert.

4. Die eigenen Werte der angemeldeten Person übergeben. Füllen Sie authData in Ihrer Seite aus der angemeldeten Person, nie mit festen Werten:

   window.initStrikeUpChatWidget({
     applicationToken: "<your widget's application token>",
     userId: "cus_48210",
     serverAuthorizations: [
       // Eigenes Token mit dem dynamischen Header "X-Api-Key: {{apiKey}}": den fertigen Header übergeben
       { serverId: "<toolkit id from the Embed screen>", authData: { "X-Api-Key": currentUser.apiKey } },
       // Basic Auth: Benutzername und Passwort
       { serverId: "<toolkit id from the Embed screen>", authData: { username: currentUser.login, password: currentUser.apiPassword } }
     ]
   });

   Übergeben Sie bei jedem Seitenaufruf den aktuellen Wert. Ein erneuter Aufruf von initStrikeUpChatWidget mit derselben userId sendet keine neuen Werte; ein Neuladen der Seite oder eine neue userId schon.

5. Als Nutzer testen. Öffnen Sie Ihr Produkt als Testnutzer, öffnen Sie das Widget und melden Sie sich an, falls das Widget es verlangt. Für die übergebenen Toolkits darf der Autorisierungsschritt nicht erscheinen. Fragen Sie etwas, das Ihre API braucht, etwa „Zeig meine letzten drei Rechnungen“, und prüfen Sie den Aufruf unter Analysen › Tool-Läufe.

Was danach passiert

Jedes Mal, wenn sich der Chat verbindet, übergibt das Widget Ihre serverAuthorizations an StrikeUp, bevor es prüft, ob sich der Kunde autorisieren muss. StrikeUp speichert jeden Eintrag als Zugangsdaten des angemeldeten Kunden für dieses Toolkit und ersetzt die vorherigen; bei einem Toolkit mit automatischem Token-Endpunkt holt es stattdessen mit Ihren Werten ein Token. Der Autorisierungsschritt überspringt diese Toolkits dann. Die Zugangsdaten gehören dem Kunden der angemeldeten Sitzung, nicht der userId, die ein späterer Aufruf übergibt, und sie gelten für jedes Ihrer Widgets mit demselben Toolkit.

Bei jedem Tool-Aufruf baut StrikeUp die Anfrage-Header in zwei Schichten: zuerst die statischen Header des Toolkits, dann die gespeicherten Zugangsdaten des Kunden. Ein Header aus den Zugangsdaten des Kunden ersetzt einen statischen Header gleichen Namens, unabhängig von Groß- und Kleinschreibung. Für Benutzername und Passwort baut StrikeUp den Header Authorization: Basic … für Sie.

Header, die Ihre Seite auf anderem Weg sendet, werden nicht verwendet. Die alte Option headers von initStrikeUpChatWidget hat keine Wirkung, und das Widget schreibt eine Warnung in die Browserkonsole, wenn Sie sie übergeben. Lehnt StrikeUp einen Eintrag von serverAuthorizations ab, etwa ein unbekanntes Toolkit oder eine gescheiterte Token-Anfrage, schreibt das Widget Some serverAuthorizations were not saved: mit dem Grund in die Browserkonsole.

Wenn Zugangsdaten nicht mehr funktionieren: Schlagen für denselben Kunden und dasselbe Toolkit nacheinander drei Tool-Aufrufe mit HTTP 401 oder einer gescheiterten Autorisierung fehl oder enden mit einem Fehler, löscht StrikeUp die gespeicherten Zugangsdaten. Beim nächsten Chat zeigt das Widget „Autorisierung abgelaufen“ und erneut den Autorisierungsschritt; ein erfolgreicher Aufruf dazwischen setzt den Zähler zurück. Geplante Workflows löschen nie Zugangsdaten. Bei einem Toolkit mit automatischem Token-Endpunkt und Refresh-Token erneuert ein 401 zuerst das Token und wiederholt den Aufruf einmal.

Nach drei fehlgeschlagenen Aufrufen in Folge werden die gespeicherten Zugangsdaten gelöscht und der Nutzer erneut gefragt.

Was dieser Screenshot zeigt

Ansicht

Autorisierung abgelaufen (host page › widget (panel))

Hervorgehoben

heading “Autorisierung abgelaufen”, notice-top, shown. none; the form below re-collects the credentials

Außerdem sichtbar

Notice that the previous authorization expired (text varies: generic, or with an unfilled {{toolkitName}} placeholder — product defect); Authorization form for Demo Billing API with Skip and Complete

Zweck

what happens when a user's stored credential stops working

So prüfen Sie, ob es funktioniert hat:

• Der Autorisierungsschritt erscheint für die übergebenen Toolkits nicht.
• Der Tool-Aufruf erscheint unter Analysen › Tool-Läufe mit der Antwort Ihrer API.
• Bei automatischen Token-Endpunkten erscheint jeder Token-Abruf in der Ansicht Autorisierungsprotokolle des Toolkits, geöffnet mit Autorisierungsprotokolle anzeigen am Toolkit, mit maskierten Werten. Andere Autorisierungsarten erscheinen dort nicht.

Autorisierungsprotokolle erfassen nur die Token-Abrufe, die StrikeUp für ein Toolkit ausführt; Werte sind maskiert.

Was dieser Screenshot zeigt

Ansicht

Autorisierungsprotokolle (/admin/servers/authorization-logs/:serverId)

Hervorgehoben

heading “Autorisierungsprotokolle”, page-header, Demo Billing API. none

Außerdem sichtbar

Search by customer ID, All Attempts, All Results, Search; Rows with Success 200 and Failed 401/400

Zweck

checking automatic token fetches per customer

Werte in serverAuthorizations liegen in Ihrer Seite

Das Widget übergibt serverAuthorizations per Browser-Nachricht an seinen eigenen Chat-Frame, nie über dessen Adresse, daher erscheinen sie nicht in Anfrageprotokollen oder im Browserverlauf. Skripte auf Ihrer Seite und die Entwicklerwerkzeuge des Browsers können sie aber lesen. Übergeben Sie kurzlebige, personenbezogene Tokens statt langlebiger Passwörter oder kontoweiter Schlüssel.

So werden gespeicherte Zugangsdaten abgelegt: StrikeUp speichert die Zugangsdaten jedes Kunden, ob im Chat eingegeben, von Ihrer Seite übergeben oder importiert, pro Kunde in der eigenen Datenbank Ihres Unternehmens, mit AES-256-GCM verschlüsselt. Sie werden nur auf dem Server entschlüsselt, wenn ein Tool-Aufruf sie braucht, und dem Kunden nie wieder vollständig angezeigt.

Optionen

Wahl	Wann Sie sie wählen	Wirkung
Nutzer geben Zugangsdaten im Widget ein	Nutzer kennen ihren eigenen Schlüssel oder Login, und Ihre Seite kann ihn nicht lesen	Der Autorisierungsschritt fragt einmal pro Toolkit; der Wert wird für den Kunden gespeichert
Von Ihrer Seite übergeben (serverAuthorizations)	Ihre App hält bereits ein personenbezogenes Token	Nutzer werden nie gefragt; der gespeicherte Wert wird bei jedem Seitenaufruf ersetzt
Per Import vorbelegen	Viele bestehende Nutzer, oder Zugangsdaten, die nur Ihr Backend kennt	CRM › Kunden › Aus CSV importieren, mit einer Spalte Toolkit-Zugangsdaten pro Kunde
Ein automatischer Token-Endpunkt ohne Platzhalter	Ihre API kann für eine Nutzer-ID ein Token ausstellen	StrikeUp holt Tokens selbst; niemand gibt etwas ein

Rotierende und ablaufende Tokens

Übergeben Sie bei jedem Seitenaufruf das aktuelle Token: Der gespeicherte Wert wird bei jedem Verbinden des Chats ersetzt. Rotiert ein Token, während eine Seite offen bleibt, übergeben Sie den neuen Wert mit window.StrikeUpChat.setServerAuthorizations([...]) oder rufen initStrikeUpChatWidget erneut auf; beides speichert ihn sofort. Noch besser übergeben Sie beim Start einen Callback getServerAuthorizations: Das Widget fragt ihn vor jeder Nachricht und Tool-Freigabe nach frischen Werten, und werden gespeicherte Zugangsdaten abgelehnt, versucht es zuerst Ihren Callback, bevor es dem Kunden den Autorisierungsschritt zeigt. Siehe Referenz der Widget-JavaScript-API. Richten Sie für einen automatischen Token-Endpunkt am Toolkit ein Refresh-Token ein, damit StrikeUp es bei einem 401 erneuert.

Was Nutzer selbst tun können

Wer im Autorisierungsschritt „Überspringen“ wählt, wird in diesem Browser nicht erneut gefragt, und der Assistent kann dieses Toolkit für die Person nicht nutzen. Im Verlaufsbereich des Chats listet „Toolkit-Status“ jedes Toolkit mit „Authentifizieren“, um Zugangsdaten später einzugeben, und „Abmelden“, das die gespeicherten Zugangsdaten löscht.

Wenn etwas schiefgeht

Symptom	Was Sie prüfen	Lösung
Der Autorisierungsschritt erscheint trotz Übergabe	Der Reihe nach: Die serverId stimmt mit der Ansicht Embed überein; das Toolkit hängt an diesem Widget; authData verwendet die eigenen Header-Namen oder Platzhalterschlüssel des Toolkits; bei Token-Endpunkten war die Token-Anfrage in Autorisierungsprotokolle erfolgreich. Das Widget zeigt nicht an, warum ein Eintrag abgewiesen wurde	Den Eintrag erneut aus der Ansicht Embed kopieren und authData korrigieren
Aufrufe erreichen Ihre API ohne den Header der Person	authData verwendet Authorization: Bearer … aus dem Beispiel statt des Header-Namens Ihres Toolkits, oder die Platzhalternamen statt der Header-Namen	{ "<Header-Name>": "<full value>" } mit den eigenen Header-Namen des Toolkits übergeben
Nutzer sehen „Autorisierung abgelaufen“	Drei Aufrufe in Folge scheiterten mit 401 oder einem Fehler; die gespeicherten Zugangsdaten wurden gelöscht	Gültige Zugangsdaten übergeben oder die Person erneut autorisieren lassen
„Failed to authorize. Please verify your input values are correct.“ im Widget	Der Token-Endpunkt hat die Werte der Person abgelehnt	Den gescheiterten Versuch in Autorisierungsprotokolle prüfen
Ein neues Token wird erst nach dem Neuladen verwendet	initStrikeUpChatWidget wurde mit derselben userId erneut aufgerufen	Neu laden oder das Token beim nächsten Seitenaufruf übergeben
Eine Person hat den Schritt übersprungen, und der Assistent kann das Toolkit nicht nutzen	„Überspringen“ wird in diesem Browser gemerkt	Die Person wählt „Authentifizieren“ unter „Toolkit-Status“ im Verlaufsbereich des Chats
Eine Änderung schlägt mit Anfrage fehlgeschlagen und “This action requires the Admin role.” fehl	Änderungen auf dieser Seite erfordern die Rolle Admin.	Bitten Sie eine Person mit der Rolle Admin, die Änderung vorzunehmen oder Ihnen die Rolle unter Einstellungen › Benutzer zu geben.

Verwandte Seiten

• Toolkits
• Autorisierungsprotokolle
• Embed
• Anmeldung von Endkunden
• Referenz der Widget-JavaScript-API
• Tool-Läufe