Copera Omni Web-Chat-Widget: Setup, SDK und Identity
Das Copera Omni Web-Widget fügt Web-Chat zu Ihrer Website hinzu und leitet jede Unterhaltung in einen Omni-Channel — eine gemeinsame Inbox, die Unterhaltungen aus mehreren Quellen gleichzeitig empfangen kann, z. B. einem oder mehreren Web-Widgets und WhatsApp-Nummern, damit Ihr Team alle an einem Ort bearbeitet.
Dieser Leitfaden führt Sie von einer Zwei-Minuten-Installation zu einer produktionsreifen Integration: dem Copy-Paste-Embed, der CoperaOmni-Command-API für Custom-Launcher, Browser-Origin-Sicherheit und dem sicheren Flow zum Identifizieren angemeldeter Besucher, ohne jemals einen Server-Key im Browser freizugeben.
Kostenlose vs. bezahlte Quellen
Ein Omni-Channel kann mehrere Quellen kombinieren. Das Web-Widget ist die kostenlose; WhatsApp ist ein bezahltes Add-on.
Fügen Sie so viele Web-Widget-Quellen hinzu, wie Sie brauchen — ohne Kosten. Alles in diesem Leitfaden nutzt das kostenlose Web-Widget.
Verbinden Sie WhatsApp-Nummern als bezahlte Add-ons mit demselben Omni-Channel, sodass Web- und WhatsApp-Unterhaltungen in einer Inbox landen.
Eine WhatsApp-Quelle zu entfernen oder einen Omni-Channel zu löschen storniert den gekauften Nummern-Slot nicht. Um für einen Slot nicht weiter zu zahlen, reduzieren Sie die gekaufte Menge separat unter Workspace Billing.
Quick Start
Zwei Minuten bis zum Live-Widget.
In Copera einen Omni-Channel öffnen (oder anlegen), zu Settings → Add source gehen und Web widget wählen — Copera kennzeichnet diese Quelle als Free. Dann den channelKey unter Configure & install kopieren.
Unten Quick embed oder JavaScript SDK wählen, in Ihre Seite einfügen und YOUR_CHANNEL_KEY durch den kopierten Key ersetzen.
Coperas Floating-Launcher erscheint an der konfigurierten Position. Öffnen Sie ihn, um eine Unterhaltung zu starten.
- Quick embed
- JavaScript SDK
Platzieren Sie dieses vollständige Snippet einmal, direkt vor dem schließenden </body>-Tag. Es lädt die CDN-Runtime asynchron, initialisiert die Quelle und zeigt Coperas Floating-Launcher.
<script>
(function (w, d) {
w.CoperaOmni = w.CoperaOmni || function () {
(w.CoperaOmni.q = w.CoperaOmni.q || []).push(arguments);
};
var s = d.createElement('script');
s.async = 1;
s.src = 'https://widget.copera.ai/widget.js';
d.head.appendChild(s);
})(window, document);
CoperaOmni('init', { channelKey: 'YOUR_CHANNEL_KEY' });
</script>
Das ist alles, was eine plain-HTML-Site braucht. Um das Panel von Ihrem eigenen Button statt vom Floating-Launcher zu steuern, wechseln Sie zum Tab JavaScript SDK.
Laden Sie dieselbe CDN-Runtime, initialisieren Sie mit launcher: 'custom', um Coperas Floating-Launcher zu unterdrücken, und steuern Sie das Panel mit Ihrer eigenen Kontrolle über die CoperaOmni-Command-API.
<button id="support-chat" type="button" aria-controls="copera-support" aria-expanded="false">
Chat with support
</button>
<script>
window.CoperaOmni = window.CoperaOmni || function () {
(window.CoperaOmni.q = window.CoperaOmni.q || []).push(arguments);
};
</script>
<script async src="https://widget.copera.ai/widget.js"></script>
<script>
const launcherButton = document.querySelector('#support-chat');
CoperaOmni('on', 'open', function () {
launcherButton.setAttribute('aria-expanded', 'true');
});
CoperaOmni('on', 'close', function () {
launcherButton.setAttribute('aria-expanded', 'false');
});
CoperaOmni('init', {
channelKey: 'YOUR_CHANNEL_KEY',
launcher: 'custom',
locale: document.documentElement.lang || 'en',
});
launcherButton.addEventListener('click', function () {
CoperaOmni('toggle');
});
</script>
Nutzen Sie open und close, wenn Ihre App den gewünschten Zustand bereits kennt, und toggle für einen einzelnen Launcher-Button. Wenn Sie den Default-Launcher behalten haben, blendet setLauncherVisible(false) ihn vorübergehend aus und setLauncherVisible(true) stellt ihn wieder her.
@copera/omni-widget-sdk ist ein optionaler typisierter Wrapper um dieselben Commands. Siehe Typisierter Wrapper und CDN-Runtime.
Der erzeugte channelKey ist der öffentliche Key für diese spezifische Web-Widget-Quelle. Er ist sicher im Browser-Code. Er ist nicht die Omni-Channel-ID oder Source-ID und darf durch keine der beiden ersetzt werden.
Wenn Sie Regenerate key wählen, funktioniert der alte channelKey nicht mehr. Ersetzen Sie ihn überall, wo das Widget eingebettet ist.
Widget konfigurieren
Der Quick Start nutzt Defaults. Öffnen Sie die Settings der Widget-Quelle (oder Configure & install), um die volle Experience vor dem Go-Live anzupassen.
Channel mit dem Channel-Typ Omni anlegen oder einen bestehenden öffnen. Ein einzelner Omni-Channel kann Unterhaltungen aus mehreren Quellen empfangen.
Settings des Channels öffnen, Add source wählen, dann Web widget. Copera kennzeichnet diese Quelle als Free.
Display name eingeben, Primary color und Launcher position wählen und optional eine Greeting message setzen. Sie können auch Show a pre-chat form für anonyme Besucher aktivieren.
Für eine neue Integration unter Embed security Browser origin (recommended) wählen. Jede exakte Site-Origin, die das Widget einbetten darf, zu Allowed origins hinzufügen und nach jeder mit Enter bestätigen — z. B. https://www.example.com und https://app.example.com.
Require verified visitor identity aus lassen, um anonyme oder Pre-Chat-Unterhaltungen zu erlauben. Einschalten, wenn Ihre Site immer identify mit einem server-ausgestellten Identity-Token aufruft. Pre-Chat-Formular und erforderliche verifizierte Identity können nicht zusammen aktiviert werden.
Create widget wählen. Auf dem Success-Screen Quick embed für den eingebauten Launcher kopieren oder JavaScript SDK für einen Custom-Launcher wählen. Später können Sie zur Quelle zurückkehren und Configure & install wählen.
| Einstellung | Was sie steuert | Standard |
|---|---|---|
| Display name | Der Name oben im Chat-Panel. | Source-Name |
| Primary color | Akzentfarbe von Launcher und Panel. | Workspace-Akzent |
| Launcher position | In welcher Ecke der Floating-Launcher sitzt. | Unten rechts |
| Greeting message | Optionale erste Nachricht beim Öffnen des Panels. | Keine |
| Show a pre-chat form | Fragt anonyme Besucher vor Beginn der Unterhaltung nach Details. | Aus |
| Embed security | Wie Copera entscheidet, welche Seiten das Widget einbetten dürfen. | Browser origin |
| Require verified visitor identity | Blockiert anonyme und Pre-Chat-Chats; erfordert server-ausgestelltes Identity-Token. | Aus |
JavaScript-Command-API
https://widget.copera.ai/widget.js installiert die globale Command-Funktion CoperaOmni(command, ...args). Aufrufe über das Queue-Snippet, bevor die Runtime fertig geladen ist, werden gepuffert und der Reihe nach abgespielt.
Commands
| Command | Signatur | Zweck |
|---|---|---|
init | CoperaOmni('init', config) | Widget initialisieren. config.channelKey ist erforderlich; locale und launcher sind optional. |
identify | CoperaOmni('identify', identity) | Besucher-Identity setzen. Bevorzugen Sie { identityToken } für angemeldete Benutzer; { name, email } unterstützt unverifizierte Besucherdetails. |
logout | CoperaOmni('logout') | Aktuelle Identity löschen, bevor ein Benutzer abmeldet oder ein anderer die Seite übernimmt. |
destroy | CoperaOmni('destroy') | Iframe, Launcher, Timer, Listener und In-Memory-Credentials entfernen. |
open | CoperaOmni('open') | Chat-Panel öffnen. |
close | CoperaOmni('close') | Chat-Panel schließen. |
toggle | CoperaOmni('toggle') | Panel zwischen offen und geschlossen umschalten. |
setLauncherVisible | CoperaOmni('setLauncherVisible', visible) | Eingebauten Launcher zeigen oder verbergen, ohne das Widget zu zerstören. |
update | CoperaOmni('update', { locale }) | Live-Widget-Locale ändern. |
on | CoperaOmni('on', eventName, callback) | Event abonnieren. Die Live-Runtime gibt eine Unsubscribe-Funktion zurück. |
off | CoperaOmni('off', eventName, callback) | Denselben Callback entfernen, der zuvor an on übergeben wurde. |
Die unterstützten init-Optionen sind:
| Option | Typ | Standard | Beschreibung |
|---|---|---|---|
channelKey | string | Erforderlich | Öffentlicher Source-Key aus Configure & install. |
locale | string | "en" | BCP-47-Locale für die Widget-UI, z. B. "en" oder "pt-BR". |
launcher | "default" | "custom" | "default" | "custom" unterdrückt Coperas Launcher und lässt Sie das Panel selbst steuern. |
Events
Jeder Event-Callback erhält ein Objekt, dessen name das Event identifiziert.
| Event | Payload | Wann es feuert |
|---|---|---|
ready | { name: 'ready' } | Iframe ist bereit und hat seinen initialen State dispatched. Beweist nicht, dass die Backend-Initialisierung gelungen ist. |
open | { name: 'open' } | Panel öffnet sich. |
close | { name: 'close' } | Panel schließt sich. |
identityRequired | { name: 'identityRequired' } | Eine geschlossene Unterhaltung wird auf einer Quelle neu gestartet, die den Besucher erneut verifiziert haben will. |
unreadCount | { name: 'unreadCount', count: number } | Die Anzahl ungelesener Nachrichten ändert sich. |
conversationStarted | { name: 'conversationStarted', conversationId: string } | Eine Unterhaltung startet und ihre ID wird verfügbar. |
Custom-Badge aktualisieren und Conversation-Start protokollieren:
const unreadBadge = document.querySelector('#support-unread');
function handleUnread(event) {
unreadBadge.textContent = String(event.count);
unreadBadge.hidden = event.count === 0;
}
function handleConversationStarted(event) {
console.log('Omni conversation started', event.conversationId);
}
CoperaOmni('on', 'unreadCount', handleUnread);
CoperaOmni('on', 'conversationStarted', handleConversationStarted);
// When this page component is removed:
CoperaOmni('off', 'unreadCount', handleUnread);
CoperaOmni('off', 'conversationStarted', handleConversationStarted);
Halten Sie die Callback-Referenz, wenn Sie off aufrufen wollen; eine neue Inline-Funktion ist nicht derselbe Listener.
Lifecycle-Events nutzen, um die Host-UI synchron zu halten:
CoperaOmni('on', 'ready', function () {
document.querySelector('#support-chat').disabled = false;
});
CoperaOmni('on', 'open', function () {
document.querySelector('#support-chat').setAttribute('aria-expanded', 'true');
});
CoperaOmni('on', 'close', function () {
document.querySelector('#support-chat').setAttribute('aria-expanded', 'false');
});
CoperaOmni('on', 'identityRequired', function () {
// Ask the signed-in host application to refresh its identity token.
void identifyCurrentUser();
});
Besucher-Identity
Wählen Sie, wie viel Sie über jeden Besucher wissen. Anonyme und Pre-Chat-Besucher brauchen kein Backend; verifizierte Besucher nutzen ein kurzlebiges, server-ausgestelltes Token.
- Anonymous
- Pre-chat form
- Verified
Require verified visitor identity aus lassen. Ein Besucher kann ohne Identity-Daten beginnen. Copera hält die Widget-Session des Browsers mit der Unterhaltung verknüpft.
Show a pre-chat form aktivieren, um den Besucher vor Beginn der Unterhaltung nach Details zu fragen. Vom Besucher eingegebene Informationen sind nützlicher Kontext, aber kein Beweis, dass der Besucher diese Identity besitzt.
Für einen angemeldeten Kunden tauscht Ihr same-origin-Backend seinen quellengebundenen Server-API-Key gegen ein kurzlebiges Identity-Token. Der Browser übergibt nur dieses Token an identify. Require verified visitor identity aktivieren, wenn anonyme und Pre-Chat-Unterhaltungen blockiert werden müssen.
identify mit { name, email } liefert unverifizierte Besucherdetails. Für authentifizierte Account-Identity nutzen Sie stattdessen { identityToken } — als Nächstes beschrieben.
Sichere verifizierte Identity
Verifizierte Identity hat drei Grenzen:
- Copera stellt einen quellengebundenen Server-API-Key mit dem Präfix
cp_omni_sk_aus. - Ihr Backend sendet eine stabile Kundenkennzeichnung an Copera und erhält ein fünf Minuten gültiges Identity-Token.
- Ihr Browser erhält nur das kurzlebige Token und übergibt es an das Widget.
Der Key cp_omni_sk_… gehört nur in den Secret Store Ihres Backends. Legen Sie ihn nie in HTML, Browser-JavaScript, eine Mobile-App, Logs, Analytics-Properties oder ein öffentliches Repository. Der öffentliche channelKey und der private Server-API-Key dienen unterschiedlichen Zwecken und sind nicht austauschbar.
Öffnen Sie das Panel Configure & install der Widget-Quelle. Unter Server API keys Create server key wählen, für ein Backend oder eine Umgebung benennen und sofort kopieren — er wird nur einmal angezeigt. Mehrere aktive Keys werden unterstützt, was Rotation ohne Teilen einer Credential über Umgebungen ermöglicht.
Speichern Sie ihn als rein serverseitige Umgebungsvariable, z. B. COPERA_OMNI_SERVER_KEY.
Ihr Backend ruft den Identity-Token-Endpunkt mit dem Server-Key auf:
POST https://api.copera.ai/public/v1/omni-channel/identity-tokens
Authorization: Bearer cp_omni_sk_...
Content-Type: application/json
Der Request-Body akzeptiert:
| Feld | Erforderlich | Beschreibung |
|---|---|---|
externalId | Ja | Opake, stabile, nicht-PII-Kennung des angemeldeten Kunden, gescoped auf Ihre Anwendung. Denselben Wert bei künftigen Besuchen verwenden. |
name | Nein | Aktueller Anzeigename aus Ihrem vertrauenswürdigen Account-Record. |
email | Nein | Aktuelle E-Mail-Adresse aus Ihrem vertrauenswürdigen Account-Record. |
Der Server-Key bindet die Anfrage bereits an einen Workspace und eine Web-Widget-Quelle; senden Sie keine Workspace-ID, Source-ID, Channel-ID oder channelKey in dieser Anfrage. Siehe die API-Referenz Create Omni identity token für das exakte Schema und die Antworten.
Die folgende Node.js-Route illustriert das same-origin-Muster. Sie setzt voraus, dass Ihre Anwendung die Anfrage bereits authentifiziert und den angemeldeten Benutzer als request.user bereitgestellt hat.
export async function postOmniIdentity(request, response) {
const user = request.user;
if (!user) {
return response.status(401).json({ message: 'Sign in required' });
}
const coperaResponse = await fetch(
'https://api.copera.ai/public/v1/omni-channel/identity-tokens',
{
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.COPERA_OMNI_SERVER_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
externalId: user.omniExternalId,
name: user.name,
email: user.email,
}),
},
);
if (!coperaResponse.ok) {
return response.status(502).json({ message: 'Unable to start support chat' });
}
const { identityToken, expiresAt } = await coperaResponse.json();
response.setHeader('Cache-Control', 'no-store');
return response.json({ identityToken, expiresAt });
}
Für dieselbe stabile externalId innerhalb dieser Widget-Quelle erstellt Copera den Kontakt beim ersten Mal und wiederverwendet denselben Kontakt bei künftigen verifizierten Sessions. Nutzen Sie einen opaken Wert, der für Ihre Anwendung erzeugt wurde. Nutzen Sie keine Anzeigenamen, E-Mail-Adressen, Telefonnummern, Usernames, sequenzielle Datenbank-IDs oder andere direkt identifizierende oder veränderliche Werte.
Stellen Sie die Route auf demselben Origin wie Ihre Anwendung bereit, verlangen Sie die normale authentifizierte Session und CSRF-Schutz der Anwendung und geben Sie nur das kurzlebige Token zurück:
async function identifyCurrentUser() {
const response = await fetch('/api/omni-identity', {
method: 'POST',
credentials: 'same-origin',
headers: {
'Content-Type': 'application/json',
'X-CSRF-Token': window.appCsrfToken,
},
});
if (!response.ok) {
throw new Error(`Omni identity request failed: ${response.status}`);
}
const { identityToken } = await response.json();
await CoperaOmni('identify', { identityToken });
}
CoperaOmni('init', { channelKey: 'YOUR_CHANNEL_KEY' });
void identifyCurrentUser().catch(function (error) {
console.error('Unable to identify the Omni visitor', error);
});
Identity-Tokens laufen fünf Minuten nach dem Minten ab. Minten Sie sie on demand und nutzen Sie sie sofort; persistieren Sie sie nicht in localStorage und behandeln Sie sie nicht als langlebiges Login-Token.
Rufen Sie CoperaOmni('logout') auf und awaiten Sie, bevor Sie einen anderen angemeldeten Benutzer auf derselben Browser-Seite identifzieren. Beim Abmelden der Anwendung logout aufrufen, auch wenn anonymer Chat verfügbar bleiben soll. Das verhindert, dass die Identity eines Kunden in die Session eines anderen rutscht.
async function switchOmniUser(nextUserIsSignedIn) {
await CoperaOmni('logout');
if (nextUserIsSignedIn) {
await identifyCurrentUser();
}
}
Wenn ein Besucher eine geschlossene Unterhaltung neu startet und Require verified visitor identity aktiv ist, emittiert das Widget identityRequired, damit der Host den Besucher erneut verifizieren kann. Fordern Sie ein frisches Token an und rufen Sie identify auf; fallen Sie nicht auf browser-gelieferte name und email zurück, als wären sie verifiziert. Beim ersten angemeldeten Besuch den Besucher proaktiv nach init identifzieren, wie oben gezeigt.
Browser-Origin-Sicherheit
Browser origin (recommended) prüft die einbettende Host-Seite gegen die Allowed origins der Quelle und etabliert eine kurzlebige, origin-gebundene Embed-Session. Fügen Sie den Origin der Seite hinzu, die das Widget hostet, z. B. https://support.example.com — nicht https://widget.copera.ai. Konfigurieren Sie exakte Origins inkl. Schema und Port, falls vorhanden:
| Seiten-URL | Allowed origin |
|---|---|
https://www.example.com/pricing | https://www.example.com |
https://app.example.com/support | https://app.example.com |
http://localhost:3000/account | http://localhost:3000 |
Pfade, Queries, Fragmente, Usernames und Passwörter sind kein Teil eines Origins. Jede Subdomain separat hinzufügen. Außerhalb der lokalen Entwicklung HTTPS bevorzugen.
Wählen Sie Browser origin (recommended) für neue Deployments und konfigurieren Sie jede erlaubte Origin explizit. Wenn Sie eine Production-Domain hinzufügen oder entfernen, Allowed origins aktualisieren, bevor Sie das Embed dort deployen. Eine Origin zu entfernen verhindert neue Embed-Sessions von dieser Origin.
Rotation und Widerruf
Behandeln Sie öffentlichen Embed-Key und Server-API-Keys als getrennte Credentials:
| Aktion | Sofortige Wirkung | Follow-up |
|---|---|---|
| Regenerate key | Bestehende Snippets mit dem alten channelKey funktionieren nicht mehr. | Key in jedem Embed ersetzen. |
| Revoke eines Server-API-Keys | Token-Minting-Anfragen mit diesem Key cp_omni_sk_… scheitern sofort. | Zuerst Ersatz-Key deployen, wenn die Integration verfügbar bleiben muss. |
Für Zero-Downtime-Server-Key-Rotation einen zweiten Key anlegen, im Backend deployen, bestätigen, dass Last used aktualisiert wird, dann den alten Key widerrufen. Getrennte Keys für Production, Staging und jedes unabhängige Backend verwenden.
Locale und Lifecycle
Initiale Locale in init setzen, dann update nutzen, wenn der Besucher die Sprache ändert:
CoperaOmni('init', {
channelKey: 'YOUR_CHANNEL_KEY',
locale: 'en',
});
function onApplicationLocaleChanged(locale) {
CoperaOmni('update', { locale });
}
Für eine Single-Page-Application:
initeinmal für die gemountete Widget-Integration aufrufen.- Mit
onabonnieren und Listener mitoffentfernen, wenn die besitzende Komponente unmountet. logoutaufrufen, wenn der Anwendungsbenutzer abmeldet oder wechselt.destroyaufrufen, wenn die Widget-Integration selbst dauerhaft entfernt wird oder Sie bewusst eine frische Instanz brauchen.
Fehlerbehebung
Das Widget-Script lädt nicht
Script-Laden absichern. Das direkte CDN-Snippet kann einen Netzwerk- oder CSP-Fehler mit dem error-Event des Script-Elements erkennen:
<script>
(function (w, d) {
w.CoperaOmni = w.CoperaOmni || function () {
(w.CoperaOmni.q = w.CoperaOmni.q || []).push(arguments);
};
var s = d.createElement('script');
s.async = 1;
s.src = 'https://widget.copera.ai/widget.js';
s.onerror = function () {
console.error('The Copera Omni widget could not be loaded.');
};
d.head.appendChild(s);
})(window, document);
CoperaOmni('init', { channelKey: 'YOUR_CHANNEL_KEY' });
</script>
Wenn die Anfrage blockiert wird, prüfen Sie Ihre Content Security Policy und bestätigen Sie, dass der Host-Page-Origin in Allowed origins steht.
Wie bestätige ich, dass die Initialisierung gelungen ist?
init, identify, logout und destroy können Promises zurückgeben, nachdem die Live-Runtime installiert ist. Awaiten Sie Identity- und Session-Übergänge und behandeln Sie Rejection. Wenn Sie den Live-Dispatcher direkt oder den typisierten Wrapper aufrufen, awaiten Sie init(), um die Backend-Initialisierung zu bestätigen.
Commands, die vor der Runtime-Installation gequeued werden, sind fire-and-forget; das Event ready bestätigt nur, dass der Iframe bereit ist und sein initialer State dispatched wurde — es beweist nicht, dass die Backend-Initialisierung gelungen ist.
Identity-Token-Anfragen scheitern
- Geben Sie einen generischen Fehler aus Ihrem Backend zurück; leiten Sie nie den Server-Key oder den Provider-Response-Body an den Browser weiter.
- Retryen Sie nur transiente Server-Fehler mit begrenztem Backoff.
- Minten Sie nach Ablauf ein neues Token statt ein altes zu replayen.
- Behandeln Sie
401vom Token-Endpunkt als fehlenden, fehlerhaften oder widerrufenen Server-Key und rotieren oder ersetzen Sie ihn. - Behandeln Sie
403als nicht verfügbare Widget-Quelle und prüfen Sie, dass die Quelle verbunden und nicht suspendiert ist.
Content Security Policy
Copera-Origins für eine strenge CSP allowlisten
Wenn Ihre Site Content Security Policy (CSP) nutzt, erlauben Sie die minimal erforderlichen Copera-Origins in den relevanten Directives:
script-src:https://widget.copera.aifürwidget.js.frame-src:https://widget.copera.aifür das Chat-Panel-Iframe.connect-src:https://api.copera.aifür Anfragen der Host-Seite.style-src: Die aktuelle Widget-Runtime erzeugt Style-Elemente und Style-Attribute und unterstützt keine Nonce- oder Hash-Alternative. Strikte CSP-Integration erfordert daher'unsafe-inline'nur instyle-src— nie inscript-srchinzufügen.- Ihre Policy muss auch den Inline-Bootstrap aus Quick embed erlauben. Wenn Ihre Policy Inline-Scripts blockiert, verschieben Sie den Bootstrap in eine erlaubte externe Datei oder autorisieren Sie ihn mit der Nonce- oder Hash-Policy Ihrer Site. Schwächen Sie die Policy nicht mit
'unsafe-inline'inscript-src. - Konfigurieren Sie den Origin der einbettenden Host-Seite unter Allowed origins, z. B.
https://support.example.com— nichthttps://widget.copera.ai. CSP-Erlaubnis ersetzt nicht Coperas Origin-Check.
Nach CSP-Änderungen unter CSP-Enforcement testen: Launcher, Panel öffnen, Unterhaltung starten, Unread-Update empfangen und verifizierte Identity in der Browser-Konsole ohne blockierte Anfragen prüfen.
Typisierter Wrapper und CDN-Runtime
Die CDN-Runtime unter https://widget.copera.ai/widget.js ist das Widget selbst und ist alles, was eine plain-HTML-Integration braucht. @copera/omni-widget-sdk ist ein optionaler typisierter Wrapper für TypeScript-Anwendungen: er injiziert dieselbe CDN-Runtime einmal, puffert frühe Aufrufe und stellt eine typisierte Facade für dieselben Commands und Events bereit. Er ersetzt weder das CDN-Widget noch ändert er den Server-Identity-Flow.
Nutzen Sie die direkten Runtime-Beispiele in diesem Leitfaden, sofern Ihre Anwendung den typisierten Wrapper nicht bereits konsumiert. Package-Installation und alternative Package-CDN-Anweisungen liegen absichtlich außerhalb dieses Embed-Leitfadens.
Häufig gestellte Fragen
Ist das Copera Omni Web-Widget kostenlos?
Das Web-Widget ist kostenlos. WhatsApp-Nummern, die mit einem Omni-Channel verbunden sind, sind bezahlte Add-ons, und das Entfernen einer WhatsApp-Quelle oder das Löschen ihres Channels storniert den gekauften Nummern-Slot nicht. Reduzieren Sie die gekaufte Menge separat unter Workspace Billing.
Ist der Widget-channelKey sicher im Browser-Code?
Ja. Der channelKey ist der öffentliche Key für eine Web-Widget-Quelle und gehört in den Embed-Code. Er ist keine Channel-ID, Source-ID oder privater Server-API-Key cp_omni_sk_…. Das Regenerieren des channelKey stoppt sofort Embeds, die noch den alten Wert nutzen.
Wie identifiziere ich einen angemeldeten Besucher sicher?
Authentifizieren Sie den Besucher im Anwendungs-Backend, tauschen Sie den quellengebundenen Key cp_omni_sk_… gegen ein fünf Minuten gültiges Identity-Token und geben Sie nur dieses kurzlebige Token an den Browser zurück. Rufen Sie dann CoperaOmni('identify', { identityToken }) auf. Geben Sie den Server-API-Key nie an den Browser oder einen Mobile-Client frei.
Wie schränke ich ein, welche Sites das Widget einbetten dürfen?
Wählen Sie Browser origin (recommended) und fügen Sie jede exakt erlaubte Origin inkl. Schema und Port (falls vorhanden) zu Allowed origins hinzu. Subdomains separat hinzufügen. Content-Security-Policy-Erlaubnisse ersetzen nicht Coperas Allowed-Origin-Check.
Verwandte Dokumentation
Wie das quellengebundene Backend-Credential sich von allgemeinen Public-API-Tokens unterscheidet.
Exakte Request-, Response- und Fehler-Schemas für den Identity-Token-Endpunkt.
Public-API-Messaging für reguläre Copera-Channels.
Wie der Omni-Identity-Token-Endpunkt in die Copera Public API passt.