React-Wrapper

Ein Provider und zwei Hooks über dem TypeScript-SDK. Es installiert einen Client pro Seite, sodass der Strict Mode von React Ihre Ereignisse nicht verdoppelt.

Wo es veröffentlicht ist

@prodantix/react on npm. It wraps @prodantix/sdk, so install both.

Installation

bun add @prodantix/sdk @prodantix/react

Der Provider

Hängen Sie ProdantixProvider einmal ein, nahe der Wurzel. Er erzeugt den Web-Client beim ersten Einhängen und verwendet ihn danach weiter, denn ein zweiter würde die History-API zweimal patchen und jedes automatisch erfasste Ereignis verdoppeln.

import { ProdantixProvider } from '@prodantix/react';

export const Providers = ({ children }: { children: ReactNode }) => (
  <ProdantixProvider
    options={{
      apiKey: process.env.NEXT_PUBLIC_PRODANTIX_KEY,
      host: 'https://eu.api.prodantix.com',
      messengerHost: 'https://eu.edge.prodantix.com',
    }}
  >
    {children}
  </ProdantixProvider>
);

Die angemeldete Person benennen

person sagt dem Provider, wer angemeldet ist, als Prop und nicht als Aufruf, sodass An- und Abmeldung den Client als die Werte erreichen, die sie sind. Es hat drei Zustände, und jeder sagt etwas anderes. undefined heißt, diese Oberfläche weiß es noch nicht, weil ihre Authentifizierung noch hydriert, und der Provider tut nichts. Ein Wert identifiziert: Der Provider ruft identify beim ersten Wert und erneut, sobald sich distinctId ändert, und trägt dabei die eigenen Merkmale des SDK, Avatar, E-Mail, Name und Telefon. null heißt, die Oberfläche hat eine Sitzung befragt und niemanden gefunden, und der Provider setzt den Client zurück, wenn, und nur wenn, er noch identifiziert ist, was die anonyme ID rotiert, damit der nächste Besucher in diesem Browser nicht die abgemeldete Person ist. Genau diese Regel lässt die Abmeldung dort halten, wo Abmelden eine harte Navigation ist und ein Übergang von Wert zu null nie gezeichnet wird. Sie ist auch der Grund, warum null nie für Laden stehen darf: Eine angemeldete Person, die die Seite neu lädt, würde zurückgesetzt, bevor die Authentifizierung hydriert. Eine Einbindung, die überhaupt keine Sitzung befragt, eine Landingpage oder eine Doku-Seite, übergibt undefined, und ein fehlendes Prop liest sich bereits als undefined.

import { ProdantixProvider } from '@prodantix/react';

export const Providers = ({ children }: { children: ReactNode }) => {
  const { session, status } = useSession();

  // undefined while auth hydrates, null once it has resolved to nobody,
  // the subject once it has resolved to someone.
  const person = status === 'loading' ? undefined : session ? { distinctId: session.sub } : null;

  return (
    <ProdantixProvider
      options={{
        apiKey: process.env.NEXT_PUBLIC_PRODANTIX_KEY,
        host: 'https://eu.api.prodantix.com',
        person,
      }}
    >
      {children}
    </ProdantixProvider>
  );
};

Die Hooks

useProdantix liefert den Client der Seite, oder null auf dem Server, vor dem Ausführen des Effekts und außerhalb eines Providers. useMessenger liefert einen Handle zum Öffnen und Schließen des Widgets und bleibt null, bis die Projektkonfiguration gelesen wurde und aktiviert meldet.

import { useMessenger, useProdantix } from '@prodantix/react';

export const HelpButton = () => {
  const prodantix = useProdantix();
  const messenger = useMessenger();

  // Both are null until the provider effect has run, so neither is assumed.
  return (
    <button
      onClick={() => {
        prodantix?.capture('help.opened');
        messenger?.open();
      }}
      type="button"
    >
      Get help
    </button>
  );
};

Wenn es nichts sendet

Eine App wird mit abgeschaltetem Prodantix genauso ausgeliefert, ein fehlender Schlüssel oder Host ist also kein Fehler. prodantixConfig sagt Ihnen, ob beide Werte vorliegen, und skipReason nennt in einer Zeile, warum ein Einhängen nichts senden wird, statt stillschweigend zurückzukehren.

import { prodantixConfig, skipReason } from '@prodantix/react';

const env = {
  host: process.env.NEXT_PUBLIC_PRODANTIX_HOST,
  key: process.env.NEXT_PUBLIC_PRODANTIX_KEY,
};

// null when either value is missing: the app runs with Prodantix switched off.
if (prodantixConfig(env) === null) {
  console.warn(skipReason(env, null));
}