Instalar por plataforma
Next.js e React
Instalar npm install @blipit/nextjs
O @blipit/nextjs oferece erros do navegador, web vitals, session replay e o botão Reportar erro a partir de um único componente no seu layout, além de erros de server components, route handlers e server actions com uma linha em instrumentation.ts. Apps React puros usam @blipit/browser.
1Instalar
npm install @blipit/nextjs2Obtenha 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.
3Coloque as chaves em .env.local
Crie .env.local na raiz do projeto com a chave pública para o navegador e, se você usar o lado do servidor abaixo, a chave secreta para o servidor. Só os nomes que começam com NEXT_PUBLIC_ chegam ao navegador, então nunca dê esse prefixo à chave secreta. Reinicie o npm run dev depois de salvar o arquivo. Para produção, adicione as mesmas variáveis no seu host (na Vercel: Project, Settings, Environment Variables, para Production e Preview) e faça o deploy novamente: os valores NEXT_PUBLIC_ são gravados no build, então um deploy feito antes de você adicioná-los tem a chave vazia.
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key4Lado do navegador
Adicione o componente uma única vez no layout raiz. Ele lê a chave pública de NEXT_PUBLIC_BLIPIT_KEY. Se a variável estiver vazia, ele não inicia nada e avisa no console do navegador.
import { Blipit } from "@blipit/nextjs";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
<Blipit
publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!}
environment={process.env.NEXT_PUBLIC_VERCEL_ENV ?? "development"}
release={process.env.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA}
replay={{ onErrorSampleRate: 1 }}
/>
{children}
</body>
</html>
);
}5Lado do servidor
O Next.js 15 e posteriores chamam onRequestError para erros em server components, route handlers e server actions. Uma linha em instrumentation.ts o conecta ao Blipit. A partir do @blipit/nextjs 0.2.1, a mesma linha também funciona em apps com um middleware.ts e em rotas Edge (runtime = "edge"): o app compila, e os erros do middleware e do Edge também são reportados. O Next.js 14 não tem onRequestError, então envolva cada route handler e server action com withBlipit, como no segundo exemplo: ele reporta o erro e o lança de novo, e ignora redirecionamentos e notFound(). Defina BLIPIT_SECRET_KEY no ambiente do servidor, nunca como NEXT_PUBLIC_.
export { captureRequestError as onRequestError } from "@blipit/nextjs/server";import { withBlipit } from "@blipit/nextjs/server";
export const GET = withBlipit(async (request: Request) => {
return Response.json(await loadOrders());
});6Dependências e saúde do servidor
A partir do @blipit/nextjs 0.3, exporte também register para que o Blipit arranque com o servidor. Assim regista as chamadas à base de dados e a serviços externos na página Dependências, e o CPU, memória e event loop do servidor em Saúde do servidor. Não faz nada no runtime Edge. Na Vercel, register pode não ver o pedido recebido: a partir de @blipit/nextjs 0.4, envolva os route handlers e server actions em withBlipit e cada um passa a ser um pedido na página Pulse com as suas chamadas à base de dados e a serviços externos, enviado depois da resposta sem a atrasar.
export { captureRequestError as onRequestError, register } from "@blipit/nextjs/server";import { withBlipit } from "@blipit/nextjs/server";
export const GET = withBlipit(async (request: Request) => Response.json(await loadOrders()));7Erros capturados por error.tsx
Erros que um boundary error.tsx ou global-error.tsx captura nunca chegam ao handler de erros do navegador, então reporte-os a partir do boundary. Os dois arquivos são client components.
"use client";
import { useEffect } from "react";
import { captureException } from "@blipit/nextjs";
export default function Error({ error, reset }: { error: Error & { digest?: string }; reset: () => void }) {
useEffect(() => {
captureException(error);
}, [error]);
return (
<div>
<p>Something went wrong.</p>
<button onClick={() => reset()}>Try again</button>
</div>
);
}"use client";
import { useEffect } from "react";
import { captureException } from "@blipit/nextjs";
export default function GlobalError({ error }: { error: Error & { digest?: string } }) {
useEffect(() => {
captureException(error);
}, [error]);
return (
<html>
<body>
<p>Something went wrong.</p>
</body>
</html>
);
}8Mantenha 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.
.env
.env.local
.env.*.local9Content Security Policy
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.
10Source maps (opcional)
Para que os stack traces mostrem seu código-fonte em vez do bundle minificado, envie os maps de cada release a partir da sua etapa de build.
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"14Preencha 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.
"use client";
import { useEffect } from "react";
import { setReportMetadata, setUser } from "@blipit/nextjs";
export function BlipitUser({ user }: { user: { id: string; name: string; email: string; plan: string } }) {
useEffect(() => {
setUser({ id: user.id, username: user.name, email: user.email });
setReportMetadata(() => ({ plan: user.plan }));
}, [user]);
return null;
}15Confira se funciona
Recarregue o app. 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 adicione um botão que chama captureMessage, ou um que lança um erro, e clique nele: o evento aparece em Problemas em poucos segundos.
"use client";
import { captureMessage } from "@blipit/nextjs";
export function TestBlipit() {
return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}Bom saber
- React simples sem Next.js: npm install @blipit/browser e chame Blipit.init antes de renderizar; veja Qualquer site.
- Ambiente e release usam VERCEL_ENV e VERCEL_GIT_COMMIT_SHA como padrão no servidor quando você os omite.
- 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.





