Wrapper React

Um provider e dois hooks sobre o SDK TypeScript. Ele instala um cliente por página, de modo que o modo estrito do React não duplica seus eventos.

Onde está publicado

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

Instalação

bun add @prodantix/sdk @prodantix/react

O provider

Monte o ProdantixProvider uma vez, perto da raiz. Ele cria o cliente web na primeira montagem e o reutiliza depois, porque criar um segundo aplicaria patch duas vezes na API History e duplicaria todo evento capturado automaticamente.

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

Nomear a pessoa autenticada

person diz ao provedor quem está autenticado, como propriedade e não como chamada, de modo que entrar e sair chegam ao cliente como os valores que são. Tem três estados e cada um diz algo diferente. undefined significa que esta superfície ainda não sabe, porque a sua autenticação ainda está hidratando, e o provedor não faz nada. Um valor identifica: o provedor chama identify no primeiro e de novo sempre que distinctId muda, levando os traços do próprio SDK, avatar, e-mail, nome e telefone. null significa que a superfície consultou uma sessão e não encontrou ninguém, e o provedor reinicia o cliente se, e somente se, ele ainda estiver identificado, o que rotaciona o id anônimo para que o próximo visitante naquele navegador não seja a pessoa que saiu. É essa regra que faz a saída valer onde sair é uma navegação dura e nenhuma transição de valor para null chega a ser desenhada. É também por isso que null nunca pode significar carregando: uma pessoa autenticada que recarrega a página seria reiniciada antes de a autenticação hidratar. Uma montagem que não consulta sessão alguma, uma página de captação ou uma página de documentação, passa undefined, e uma propriedade ausente já se lê como 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>
  );
};

Os hooks

useProdantix devolve o cliente da página, ou null no servidor, antes de o efeito rodar e fora de um provider. useMessenger devolve um handle que abre e fecha o widget, e permanece null até a configuração do projeto ser lida e indicar que está ligado.

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

Quando ele não envia nada

Um aplicativo é publicado do mesmo jeito com o Prodantix desligado, então uma chave ou host ausente não é um erro. prodantixConfig informa se os dois valores estão presentes, e skipReason diz em uma linha por que uma montagem não enviará nada, em vez de retornar em silêncio.

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