Installation nach Plattform
Next.js und React
Installation npm install @blipit/nextjs
@blipit/nextjs liefert Ihnen Browser-Fehler, Web Vitals, Session Replay und den Button Fehler melden über eine einzige Komponente in Ihrem Layout, und Fehler aus Server Components, Route Handlern und Server Actions über eine einzige Zeile in instrumentation.ts. Reine React-Apps verwenden @blipit/browser.
1Installation
npm install @blipit/nextjs2Schlüssel abrufen
Melden Sie sich bei app.blipit.io an und öffnen Sie API-Schlüssel in der Seitenleiste, dann Ihr Projekt. Jedes Projekt hat zwei Schlüssel. Der öffentliche Schlüssel beginnt mit blipit_pk_: Er gehört in Browser- und App-Code, kann nur Events senden und darf von jedem gesehen werden. Der geheime Schlüssel beginnt mit blipit_sk_: Er bleibt auf Ihrem Server oder in Odoo, nie in einem Browser, weil er auch Issues lesen und ändern kann. Der geheime Schlüssel wird nur einmal angezeigt, direkt nach der Erstellung, kopieren Sie ihn also dann; geht er verloren, klicken Sie auf Neuen geheimen Schlüssel erstellen, und der alte funktioniert sofort nicht mehr. Manche SDKs brauchen zusätzlich die Projekt-ID, die auf derselben Seite steht.
3Die Schlüssel in .env.local ablegen
Legen Sie im Projektstamm .env.local an, mit dem öffentlichen Schlüssel für den Browser und, falls Sie die Serverseite unten nutzen, dem geheimen Schlüssel für den Server. Nur Namen, die mit NEXT_PUBLIC_ beginnen, erreichen den Browser, geben Sie dem geheimen Schlüssel dieses Präfix also nie. Starten Sie npm run dev nach dem Speichern der Datei neu. Für die Produktion fügen Sie dieselben Variablen bei Ihrem Hoster hinzu (auf Vercel: Project, Settings, Environment Variables, für Production und Preview) und deployen erneut: NEXT_PUBLIC_-Werte werden in den Build geschrieben, daher hat ein Deployment, das vor dem Hinzufügen erstellt wurde, einen leeren Schlüssel.
NEXT_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
BLIPIT_SECRET_KEY=blipit_sk_your_secret_key4Browserseite
Fügen Sie die Komponente einmal im Root-Layout ein. Sie liest den öffentlichen Schlüssel aus NEXT_PUBLIC_BLIPIT_KEY. Ist die Variable leer, startet sie nichts und meldet das in der Browser-Konsole.
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>
);
}5Serverseite
Next.js 15 und neuer rufen onRequestError bei Fehlern in Server Components, Route Handlers und Server Actions auf. Eine Zeile in instrumentation.ts verbindet es mit Blipit. Ab @blipit/nextjs 0.2.1 funktioniert dieselbe Zeile auch in Apps mit einer middleware.ts und in Edge-Routen (runtime = "edge"): Die App lässt sich bauen, und Fehler aus Middleware und Edge werden ebenfalls gemeldet. Next.js 14 hat kein onRequestError; umschließen Sie dort jeden Route Handler und jede Server Action mit withBlipit, wie im zweiten Beispiel: Es meldet den Fehler, wirft ihn erneut und lässt Redirects und notFound() aus. Setzen Sie BLIPIT_SECRET_KEY in der Server-Umgebung, nie als 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());
});6Abhängigkeiten und Serverzustand
Ab @blipit/nextjs 0.3 exportierst du auch register, damit Blipit beim Serverstart beginnt. Dann erscheinen Datenbank- und externe Aufrufe unter Abhängigkeiten und CPU, Speicher und Event-Loop des Servers unter Serverzustand. In der Edge-Runtime tut es nichts. Auf Vercel sieht register die eingehende Anfrage womöglich nicht: Ab @blipit/nextjs 0.4 umschließen Sie Route Handler und Server Actions mit withBlipit, dann wird jeder zu einer Anfrage auf der Seite Pulse mit ihren Datenbank- und externen Aufrufen, gesendet nach der Antwort, ohne sie zu verzögern.
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()));7Von error.tsx abgefangene Fehler
Fehler, die eine error.tsx- oder global-error.tsx-Boundary abfängt, erreichen den Fehler-Handler des Browsers nie, melden Sie sie daher aus der Boundary. Beide Dateien sind 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>
);
}8Schlüssel aus Git heraushalten
Bewahren Sie Schlüssel in Umgebungsvariablen oder den Secret-Einstellungen Ihres Hosters auf, nie in Code, den Sie committen, und tragen Sie Ihre .env-Dateien in .gitignore ein. Ein öffentlicher Schlüssel in einer Webseite ist normal. Landet ein geheimer Schlüssel je in Git, auf einer öffentlichen Seite, in einem Screenshot oder einem Chat, öffnen Sie API-Schlüssel, klicken Sie auf Neuen geheimen Schlüssel erstellen und fügen Sie den neuen Schlüssel überall ein, wo der alte verwendet wurde: Der alte Schlüssel funktioniert sofort nicht mehr.
.env
.env.local
.env.*.local9Content Security Policy
Wenn Ihre Website eine Content Security Policy sendet, erlauben Sie script-src https://blipit.io (das Script-Tag sowie den Reporter-Editor und das Replay-Add-on, die beim ersten Gebrauch von blipit.io/sdk/<version>/ geladen werden), connect-src https://in.blipit.io (Ereignisse, Screenshots und Bildschirmaufnahmen gehen alle an in.blipit.io), img-src data: (der Screenshot wird aus einem Bild der Seite gezeichnet) und media-src blob: (Aufnahmen werden im Reporter abgespielt). Der Screenshot lädt die Bilder und Schriften der Seite neu, daher gehören deren Hosts ebenfalls in connect-src, sonst bleiben sie leer. Eine Änderung an style-src ist nicht nötig. Rufen Sie beim Script-Tag Blipit.init aus einer eigenen .js-Datei auf oder geben Sie dem Inline-Script eine Nonce, denn eine strenge Policy blockiert Inline-Scripts. Damit Bildschirmaufnahmen Ton enthalten, muss der Permissions-Policy-Header Ihrer Website microphone=(self) erlauben, für die Bildschirmaufnahme außerdem display-capture=(self); mit microphone=() funktionieren Aufnahmen ohne Ton.
10Source Maps (optional)
Damit Stack Traces Ihren Quellcode statt des minifizierten Bundles zeigen, laden Sie die Maps für jedes Release aus Ihrem Build-Schritt hoch.
BLIPIT_KEY=<secret key> npx @blipit/cli sourcemaps upload .next/static --release "$VERCEL_GIT_COMMIT_SHA"14Den Reporter vorausfüllen und Kontext hinzufügen
Rufen Sie setUser nach der Anmeldung auf: Name und E-Mail der meldenden Person werden vorausgefüllt, und sie erhält eine E-Mail, wenn Sie antworten oder den Status ändern. setReportMetadata fügt jedem Bericht eigene Felder hinzu, etwa den Plan oder die Warenkorbgröße; die Funktion läuft beim Senden eines Berichts, daher sind die Werte aktuell.
"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;
}15Prüfen, ob es funktioniert
Laden Sie die App neu. Der Button Fehler melden erscheint unten rechts, und innerhalb einer Minute erscheint der Seitenaufruf unter Web Vitals in app.blipit.io. Fügen Sie dann einen Button hinzu, der captureMessage aufruft oder einen Fehler wirft, und klicken Sie darauf: Das Event erscheint innerhalb weniger Sekunden unter Issues.
"use client";
import { captureMessage } from "@blipit/nextjs";
export function TestBlipit() {
return <button onClick={() => captureMessage("Hello from Next.js")}>Send a test event</button>;
}Gut zu wissen
- Reines React ohne Next.js: npm install @blipit/browser und Blipit.init vor dem Rendern aufrufen; siehe Beliebige Website.
- Umgebung und Release fallen auf dem Server auf VERCEL_ENV und VERCEL_GIT_COMMIT_SHA zurück, wenn Sie sie weglassen.
- Blipit aktuell halten: Die Anleitung „Blipit auf dem neuesten Stand halten“ (docs.blipit.io/updates) erklärt das Update-Banner, die E-Mails zu wichtigen Releases, den Hinweis in deiner Entwicklungskonsole und den Update-Befehl für diese Plattform.
- Ein Projekt pro App und Plattform: Jedes Projekt legt beim Anlegen seine Plattform fest (Android, iOS, React Native, Flutter, Web, Backend oder Odoo), und Blipit lehnt Daten von jeder anderen Plattform mit einer klaren Fehlermeldung ab. Eine iOS-App und eine Android-App brauchen also zwei Projekte mit zwei Schlüsseln. Releases, Versionen, Absturzraten und Store-Builds sind je Plattform verschieden, und gemischt in einem Projekt stimmt keiner dieser Werte mehr. Ein Web-Projekt nimmt auch die Serverseite derselben Web-App an (den Next.js-Server oder Node), und ein React-Native- oder Flutter-Projekt auch seine eigenen nativen Android- und iOS-Absturzberichte.
Kommen Sie nicht weiter? Schreiben Sie an support@blipit.io. Schlüssel und die Projekt-ID jedes Projekts finden Sie unter API-Schlüssel in app.blipit.io.





