Installazione per piattaforma
Next.js e React
Installazione npm install @blipit/nextjs
@blipit/nextjs ti dà errori del browser, web vitals, session replay e il pulsante Segnala un bug con un solo componente nel layout, e gli errori di server component, route handler e server action con una sola riga in instrumentation.ts. Le app React semplici usano @blipit/browser.
1Installazione
npm install @blipit/nextjs2Ottieni le chiavi
Accedi su app.blipit.io e apri Chiavi API nella barra laterale, poi il tuo progetto. Ogni progetto ha due chiavi. La chiave pubblica inizia con blipit_pk_: va nel codice del browser e delle app, può solo inviare eventi e chiunque può vederla senza rischi. La chiave segreta inizia con blipit_sk_: resta sul tuo server o in Odoo, mai in un browser, perché può anche leggere e modificare le issue. La chiave segreta viene mostrata una sola volta, subito dopo la creazione, quindi copiala in quel momento; se la perdi, premi Crea una nuova chiave segreta e quella vecchia smette subito di funzionare. Alcuni SDK richiedono anche l'id del progetto, mostrato nella stessa pagina.
3Metti le chiavi in .env.local
Crea .env.local nella root del progetto con la chiave pubblica per il browser e, se usi la parte server qui sotto, la chiave segreta per il server. Solo i nomi che iniziano con NEXT_PUBLIC_ arrivano al browser, quindi non dare mai quel prefisso alla chiave segreta. Riavvia npm run dev dopo aver salvato il file. Per la produzione, aggiungi le stesse variabili nel tuo host (su Vercel: Project, Settings, Environment Variables, per Production e Preview) e fai di nuovo il deploy: i valori NEXT_PUBLIC_ vengono scritti nella build, quindi un deploy fatto prima di aggiungerli ha una chiave vuota.
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key4Lato browser
Aggiungi il componente una sola volta nel layout principale. Legge la chiave pubblica da NEXT_PUBLIC_BLIPIT_KEY. Se la variabile è vuota, non avvia nulla e lo segnala nella console del browser.
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>
);
}5Lato server
Next.js 15 e successivi chiamano onRequestError per gli errori in server component, route handler e server action. Una riga in instrumentation.ts lo collega a Blipit. Da @blipit/nextjs 0.2.1 la stessa riga funziona anche nelle app con un middleware.ts e nelle route Edge (runtime = "edge"): l'app si compila e vengono segnalati anche gli errori del middleware e di Edge. Next.js 14 non ha onRequestError, quindi avvolgi ogni route handler e server action in withBlipit, come nel secondo esempio: segnala l'errore e lo rilancia, e salta i redirect e notFound(). Imposta BLIPIT_SECRET_KEY nell'ambiente del server, mai come 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());
});6Dipendenze e stato dei server
Da @blipit/nextjs 0.3 esporta anche register, così Blipit parte all'avvio del server. Registra quindi le chiamate al database e ai servizi esterni nella pagina Dipendenze, e CPU, memoria ed event loop del server in Stato dei server. Nel runtime Edge non fa nulla. Su Vercel, register potrebbe non vedere la richiesta in arrivo: da @blipit/nextjs 0.4, avvolgi route handler e server action in withBlipit e ognuno diventa una richiesta nella pagina Pulse con le sue chiamate al database e ai servizi esterni, inviata dopo la risposta senza rallentarla.
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()));7Errori catturati da error.tsx
Gli errori catturati da un boundary error.tsx o global-error.tsx non arrivano mai al gestore degli errori del browser, quindi segnalali dal boundary. Entrambi i file sono client component.
"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>
);
}8Tieni le chiavi fuori da git
Tieni le chiavi in variabili d'ambiente o nelle impostazioni dei secret del tuo host, mai nel codice che fai commit, e aggiungi i tuoi file .env a .gitignore. Una chiave pubblica in una pagina web è normale. Se una chiave segreta finisce in git, in una pagina pubblica, in uno screenshot o in una chat, apri Chiavi API, premi Crea una nuova chiave segreta e incolla la nuova chiave ovunque usavi quella vecchia: la vecchia chiave smette di funzionare subito.
.env
.env.local
.env.*.local9Content Security Policy
Se il tuo sito invia una Content Security Policy, consenti script-src https://blipit.io (il tag script, l'editor della segnalazione e il modulo di replay, che si caricano da blipit.io/sdk/<version>/ al primo utilizzo), connect-src https://in.blipit.io (eventi, screenshot e registrazioni dello schermo vanno tutti a in.blipit.io), img-src data: (lo screenshot viene disegnato da un'immagine della pagina) e media-src blob: (le registrazioni vengono riprodotte nella segnalazione). Lo screenshot ricarica le immagini e i font della pagina, quindi anche i loro host vanno in connect-src, altrimenti restano vuoti. Non serve modificare style-src. Con il tag script, chiama Blipit.init da un tuo file .js o assegna un nonce allo script inline, perché una policy rigorosa blocca gli script inline. Perché le registrazioni dello schermo abbiano l'audio, l'header Permissions-Policy del sito deve consentire microphone=(self), e display-capture=(self) per la registrazione dello schermo; con microphone=() le registrazioni funzionano senza audio.
10Source map (facoltativo)
Perché gli stack trace mostrino il tuo sorgente invece del bundle minificato, carica le map di ogni release dal tuo passaggio di build.
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"14Precompilare il modulo di segnalazione e aggiungere contesto
Chiama setUser dopo l'accesso: nome ed email di chi segnala vengono compilati, e riceve un'email quando rispondi o cambi lo stato. setReportMetadata aggiunge i tuoi campi, come il piano o la dimensione del carrello, a ogni segnalazione; viene eseguita quando la segnalazione viene inviata, quindi i valori sono aggiornati.
"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;
}15Verifica che funzioni
Ricarica l'app. Il pulsante Segnala un bug compare nell'angolo in basso a destra, e entro un minuto la visualizzazione di pagina compare in Web vitals su app.blipit.io. Poi aggiungi un pulsante che chiama captureMessage, o uno che lancia un errore, e cliccalo: l'evento compare in Issue entro pochi secondi.
"use client";
import { captureMessage } from "@blipit/nextjs";
export function TestBlipit() {
return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}Buono a sapersi
- React semplice senza Next.js: npm install @blipit/browser e chiama Blipit.init prima del rendering; vedi Qualsiasi sito web.
- Ambiente e release sul server usano per impostazione predefinita VERCEL_ENV e VERCEL_GIT_COMMIT_SHA quando li ometti.
- Tenere Blipit aggiornato: la guida Tenere Blipit aggiornato (docs.blipit.io/updates) spiega il banner di aggiornamento, le email per le versioni importanti, l'avviso nella console di sviluppo e il comando di aggiornamento per questa piattaforma.
- Un progetto per app e piattaforma: ogni progetto sceglie la sua piattaforma quando viene creato (Android, iOS, React Native, Flutter, Web, Backend o Odoo) e Blipit rifiuta con un errore chiaro i dati di qualsiasi altra piattaforma, quindi un'app iOS e un'app Android hanno bisogno di due progetti con due chiavi. Release, versioni, tassi di crash e build per gli store sono diversi per ogni piattaforma, e mescolarli in un progetto li rende tutti sbagliati. Un progetto Web accetta anche la parte server della stessa app web (il server Next.js o Node), e un progetto React Native o Flutter accetta anche i propri crash nativi Android e iOS.
Bloccato? Scrivi a support@blipit.io. Le chiavi e l'id di ogni progetto sono sotto Chiavi API in app.blipit.io.





