Client SDK Übersicht

Das Univerx Client SDK (@univerx/client-sdk) ermöglicht es Ihnen, Echtzeit-Videoanrufe und Cobrowsing direkt in Ihre Webanwendung einzubetten. Wenn ein Besucher auf eine Hilfe-Schaltfläche klickt, tritt er in eine Support-Warteschlange ein, wird mit einem verfügbaren Agenten verbunden und kann seinen Bildschirm teilen – alles ohne Ihre Website zu verlassen.

Wann Sie das Client SDK verwenden sollten

• Sie möchten Live-Video-Support zu Ihrer eigenen Website oder Web-App hinzufügen.
• Sie benötigen Cobrowsing: Agenten sehen und interagieren in Echtzeit mit dem Browser des Besuchers.
• Ihr Team verwaltet Warteschlangen und Agenten im Univerx-Dashboard und Sie möchten das kundenseitige Widget auf Ihrer Domain haben.
• Sie erstellen eine benutzerdefinierte Benutzeroberfläche anstatt das gehostete Widget einzubetten.
• Sie benötigen detaillierte Kontrolle über Theming, Positionierung und Lifecycle-Events.

Installation

npm

npm install @univerx/client-sdk

yarn

yarn add @univerx/client-sdk

pnpm

pnpm add @univerx/client-sdk

CDN

<script src="https://cdn.univerx.ai/[email protected]/index.js"></script>

Hinweis

Der CDN-Build stellt UniverxWidget als globale Variable bereit. Verwenden Sie in diesem Fall new UniverxWidget.WidgetClient({ ... }).

Widget-Schlüssel erhalten

Bevor Sie das SDK initialisieren, benötigen Sie einen Widget-Schlüssel. Erstellen Sie einen in Ihrem Univerx-Dashboard unter Einstellungen → Widgets. Jeder Schlüssel ist an eine Reihe erlaubter Domains gebunden, stellen Sie also sicher, dass Sie auch den Ursprung Ihrer Website dort hinzufügen.

Speichern Sie den Schlüssel als Umgebungsvariable, damit er nicht in die Versionskontrolle übernommen wird:

UNIVERX_WIDGET_KEY=your-widget-key-here

Schnellstart

Der minimale Ablauf ist: instanziieren → init → Formular vor dem Anruf übermitteln (optional) → Warteschlange beitreten → Events behandeln.

import { WidgetClient } from "@univerx/client-sdk";

const widget = new WidgetClient({
  widgetKey: "your-widget-key-here", // required
  // baseUrl defaults to https://api.univerx.ai
});

// Initialise: authenticates with the Univerx API and sets up realtime channels
await widget.init();

// (optional) collect visitor details before placing them in the queue
await widget.submitForm({
  name: "Jane Smith",
  email: "[email protected]",
});

// join the support queue; pass consent flags your pre-call form collected
const ticket = await widget.joinQueue({
  terms: true,      // visitor accepted terms of service
  recording: false, // visitor declined recording consent
});

console.log("Queue position:", ticket.position);

// react to key lifecycle events
widget.on("agent:assigned", (agent) => {
  console.log(`Connected to agent: ${agent.name}`);
});

widget.on("call:started", () => {
  console.log("Video call is live");
});

widget.on("call:ended", () => {
  widget.destroy(); // clean up listeners and connections
});

React Integration

import { WidgetClient } from "@univerx/client-sdk";
import { useEffect, useRef } from "react";

export function SupportWidget() {
  const widgetRef = useRef<WidgetClient | null>(null);

  useEffect(() => {
    const widget = new WidgetClient({
      widgetKey: process.env.UNIVERX_WIDGET_KEY,
      onAgentAssigned: (agent) => console.log(`Agent: ${agent.name}`),
      onCallEnded: () => widgetRef.current?.destroy(),
    });

    widget.init();
    widgetRef.current = widget;

    return () => {
      widgetRef.current?.destroy();
    };
  }, []);

  // The SDK renders its own UI; this component is a lifecycle wrapper only
  return null;
}

Tipp

Rufen Sie immer widget.destroy() beim Unmount (oder wenn der Anruf endet) auf, um Echtzeit-Abonnements und WebRTC-Verbindungen zu bereinigen.

Konfigurationsreferenz

Option	Typ	Erforderlich	Beschreibung
widgetKey	string	Ja	Ihr Widget-Installationsschlüssel
baseUrl	string	Nein	API-Basis-URL. Standard ist https://api.univerx.ai
container	string | HTMLElement	Nein	Widget in einem bestimmten DOM-Element mounten
theme	WidgetTheme	Nein	Visuelle Anpassung: Farben, Position, Schriftart
cursor	CursorConfig	Nein	Einstellungen für die Sichtbarkeit des Agenten-Cursors
onReady	() => void	Nein	Wird aufgerufen, wenn das SDK initialisiert und bereit ist
onError	(error: Error) => void	Nein	Wird bei jedem unbehandelten SDK-Fehler aufgerufen
onAgentAssigned	(agent: Agent) => void	Nein	Wird aufgerufen, wenn ein Agent die Sitzung akzeptiert
onCallStarted	() => void	Nein	Wird aufgerufen, wenn der Videoanruf beginnt
onCallEnded	() => void	Nein	Wird aufgerufen, wenn der Videoanruf endet

Wichtige Events

Das SDK erweitert EventEmitter. Abonnieren Sie mit widget.on(event, handler).

Event	Payload	Beschreibung
ready	—	SDK initialisiert
queue:joined	QueueTicket	Besucher ist der Warteschlange beigetreten
queue:update	number	Warteschlangenposition hat sich geändert
queue:left	—	Besucher hat die Warteschlange verlassen
agent:assigned	Agent	Agent hat die Sitzung akzeptiert
call:started	—	Videoanruf ist aktiv
call:ended	—	Videoanruf beendet
cobrowse:started	—	Cobrowsing-Sitzung gestartet
cobrowse:ended	—	Cobrowsing-Sitzung beendet
error	Error	Unbehandelter Fehler

Nächste Schritte

Konfiguration Theming, Cursor-Optionen, benutzerdefinierter Container und Domain-Allowlisting.

API-Referenz: WidgetClient Vollständige Methoden- und Event-Referenz mit TypeScript-Signaturen.

React-Integrationsleitfaden Benutzerdefinierte Hooks und Next.js-Muster für React-Apps.

Fehlerbehebung Häufige Fehler, HTTP-Statuscodes und wie Sie sie beheben.

Fehlerbehebung

401 Unauthorized bei init

Ihr Widget-Schlüssel fehlt oder ist falsch. Überprüfen Sie den Wert, der an widgetKey übergeben wird. Stellen Sie außerdem sicher, dass die Domain, von der aus Sie aufrufen, unter Einstellungen → Widgets → Domains in Ihrem Dashboard auf der Allowlist steht.

Widget initialisiert, aber es erscheinen keine Agenten

Die Warteschlange ist möglicherweise leer oder es sind derzeit keine Agenten online. Überprüfen Sie den Bereich Warteschlangen in Ihrem Dashboard und stellen Sie sicher, dass das Widget unter Einstellungen → Widgets der richtigen Warteschlange zugewiesen ist.

CORS-Fehler in der Browser-Konsole

Ihre Domain muss zur Liste der erlaubten Domains des Widgets hinzugefügt werden. Öffnen Sie Einstellungen → Widgets, wählen Sie Ihr Widget aus und fügen Sie Ihren vollständigen Ursprung einschließlich Protokoll hinzu (z.B. https://example.com).

Rate-Limit-Fehler (429 Too Many Requests)

Der öffentliche init-Endpunkt ist auf 10 Anfragen pro Minute pro IP begrenzt. Vermeiden Sie es, widget.init() bei jedem Render aufzurufen – rufen Sie es einmal beim Component Mount auf und halten Sie die Instanz am Leben.