@zickt/react

@zickt/react ist das offizielle React SDK zum Einbetten des Zickt-Chat-Widgets. Es bietet zwei Nutzungsmuster — eine Drop-in-Komponente (ZicktMessenger) für die Einrichtung ohne Konfiguration und einen Context Provider (ZicktProvider) mit einem useZickt-Hook für programmatische Steuerung von überall im Komponentenbaum.

Installation

npm install @zickt/react

Peer-Abhängigkeiten: React 18 oder 19 und das entsprechende react-dom.

Paketgröße: Unter 3 kB minified + brotli.

Überblick

Das Paket exportiert drei Runtime-Symbole und vierzehn Typ-Symbole.

Runtime-Exports:

• ZicktMessenger — Drop-in-Komponente; wrapped intern ZicktProvider
• ZicktProvider — Context Provider; verwende ihn, wenn Kindkomponenten useZickt benötigen
• useZickt — Hook, der den Kontextwert vom nächsten ZicktProvider zurückgibt

Typ-Exports:

ReactCommand, CSSColor, CSSFontFamily, CSSLength, CSSZIndex, ZicktAppearance, ZicktCallbacks, ZicktCompany, ZicktConfig, ZicktContextValue, ZicktIdentifyPayload, ZicktMessengerProps, ZicktProviderProps, ZicktUser

Das SDK lädt das Zickt-CDN-Skript (https://cdn.zickt.com/loader.js) zur Laufzeit und ist SSR-sicher: Es führt keine DOM-Operationen aus, wenn window undefiniert ist.

ZicktMessenger

import { ZicktMessenger } from '@zickt/react';

export default function App() {
  return (
    <>
      <YourApp />
      <ZicktMessenger channelKey="your-channel-key" />
    </>
  );
}

ZicktMessenger ist eine Drop-in-Komponente, die nur channelKey als Pflichtkonfiguration benötigt. Sie rendert nichts Sichtbares — das Chat-Widget wird durch das CDN SDK in die Seite injiziert. Intern rendert sie <ZicktProvider {...props}><></></ZicktProvider>, akzeptiert also alle ZicktConfig- und ZicktCallbacks-Props, aber keine children.

Props-Typ: ZicktMessengerProps = ZicktConfig & ZicktCallbacks

Config-Props

Callback-Props

ZicktProvider

Verwende ZicktProvider, wenn du useZickt aus Kindkomponenten aufrufen musst — zum Beispiel, um das Widget von einem Button tief im Komponentenbaum zu öffnen.

import { ZicktProvider } from '@zickt/react';

export default function App() {
  return (
    <ZicktProvider channelKey="your-channel-key">
      <YourApp />
    </ZicktProvider>
  );
}

Props-Typ: ZicktProviderProps extends ZicktConfig, ZicktCallbacks

ZicktProviderProps akzeptiert alle gleichen Config- und Callback-Props wie ZicktMessenger, plus children:

Lebenszyklus-Verhalten

• Beim Mounten wird das CDN-Skript einmal geladen. Falls das Script-Tag bereits im DOM vorhanden ist (manuell hinzugefügt), wird kein zweites angehängt.
• Nach dem Laden des Skripts startet das Widget mit dem bereitgestellten channelKey.
• Wenn sich user, company, appearance, customLauncherSelector oder hideDefaultLauncher nach dem Start ändern, aktualisiert sich das Widget automatisch ohne Neustart.
• Das Ändern von channelKey löst ein vollständiges Herunterfahren und einen Neustart aus.
• Beim Unmounten wird das Widget heruntergefahren und der interne Zustand zurückgesetzt.

useZickt

useZickt gibt den ZicktContextValue vom nächsten ZicktProvider zurück. Rufe ihn aus einer beliebigen Komponente innerhalb des Provider-Baums auf.

import { useZickt } from '@zickt/react';

export function SupportButton() {
  const { show, isReady } = useZickt();

  return (
    <button onClick={show} disabled={!isReady}>
      Mit uns chatten
    </button>
  );
}

Wirft "useZickt must be used within a <ZicktProvider>", wenn außerhalb eines Providers aufgerufen.

Rückgabetyp: ZicktContextValue

Alle Methoden sind stabile Referenzen, die mit useCallback erstellt wurden und sicher in useEffect-Abhängigkeitsarrays verwendet werden können.

Typen

ZicktConfig

Zentrale Konfigurationsschnittstelle, die von ZicktMessenger, ZicktProvider und der update-Methode geteilt wird.

interface ZicktConfig {
  channelKey: string;
  user?: ZicktUser;
  company?: ZicktCompany;
  appearance?: ZicktAppearance;
  customLauncherSelector?: string;
  hideDefaultLauncher?: boolean;
}

ZicktUser

Benutzeridentität, die beim Start über die user-Prop übergeben wird.

ZicktUser akzeptiert auch beliebige benutzerdefinierte Attribute über eine Index-Signatur: [key: string]: unknown.

ZicktCompany

Unternehmensidentität, die beim Start über die company-Prop übergeben wird.

ZicktCompany akzeptiert auch beliebige benutzerdefinierte Attribute über eine Index-Signatur: [key: string]: unknown.

ZicktIdentifyPayload

Erweiterte Payload für die identify()-Methode. Verwende identify nach dem Login, um eine Sitzung mit einer bekannten Identität zu verknüpfen.

Das company-Feld in ZicktIdentifyPayload akzeptiert id, name, domain, industry, size, plan, monthlySpend (Zahl) und custom (beliebige Schlüssel-Wert-Paare).

ZicktAppearance

Alle 14 Darstellungsfelder. Alle Felder sind optional. Änderungen an der Darstellung nach dem Start werden über die update-Methode automatisch angewendet, wenn sie als Prop übergeben werden, oder manuell über useZickt().update({ appearance: ... }).

Layout und Theme:

Markenidentität:

Feinschliff:

CSS-Typ-Aliase

CSSColor, CSSLength und CSSFontFamily sind dokumentierte String-Aliase — das SDK gibt sie ohne Laufzeitvalidierung an das zugrunde liegende Widget weiter.

type CSSColor = string; // hex, rgb, hsl oder benannte Farbe
type CSSLength = string; // muss Einheiten enthalten: '16px', '1rem', '50%', 'calc(100% - 20px)'
type CSSFontFamily = string; // z. B. '"Inter", sans-serif'
type CSSZIndex = number; // ganzzahliger z-index-Wert

ReactCommand

Union-Typ der 9 SDK-Befehle, die das React SDK bereitstellt.

type ReactCommand =
  | 'boot'
  | 'shutdown'
  | 'show'
  | 'hide'
  | 'showNewMessage'
  | 'update'
  | 'identify'
  | 'logout'
  | 'getVisitorId';

Dies ist eine kuratierte Teilmenge des vollständigen SDK-Befehlssatzes. Interne und Echtzeit-Befehle (wie sendMessage, connectRealtime, sendTypingIndicator) werden absichtlich nicht bereitgestellt.

Beispiele

Drop-in-Nutzung

Die einfachste Integration. Füge ZicktMessenger einmal im Root deiner App hinzu.

import { ZicktMessenger } from '@zickt/react';

export default function App() {
  return (
    <>
      <YourApp />
      <ZicktMessenger
        channelKey="your-channel-key"
        appearance={{ position: 'bottom-right', primaryColor: '#0066CC' }}
        onReady={() => console.log('Widget bereit')}
        onUnreadCountChanged={(count) =>
          (document.title = count > 0 ? `(${count}) Meine App` : 'Meine App')
        }
      />
    </>
  );
}

Provider und Hook

Verwende ZicktProvider im Root und useZickt in Kindkomponenten, um das Widget programmatisch zu öffnen.

import { ZicktProvider } from '@zickt/react';

export default function App() {
  return (
    <ZicktProvider channelKey="your-channel-key">
      <YourApp />
    </ZicktProvider>
  );
}

import { useZickt } from '@zickt/react';

export function HelpButton() {
  const { show, isReady } = useZickt();

  return (
    <button onClick={show} disabled={!isReady}>
      Hilfe erhalten
    </button>
  );
}

Eingeloggten Benutzer identifizieren

Rufe identify auf, nachdem sich der Benutzer authentifiziert hat, um die Besuchersitzung mit seinem Konto zu verknüpfen.

import { useEffect } from 'react';
import { useZickt } from '@zickt/react';

export function useAuthSync(user: AuthUser | null) {
  const { isReady, identify, logout } = useZickt();

  useEffect(() => {
    if (!isReady) return;

    if (user) {
      identify({
        id: user.id,
        email: user.email,
        name: user.displayName,
        signedUpAt: user.createdAt,
        custom: { plan: user.plan },
        company: {
          id: user.company.id,
          name: user.company.name,
          plan: user.company.plan,
        },
      });
    } else {
      logout();
    }
  }, [isReady, user, identify, logout]);
}

Benutzerdefinierter Launcher

Verstecke den Standard-Chat-Bubble und öffne das Widget über ein eigenes UI-Element.

import { ZicktProvider, useZickt } from '@zickt/react';

function CustomLaunchButton() {
  const { show } = useZickt();
  return <button onClick={show}>Support</button>;
}

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <ZicktProvider channelKey="your-channel-key" hideDefaultLauncher>
      {children}
      <CustomLaunchButton />
    </ZicktProvider>
  );
}

Darstellung nach dem Start ändern

Übergib aktualisierte Darstellungswerte als Prop oder rufe update direkt auf.

import { useZickt } from '@zickt/react';

export function ThemeSwitch({ isDark }: { isDark: boolean }) {
  const { update } = useZickt();

  useEffect(() => {
    update({ appearance: { theme: isDark ? 'dark' : 'light' } });
  }, [isDark, update]);

  return null;
}

Verwandte Seiten