@tellio-test/widget

v1.0.2

Published

2 months ago

Tellio Widget wrapper for React applications

0High
0Medium
0Low

caiorafaeldop

tellio widget react feedback

Tellio React Widget

Componente oficial React para o Tellio — a forma mais simples de coletar feedbacks, reportar bugs, NPS e rastrear page views na sua aplicação React/Next.js.

Instalação

npm install @tellio-test/widget
# ou
yarn add @tellio-test/widget
# ou
pnpm add @tellio-test/widget

Quick Start (Exemplo Mínimo)

Importe o widget no seu arquivo de layout principal (ex: src/app/layout.tsx no Next.js ou src/App.tsx no React). O ID do widget é obrigatório.

import { TellioWidget } from '@tellio-test/widget';

export default function RootLayout({ children }) {
  return (
    <html lang="pt-BR">
      <body>
        {children}
        <TellioWidget id="SEU_WIDGET_ID" />
      </body>
    </html>
  );
}

Com identificação de usuário

Passe o usuário logado via propriedade user para saber quem está enviando o feedback ou acessando as páginas:

import { TellioWidget } from '@tellio-test/widget';

export default function RootLayout({ children }) {
  // Exemplo de usuário logado (pode vir do seu provider de auth)
  const user = {
    id: "user_123", // Obrigatório se passar o objeto user
    email: "[email protected]", 
    name: "João Silva",
  };

  return (
    <html lang="pt-BR">
      <body>
        {children}
        <TellioWidget 
          id="SEU_WIDGET_ID"
          user={user}
        />
      </body>
    </html>
  );
}

Com rastreamento automático de page views

Ative trackPageViews={true} para registrar automaticamente cada tela que o usuário acessa.

import { TellioWidget } from '@tellio-test/widget';

export default function RootLayout({ children }) {
  return (
    <html lang="pt-BR">
      <body>
        {children}
        <TellioWidget 
          id="SEU_WIDGET_ID"
          user={{ id: "user_123", email: "[email protected]" }}
          trackPageViews={true}
        />
      </body>
    </html>
  );
}

Nota: O rastreamento automático detecta mudanças de rota em SPAs (Next.js, React Router, etc.) ouvindo eventos da History API.

Com rastreamento manual via hook

Se você preferir controle total em vez do rastreamento automático (trackPageViews), pode usar o hook usePageLogger. Exemplo com Next.js App Router usando usePathname():

'use client';

import { usePathname } from 'next/navigation';
import { usePageLogger } from '@tellio-test/widget';

export function PageTracker({ widgetId, userId }: { widgetId: string; userId?: string }) {
  const pathname = usePathname();

  usePageLogger({
    widgetId,
    customerId: userId,
    pathname,
  });

  return null;
}

Adicione <PageTracker /> no seu layout global (onde tem acesso ao client context).

Props do `TellioWidget`

| Prop | Tipo | Padrão | Descrição | |------|------|--------|-----------| | id | string | obrigatório | ID do seu widget. Encontrado no painel Tellio. | | user | TellioUser | undefined | Objeto do usuário logado: { id: string, email?: string, name?: string, phone?: string }. | | src | string | undefined | URL customizada do script do widget (para self-hosting). | | onLoad | () => void | undefined | Callback chamado quando o script do widget termina de carregar. | | trackPageViews | boolean | false | Se true, ativa o rastreamento automático de rotas (page views). | | apiUrl | string | https://app.tellio.br| URL base da API do Tellio para onde os page views serão enviados (útil para self-hosting ou ambiente de dev local). |

Parâmetros do `usePageLogger`

| Parâmetro | Tipo | Padrão | Descrição | |-----------|------|--------|-----------| | widgetId | string | obrigatório | ID do seu widget Tellio. | | pathname | string | obrigatório | Rota atual a ser registrada (ex: usar usePathname() no Next.js). | | customerId | string | undefined | ID do usuário logado para vinculação analítica. | | apiUrl | string | https://app.tellio.br | URL base da API do Tellio para onde chamadas HTTP serão enviadas. |

🛡️ Privacidade e LGPD / GDPR

O Tellio foi desenhado respeitando a privacidade dos usuários:

O rastreamento de page views é estritamente opt-in. Ele só envia dados se você habilitar explicitamente (trackPageViews={true} ou chamando o hook usePageLogger).
O controle dos dados enviados é 100% do desenvolvedor do projeto. O campo user.id ou customerId é um identificador opaco. Você não precisa enviar o ID real do banco (pode usar um hash ou identificador gerado) nem enviar e-mails aos envios de página.
Não existem cookies instalados pelo rastreamento de páginas para contornar ou monitorar o usuário em diferentes sessões na web. Tudo é gerenciado através de requisições independentes.

Criado com ❤️ pela equipe Tellio.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme