Wrapper React

Un fournisseur et deux hooks au-dessus du SDK TypeScript. Il installe un seul client par page, si bien que le mode strict de React ne double pas vos événements.

Où il est publié

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

Installation

bun add @prodantix/sdk @prodantix/react

Le fournisseur

Montez ProdantixProvider une seule fois, près de la racine. Il crée le client web au premier montage puis le réutilise, car en créer un second corrigerait deux fois l'API History et doublerait chaque événement capté automatiquement.

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>
);

Nommer la personne connectée

person indique au fournisseur qui est connecté, sous forme de propriété plutôt que d'appel, si bien que la connexion et la déconnexion atteignent le client comme les valeurs qu'elles sont. Il a trois états, et chacun dit autre chose. undefined signifie que cette surface ne sait pas encore, parce que son authentification s'hydrate toujours, et le fournisseur ne fait rien. Une valeur identifie : le fournisseur appelle identify sur la première, puis de nouveau chaque fois que distinctId change, en portant les traits propres au SDK, avatar, e-mail, nom et téléphone. null signifie que la surface a consulté une session et n'a trouvé personne, et le fournisseur réinitialise le client si, et seulement si, il est encore identifié, ce qui fait tourner l'identifiant anonyme afin que le prochain visiteur sur ce navigateur ne soit pas la personne qui vient de se déconnecter. C'est cette règle qui fait tenir la déconnexion là où se déconnecter est une navigation dure et où aucune transition d'une valeur vers null n'est jamais rendue. C'est aussi pourquoi null ne doit jamais valoir chargement : une personne connectée qui recharge la page serait réinitialisée avant l'hydratation de l'authentification. Un montage qui ne consulte aucune session, une page vitrine ou une page de documentation, passe undefined, et une propriété absente se lit déjà comme 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>
  );
};

Les hooks

useProdantix renvoie le client de la page, ou null sur le serveur, avant l'exécution de l'effet et hors d'un fournisseur. useMessenger renvoie une poignée qui ouvre et ferme le widget, et reste null tant que la configuration du projet n'a pas été lue et ne le déclare pas activé.

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>
  );
};

Quand il n'envoie rien

Une application se livre de la même façon avec Prodantix désactivé : une clé ou un hôte manquant n'est donc pas une erreur. prodantixConfig indique si les deux valeurs sont présentes, et skipReason explique en une ligne pourquoi un montage n'enverra rien, au lieu de revenir en silence.

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));
}