Qualsiasi sito web

Installazione npm install @blipit/browser

L'SDK Blipit per browser pesa 10 KB. Cattura errori non catturati, promise rejection non gestite e richieste fallite, conserva i clic e le richieste che hanno portato a ogni errore, registra i web vitals, mette un pulsante Segnala un bug in ogni pagina e può registrare un session replay quando si verifica un errore. Installalo da npm in un'app con bundler, oppure inserisci un tag script in qualsiasi pagina.

Incollalo in Claude Code, Cursor o in qualsiasi assistente di programmazione IA. Contiene i passaggi e il codice. In app.blipit.io, in Chiavi API, lo stesso prompt ha già la tua chiave inserita.
Video: installare Blipit in qualsiasi stack, da 0:32

1Ottieni 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.

Chiavi API su app.blipit.io: la chiave pubblica (blipit_pk_) per il codice del browser e la chiave segreta (blipit_sk_) per i server e Odoo.
Chiavi API su app.blipit.io: la chiave pubblica (blipit_pk_) per il codice del browser e la chiave segreta (blipit_sk_) per i server e Odoo.
Una nuova chiave segreta viene mostrata una sola volta. Copiala subito: viene salvata come hash e non può essere mostrata di nuovo.
Una nuova chiave segreta viene mostrata una sola volta. Copiala subito: viene salvata come hash e non può essere mostrata di nuovo.

2Con npm

Chiama init una sola volta nel file di ingresso, prima che l'app venga renderizzata, con la chiave pubblica. Con Vite (React, Vue, Svelte), tieni la chiave in .env come VITE_BLIPIT_KEY; solo le variabili VITE_ arrivano al browser, e il dev server legge .env solo all'avvio.

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 },
});

3Senza bundler: un solo tag script

Incolla questo nel <head> di ogni pagina, o nello spazio per il codice personalizzato della tua piattaforma, con la tua chiave pubblica già inserita. Va bene così: la chiave pubblica può solo inviare eventi.

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>

4Tieni 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.

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

5Di' a Blipit chi è l'utente (facoltativo)

Dopo l'accesso, allega l'utente così le issue mostrano chi è stato colpito e i replay possono essere trovati per utente.

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

6React, Vue, Angular e Svelte: segnalare gli errori catturati

I framework catturano gli errori dentro i componenti prima che li veda il browser, quindi passa anche quelli a Blipit. Gli errori non catturati in qualsiasi altro punto vengono segnalati da soli.

React 19 (src/main.tsx)
createRoot(document.getElementById("root")!, {
  onCaughtError: (error) => Blipit.captureException(error),
  onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);
Oppure, React 18 e precedenti: un 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);
};

7Segnalazioni di bug: il pulsante Segnala un bug

Appena l'SDK si avvia con la tua chiave pubblica, compare un pulsante Segnala un bug nell'angolo in basso a destra di ogni pagina, nella lingua del visitatore. Un clic apre il modulo di segnalazione: uno screenshot della pagina da annotare, un selettore di elementi, una registrazione dello schermo facoltativa, un titolo e una descrizione. Cambia posizione, stile, testo, colore e scorciatoia da tastiera nel codice, come qui sotto, oppure per tutti i siti insieme su app.blipit.io, Impostazioni del progetto, Widget di segnalazione bug; le opzioni nel codice hanno la precedenza. La guida al pulsante di segnalazione bug mostra ogni opzione con screenshot e una demo dal 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",
  },
});
Il pulsante predefinito Segnala un bug, in basso a destra.
Il pulsante predefinito Segnala un bug, in basso a destra.
Il modulo di segnalazione: uno screenshot annotato, il titolo e cosa è successo.
Il modulo di segnalazione: uno screenshot annotato, il titolo e cosa è successo.

8Aprire il modulo di segnalazione dal tuo pulsante

Per mettere un pulsante Segnala un bug nella tua intestazione o nel tuo menu, usa quello ufficiale: Blipit.reportButton() restituisce un pulsante pronto con l'icona di Blipit e Segnala un bug nella lingua del visitatore, e le app React possono mostrare <BlipitReportButton /> da @blipit/nextjs/react (npm install @blipit/nextjs). Preferisci un design tuo? Chiama openReport() da qualsiasi gestore di clic, oppure attachReport(element) per collegare un elemento che esiste già. In entrambi i casi il modulo si apre esattamente come dal pulsante flottante. L'icona di Blipit può essere usata solo accanto a Segnala un bug, come mostra il pulsante ufficiale.

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

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton variant="outline" size="sm" />
    </header>
  );
}
Pulsante ufficiale, 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 semplice
<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>
Il pulsante ufficiale Segnala un bug nell'intestazione di un sito.
Il pulsante ufficiale Segnala un bug nell'intestazione di un sito.
Un pulsante personalizzato Report Issue nell'header della pagina apre il modulo di segnalazione Blipit.
Un pulsante personalizzato Report Issue nell'header della pagina apre il modulo di segnalazione Blipit.

9Nascondere il pulsante predefinito

Per tenere solo il tuo pulsante, disattiva quello flottante con feedbackWidget: false nel codice (feedbackWidget={false} su <Blipit />), oppure disattiva Mostra il pulsante di segnalazione nelle impostazioni del Widget di segnalazione bug del progetto per nasconderlo su ogni sito che usa la chiave. openReport() e attachReport() continuano a funzionare in entrambi i casi.

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

10Precompilare 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.

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

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

11Tutte le opzioni e le funzioni

  • key: la chiave pubblica (blipit_pk_). Obbligatoria.
  • environment e release: mostrati su ogni evento; release abilita regressioni e source map. environment è production per impostazione predefinita.
  • debug: true scrive nella console cosa fa l'SDK, con righe che iniziano con [blipit].
  • sampleRate (da 0 a 1), ignoreErrors (stringhe o pattern) e beforeSend (modifica un evento, o restituisci null per scartarlo) controllano cosa viene inviato. autoMuteExtensions (attivo di default) scarta gli errori che provengono solo da estensioni del browser.
  • webVitals (attivo di default), replay ({ sessionSampleRate, onErrorSampleRate }) e autoSessionTracking (tassi crash-free, richiede release).
  • feedbackWidget: false nasconde il pulsante Segnala un bug, mentre un oggetto con position, style, text, color, font, match e shortcut lo modifica. theme: "light", "dark" o "auto" imposta il tema del modulo di segnalazione.
  • user ({ id, name, email }) e company (un nome o { id, name }) compilano il modulo di segnalazione e vengono aggiunti alle segnalazioni.
  • endpoint: solo per un ingest self-hosted; il valore predefinito è https://in.blipit.io/api/v1/events.
  • Funzioni: captureException(error), captureMessage(text, level), setUser, setTag(key, value), addBreadcrumb({ category, message }), openReport(), attachReport(element), reportButton(options), updateWidget(options), setReportMetadata(fn), showFeedback() e flush(), che restituisce una promise quando gli eventi in coda sono stati inviati.
  • Le impostazioni del widget cambiate nella dashboard raggiungono i browser entro un'ora, perché l'SDK le conserva per quel tempo; una finestra privata mostra subito la modifica.

12Verifica che funzioni

Ricarica il sito. 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 invia un evento di prova: chiama captureMessage una volta dal tuo codice, oppure, con il tag script, esegui la riga qui sotto nella console del browser. Compare in Issue entro pochi secondi.

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

13Se il pulsante o gli eventi non compaiono

  • Apri la console del browser e cerca le righe che iniziano con [blipit]. Attiva debug (debug: true in init, oppure debug su <Blipit />) per vedere se il pulsante è stato mostrato, disattivato nel codice o nascosto dall'impostazione del progetto.
  • Next.js invia al browser solo le variabili il cui nome inizia con NEXT_PUBLIC_, quindi usa NEXT_PUBLIC_BLIPIT_KEY. Vite invia solo le variabili VITE_, quindi usa VITE_BLIPIT_KEY. Con qualsiasi altro nome la chiave è vuota nel browser e Blipit non si avvia.
  • Riavvia il dev server dopo aver aggiunto o modificato .env o .env.local. Li legge solo all'avvio.
  • Su Vercel o qualsiasi altro host, aggiungi la stessa variabile nelle variabili d'ambiente del progetto e fai di nuovo il deploy. I valori NEXT_PUBLIC_ e VITE_ vengono scritti nella build, quindi un deploy già in esecuzione non vede mai un valore aggiunto dopo.
  • Usa la chiave pubblica (blipit_pk_). Una chiave segreta (blipit_sk_) viene rifiutata nel browser con un errore in console; se una è mai finita in una pagina, crea una nuova chiave segreta.
  • In Next.js, <Blipit /> va nel file principale app/layout.tsx (o pages/_app.tsx), così viene eseguito in ogni pagina. Nelle altre app, chiama init una sola volta nel file di ingresso, prima che l'app venga renderizzata.
  • Mostra il pulsante di segnalazione deve essere attivo su app.blipit.io, Impostazioni del progetto, Widget di segnalazione bug, e il tuo codice non deve passare feedbackWidget: false. L'SDK conserva le impostazioni del progetto fino a un'ora, quindi prova una modifica in una finestra privata.
  • Gli ad blocker e le estensioni per la privacy possono bloccare in.blipit.io. Prova una finestra privata con le estensioni disattivate.
  • Se il tuo sito invia una Content Security Policy, consenti script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: e media-src blob:. L'editor della segnalazione si carica da blipit.io/sdk al primo clic, lo screenshot viene disegnato da un'immagine data: e anche le registrazioni dello schermo vengono caricate su in.blipit.io. Con debug attivo, la console indica quando la policy ha bloccato lo screenshot. 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.
  • Controlla quale versione è installata con npm ls @blipit/browser @blipit/nextjs (o pnpm list @blipit/browser @blipit/nextjs) e confrontala con il changelog. pnpm 11 aspetta un giorno prima di installare una nuova versione (minimum-release-age), quindi il giorno del rilascio pnpm add installa in silenzio la versione precedente. Per avere subito quella nuova: pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Ancora bloccato? Scrivi a support@blipit.io allegando le righe [blipit] della console.

Buono a sapersi

  • Opzioni: sampleRate (da 0 a 1), ignoreErrors (stringhe o pattern), beforeSend per scartare o modificare un evento, maxBreadcrumbs, webVitals (attivo per impostazione predefinita), autoSessionTracking per i tassi crash-free (richiede release).
  • blipit.io/sdk/blipit.js serve sempre l'ultima versione (0.3.23). Le versioni fisse si trovano in blipit.io/sdk/0.3.23/blipit.js se vuoi controllare gli aggiornamenti.
  • 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.
  • 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.