Qualquer site

Instalar npm install @blipit/browser

O SDK de navegador do Blipit tem 10 KB. Ele captura erros não capturados, rejeições de promise não tratadas e requisições com falha, guarda os cliques e as requisições que levaram a cada erro, registra web vitals, coloca um botão Reportar erro em cada página e pode gravar um session replay quando ocorre um erro. Instale-o via npm em um app com bundler, ou coloque uma única tag script em qualquer página.

Cole-o no Claude Code, no Cursor ou em qualquer assistente de programação com IA. Inclui os passos e o código. Em app.blipit.io, em Chaves de API, o mesmo prompt já vem com a sua chave preenchida.
Vídeo: instalar o Blipit em qualquer stack, a partir de 0:32

1Obtenha suas chaves

Entre no app.blipit.io e abra Chaves de API na barra lateral, depois o seu projeto. Cada projeto tem duas chaves. A chave pública começa com blipit_pk_: ela vai no código do navegador e do app, só pode enviar eventos e é segura para qualquer pessoa ver. A chave secreta começa com blipit_sk_: ela fica no seu servidor ou no Odoo, nunca em um navegador, porque também pode ler e alterar problemas. A chave secreta é exibida uma única vez, logo depois de criada, então copie-a nesse momento; se você a perder, clique em Criar uma nova chave secreta, e a antiga para de funcionar na hora. Alguns SDKs também precisam do id do projeto, exibido na mesma página.

Chaves de API no app.blipit.io: a chave pública (blipit_pk_) para código de navegador e a chave secreta (blipit_sk_) para servidores e o Odoo.
Chaves de API no app.blipit.io: a chave pública (blipit_pk_) para código de navegador e a chave secreta (blipit_sk_) para servidores e o Odoo.
Uma nova chave secreta é exibida uma única vez. Copie-a agora: ela é armazenada com hash e não pode ser exibida novamente.
Uma nova chave secreta é exibida uma única vez. Copie-a agora: ela é armazenada com hash e não pode ser exibida novamente.

2Com npm

Chame init uma única vez no seu arquivo de entrada, antes de o app renderizar, com a chave pública. Com Vite (React, Vue, Svelte), mantenha a chave em .env como VITE_BLIPIT_KEY; só as variáveis VITE_ chegam ao navegador, e o servidor de desenvolvimento lê o .env apenas ao iniciar.

sh
npm install @blipit/browser
.env
VITE_BLIPIT_KEY=blipit_pk_your_public_key
src/main.js
import * as Blipit from "@blipit/browser";

Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  environment: import.meta.env.MODE,
  release: "2026.09.28",
  replay: { onErrorSampleRate: 1 },
});

3Sem bundler: uma tag script

Cole isto no <head> de todas as páginas, ou no espaço de código personalizado da sua plataforma, com a sua chave pública escrita nele. Não há problema: a chave pública só pode enviar eventos.

html
<script src="https://blipit.io/sdk/blipit.js"></script>
<script>
  Blipit.init({ key: "blipit_pk_your_public_key", environment: "production", release: "2026.09.28", replay: { onErrorSampleRate: 1 } });
</script>

4Mantenha as chaves fora do git

Mantenha as chaves em variáveis de ambiente ou nas configurações de segredos do seu host, nunca em código que você faz commit, e adicione seus arquivos .env ao .gitignore. Uma chave pública em uma página web é normal. Se uma chave secreta for parar no git, em uma página pública, em uma captura de tela ou em um chat, abra Chaves de API, clique em Criar uma nova chave secreta e cole a nova chave onde a antiga era usada: a chave antiga para de funcionar na hora.

.gitignore
.env
.env.local
.env.*.local

5Diga ao Blipit quem é o usuário (opcional)

Depois do login, anexe o usuário para que os problemas mostrem quem foi afetado e os replays possam ser encontrados por usuário.

js
Blipit.setUser({ id: "42", email: "ana@example.com" });

6React, Vue, Angular e Svelte: reporte os erros capturados

Os frameworks capturam erros dentro dos componentes antes que o navegador os veja, então passe esses erros ao Blipit também. Erros não capturados em qualquer outro lugar são reportados automaticamente.

React 19 (src/main.tsx)
createRoot(document.getElementById("root")!, {
  onCaughtError: (error) => Blipit.captureException(error),
  onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);
Ou, React 18 e anteriores: um error boundary
class ErrorBoundary extends React.Component<{ children: React.ReactNode }, { failed: boolean }> {
  state = { failed: false };
  static getDerivedStateFromError() {
    return { failed: true };
  }
  componentDidCatch(error: Error) {
    Blipit.captureException(error);
  }
  render() {
    return this.state.failed ? <p>Something went wrong.</p> : this.props.children;
  }
}
Vue (src/main.ts)
const app = createApp(App);
app.config.errorHandler = (err) => Blipit.captureException(err);
app.mount("#app");
Angular (app.config.ts)
import { ErrorHandler } from "@angular/core";
import * as Blipit from "@blipit/browser";

class BlipitErrorHandler implements ErrorHandler {
  handleError(error: unknown) {
    Blipit.captureException(error);
    console.error(error);
  }
}

export const appConfig = { providers: [{ provide: ErrorHandler, useClass: BlipitErrorHandler }] };
SvelteKit (src/hooks.client.ts)
import * as Blipit from "@blipit/browser";
import type { HandleClientError } from "@sveltejs/kit";

export const handleError: HandleClientError = ({ error }) => {
  Blipit.captureException(error);
};

7Relatórios de bugs: o botão Reportar erro

Assim que o SDK inicia com a sua chave pública, um botão Reportar erro aparece no canto inferior direito de cada página, no idioma do visitante. Um clique abre o formulário de relato: uma captura de tela da página para marcar, um seletor de elementos, uma gravação de tela opcional, e um título e uma descrição. Altere a posição, o estilo, o texto, a cor e o atalho de teclado no código, como abaixo, ou para todos os sites de uma vez no app.blipit.io, em Configurações do projeto, Widget de relatório de bugs; as opções no código prevalecem. O guia do botão de relatório de bug mostra cada opção com capturas de tela e uma demonstração ao vivo.

js
Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  feedbackWidget: {
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  },
});
O botão Reportar erro padrão, no canto inferior direito.
O botão Reportar erro padrão, no canto inferior direito.
O formulário de relato: uma captura de tela marcada, o título e o que aconteceu.
O formulário de relato: uma captura de tela marcada, o título e o que aconteceu.

8Abra o formulário de relato a partir do seu próprio botão

Para colocar um botão Reportar erro no seu próprio cabeçalho ou menu, use o oficial: Blipit.reportButton() devolve um botão pronto com o ícone do Blipit e Reportar erro no idioma do visitante, e apps React podem mostrar <BlipitReportButton /> de @blipit/nextjs/react (npm install @blipit/nextjs). Prefere o seu próprio design? Chame openReport() de qualquer manipulador de clique, ou attachReport(element) para ligar um elemento que já existe. Em ambos os casos o formulário abre exatamente como pelo botão flutuante. O ícone do Blipit só pode ser usado ao lado de Reportar erro, como mostra o botão oficial.

Botão oficial, HTML simples
<nav id="help-menu"></nav>
<script>
  document.getElementById("help-menu").append(Blipit.reportButton());
</script>
Botão oficial, React
import { BlipitReportButton } from "@blipit/nextjs/react";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton variant="outline" size="sm" />
    </header>
  );
}
Botão oficial, Vue
<script setup>
import { onMounted, ref } from "vue";
import { reportButton } from "@blipit/browser";

const slot = ref();
onMounted(() => slot.value.append(reportButton({ variant: "outline", size: "sm" })));
</script>

<template>
  <span ref="slot"></span>
</template>
HTML puro
<button id="report-issue">Report Issue</button>
<script>
  Blipit.attachReport(document.getElementById("report-issue"));
</script>

<button onclick="Blipit.openReport()">Report Issue</button>
React
import { openReport } from "@blipit/browser";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}
Vue
<script setup>
import { openReport } from "@blipit/browser";
</script>

<template>
  <button @click="openReport()">Report Issue</button>
</template>
O botão oficial Reportar erro no cabeçalho de um site.
O botão oficial Reportar erro no cabeçalho de um site.
Um botão personalizado Report Issue no cabeçalho da página abre o formulário de relato do Blipit.
Um botão personalizado Report Issue no cabeçalho da página abre o formulário de relato do Blipit.

9Ocultar o botão padrão

Para manter só o seu próprio botão, desative o flutuante com feedbackWidget: false no código (feedbackWidget={false} em <Blipit />), ou desligue Mostrar o botão de relatório nas configurações do Widget de relatório de bugs do projeto para ocultá-lo em todos os sites que usam a chave. openReport() e attachReport() continuam funcionando de qualquer forma.

js
Blipit.init({ key: import.meta.env.VITE_BLIPIT_KEY, feedbackWidget: false });

10Preencha o formulário de relato e adicione contexto

Chame setUser após o login: o nome e o e-mail de quem relata já vêm preenchidos, e essa pessoa recebe um e-mail quando você responde ou muda o status. setReportMetadata adiciona seus próprios campos, como o plano ou o tamanho do carrinho, a cada relatório; ele roda quando o relatório é enviado, então os valores estão sempre atualizados.

js
Blipit.setUser({ id: "42", username: "Ana Lima", email: "ana@example.com" });

Blipit.setReportMetadata(() => ({ plan: "pro", cartItems: cart.length }));

11Todas as opções e funções

  • key: a chave pública (blipit_pk_). Obrigatória.
  • environment e release: exibidos em cada evento; release alimenta regressões e source maps. environment tem production como padrão.
  • debug: true registra no console o que o SDK faz, em linhas que começam com [blipit].
  • sampleRate (0 a 1), ignoreErrors (strings ou padrões) e beforeSend (edite um evento ou retorne null para descartá-lo) controlam o que é enviado. autoMuteExtensions (ativado por padrão) descarta erros que vêm apenas de extensões do navegador.
  • webVitals (ativado por padrão), replay ({ sessionSampleRate, onErrorSampleRate }) e autoSessionTracking (taxas sem falhas, exige release).
  • feedbackWidget: false oculta o botão Reportar erro, ou um objeto com position, style, text, color, font, match e shortcut o altera. theme: "light", "dark" ou "auto" define o tema do formulário de relato.
  • user ({ id, name, email }) e company (um nome ou { id, name }) preenchem o formulário de relato e são adicionados aos relatórios.
  • endpoint: só para um ingest auto-hospedado; o padrão é https://in.blipit.io/api/v1/events.
  • Funções: captureException(error), captureMessage(text, level), setUser, setTag(key, value), addBreadcrumb({ category, message }), openReport(), attachReport(element), reportButton(options), updateWidget(options), setReportMetadata(fn), showFeedback() e flush(), que retorna uma promise quando os eventos na fila são enviados.
  • As configurações do widget alteradas no painel chegam aos navegadores em até uma hora, porque o SDK as guarda por esse tempo; uma janela anônima mostra a alteração na hora.

12Confira se funciona

Recarregue o seu site. O botão Reportar erro aparece no canto inferior direito e, em até um minuto, a visualização de página aparece em Web vitals no app.blipit.io. Depois envie um evento de teste: chame captureMessage uma vez no seu código ou, com a tag script, rode a linha abaixo no console do navegador. Ele aparece em Problemas em poucos segundos.

js
Blipit.captureMessage("Hello from " + location.host, "info");

13Se o botão ou os eventos não aparecerem

  • Abra o console do navegador e procure linhas que começam com [blipit]. Ative o debug (debug: true no init, ou debug em <Blipit />) para ver se o botão foi exibido, desativado no código ou ocultado pela configuração do projeto.
  • O Next.js só envia ao navegador as variáveis cujo nome começa com NEXT_PUBLIC_, então use NEXT_PUBLIC_BLIPIT_KEY. O Vite só envia variáveis VITE_, então use VITE_BLIPIT_KEY. Com qualquer outro nome, a chave fica vazia no navegador e o Blipit não inicia.
  • Reinicie o servidor de desenvolvimento depois de adicionar ou alterar .env ou .env.local. Ele os lê apenas ao iniciar.
  • Na Vercel ou em qualquer outro host, adicione a mesma variável nas variáveis de ambiente do projeto e faça o deploy novamente. Os valores NEXT_PUBLIC_ e VITE_ são gravados no build, então um deploy em execução nunca vê um valor adicionado depois.
  • Use a chave pública (blipit_pk_). Uma chave secreta (blipit_sk_) é recusada no navegador com um erro no console; se alguma já esteve em uma página, crie uma nova chave secreta.
  • No Next.js, <Blipit /> vai no app/layout.tsx raiz (ou em pages/_app.tsx) para rodar em todas as páginas. Em outros apps, chame init uma única vez no arquivo de entrada, antes de o app renderizar.
  • Mostrar o botão de relatório precisa estar ativado no app.blipit.io, em Configurações do projeto, Widget de relatório de bugs, e o seu código não pode passar feedbackWidget: false. O SDK guarda as configurações do projeto por até uma hora, então teste uma alteração em uma janela anônima.
  • Bloqueadores de anúncios e extensões de privacidade podem bloquear in.blipit.io. Teste em uma janela anônima com as extensões desativadas.
  • Se o seu site envia uma Content Security Policy, permita script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: e media-src blob:. O editor do relato carrega de blipit.io/sdk no primeiro clique, a captura é desenhada a partir de uma imagem data: e as gravações de tela também são enviadas para in.blipit.io. Com debug ativado, o console avisa quando a política bloqueou a captura. Para que as gravações de tela tenham voz, o cabeçalho Permissions-Policy do site precisa permitir microphone=(self), e display-capture=(self) para a gravação de tela; com microphone=() as gravações funcionam sem som.
  • Confira a versão instalada com npm ls @blipit/browser @blipit/nextjs (ou pnpm list @blipit/browser @blipit/nextjs) e compare com o changelog. O pnpm 11 espera um dia antes de instalar uma versão nova (minimum-release-age), então no dia do lançamento o pnpm add instala a versão anterior sem avisar. Para pegar a nova na hora: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Travou? Envie um e-mail para support@blipit.io com as linhas [blipit] do console.

Bom saber

  • Opções: sampleRate (0 a 1), ignoreErrors (strings ou padrões), beforeSend para descartar ou editar um evento, maxBreadcrumbs, webVitals (ativado por padrão), autoSessionTracking para taxas sem falha (precisa de release).
  • blipit.io/sdk/blipit.js sempre serve a versão mais recente (0.3.23). As versões fixas ficam em blipit.io/sdk/0.3.23/blipit.js, se você quiser controlar as atualizações.
  • Se o seu site envia uma Content Security Policy, permita script-src https://blipit.io (a tag script, e o editor do relato e o complemento de replay, que carregam de blipit.io/sdk/<version>/ no primeiro uso), connect-src https://in.blipit.io (eventos, capturas e gravações de tela vão todos para in.blipit.io), img-src data: (a captura é desenhada a partir de uma imagem da página) e media-src blob: (as gravações são reproduzidas no relato). A captura recarrega as imagens e fontes da página, então os hosts delas também precisam estar em connect-src, senão ficam em branco. Não é preciso mudar style-src. Com a tag script, chame Blipit.init a partir do seu próprio arquivo .js ou dê um nonce ao script inline, porque uma política rígida bloqueia scripts inline. Para que as gravações de tela tenham voz, o cabeçalho Permissions-Policy do site precisa permitir microphone=(self), e display-capture=(self) para a gravação de tela; com microphone=() as gravações funcionam sem som.
  • Manter o Blipit atualizado: o guia Manter o Blipit atualizado (docs.blipit.io/updates) explica o banner de atualização, os e-mails de versões importantes, o aviso no seu console de desenvolvimento e o comando de atualização para esta plataforma.
  • Um projeto por app e plataforma: cada projeto escolhe a sua plataforma quando é criado (Android, iOS, React Native, Flutter, Web, Backend ou Odoo), e o Blipit recusa com um erro claro os dados de qualquer outra plataforma, por isso uma app iOS e uma app Android precisam de dois projetos com duas chaves. Releases, versões, taxas de falhas e builds das lojas são diferentes em cada plataforma, e misturá-los num projeto torna todos errados. Um projeto Web também aceita o lado servidor da mesma app web (o servidor Next.js ou Node), e um projeto React Native ou Flutter também aceita os seus próprios relatórios de falhas nativos de Android e iOS.

Travou? Envie um e-mail para support@blipit.io. As chaves e o id de cada projeto ficam em Chaves de API no app.blipit.io.