Installa Blipit

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.

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.

npm install @blipit/browser

VITE_BLIPIT_KEY=blipit_pk_your_public_key

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.

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

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

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.

createRoot(document.getElementById("root")!, {
  onCaughtError: (error) => Blipit.captureException(error),
  onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);

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

const app = createApp(App);
app.config.errorHandler = (err) => Blipit.captureException(err);
app.mount("#app");

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 }] };

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.

Blipit.init({
  key: import.meta.env.VITE_BLIPIT_KEY,
  feedbackWidget: {
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  },
});

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.

<nav id="help-menu"></nav>
<script>
  document.getElementById("help-menu").append(Blipit.reportButton());
</script>

import { BlipitReportButton } from "@blipit/nextjs/react";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton variant="outline" size="sm" />
    </header>
  );
}

<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>

<button id="report-issue">Report Issue</button>
<script>
  Blipit.attachReport(document.getElementById("report-issue"));
</script>

<button onclick="Blipit.openReport()">Report Issue</button>

import { openReport } from "@blipit/browser";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}

<script setup>
import { openReport } from "@blipit/browser";
</script>

<template>
  <button @click="openReport()">Report Issue</button>
</template>

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.

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.

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

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.

1Installazione

npm install @blipit/nextjs

2Ottieni 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_key

4Lato 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.*.local

9Content 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"

11Segnalazioni 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.

<Blipit
  publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!}
  feedbackWidget={{
    position: "bottom-left",
    style: "icon",
    text: "Report Issue",
    color: "#E11D48",
    shortcut: "ctrl+shift+b",
  }}
/>

12Aprire il modulo di segnalazione dal tuo pulsante

Metti il pulsante ufficiale ovunque con <BlipitReportButton />, anche nei server component: mostra l'icona di Blipit e Segnala un bug nella lingua del visitatore e apre il modulo. Preferisci un design tuo? Il componente che chiama openReport deve essere un client component, quindi metti "use client" all'inizio del suo file. <Blipit /> deve essere già in app/layout.tsx. Le app React senza Next.js importano il pulsante da @blipit/nextjs/react e openReport da @blipit/browser.

import { BlipitReportButton } from "@blipit/nextjs";

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton />
    </header>
  );
}

import { BlipitReportButton } from "@blipit/nextjs/react";

<BlipitReportButton variant="outline" size="sm" />

"use client";

import { openReport } from "@blipit/nextjs";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}

import { openReport } from "@blipit/browser";

export function ReportIssue() {
  return <button onClick={() => openReport()}>Report Issue</button>;
}

13Nascondere 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.

<Blipit publicKey={process.env.NEXT_PUBLIC_BLIPIT_KEY!} feedbackWidget={false} />

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

16Se 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.

1Installazione

npm install @blipit/node

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

3Tieni la chiave nell'ambiente

Node usa la chiave segreta. Mettila in una variabile d'ambiente, mai nel codice: in locale in un file .env che Node 20.6 e versioni successive caricano con --env-file, in produzione nelle impostazioni dell'ambiente o dei secret del tuo host (Fly secrets, Docker, systemd, Render, Vercel). Riavvia il processo dopo averla cambiata.

BLIPIT_SECRET_KEY=blipit_sk_your_secret_key

node --env-file=.env --import ./instrument.mjs server.mjs

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.

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

5Inizializza per primo

Mettilo in un file che viene eseguito prima della tua app, e importalo per primo.

import * as Blipit from "@blipit/node";

Blipit.init({
  key: process.env.BLIPIT_SECRET_KEY,
  environment: process.env.NODE_ENV,
  release: process.env.RELEASE,
  serverName: "api",
});

6Express, Fastify, Koa, Hono o NestJS

Aggiungi l'handler dopo le tue route così sia gli errori gestiti che quelli non gestiti raggiungono Blipit, con metodo, URL e user agent della richiesta. Koa, Hono e NestJS richiedono una riga ciascuno: il middleware di Koa va per primo, quello di Hono prima delle rotte. Segnalano gli errori con stato 500 o superiore. Le richieste compaiono poi nella pagina Pulse per rotta, come GET /users/:id, invece di una riga per URL.

import "./instrument.mjs";
import * as Blipit from "@blipit/node";
import express from "express";

const app = express();
app.get("/", (req, res) => res.send("ok"));
app.use(Blipit.expressErrorHandler());
app.listen(3000);

await app.register(Blipit.fastifyPlugin());

app.use(Blipit.koaMiddleware());

app.use(Blipit.honoMiddleware());

app.useGlobalInterceptors(Blipit.nestInterceptor());

7Serverless: AWS Lambda e Vercel

Gli host serverless sospendono la funzione appena risponde, e Lambda non avvia il server HTTP di Node, quindi avvolgi l'handler. wrapHandler registra la richiesta (eventi di API Gateway, URL di funzione e load balancer per metodo e rotta, gli altri eventi per nome della funzione), segnala gli errori e invia tutto prima che l'handler restituisca; attende solo quando c'è qualcosa da inviare, al massimo 2 secondi. traceRequest fa lo stesso per qualsiasi handler che riceve una Request. Su Vercel i dati partono dopo la risposta tramite waitUntil, quindi nulla viene rallentato. In Next.js usa withBlipit (vedi la guida Next.js).

import * as Blipit from "@blipit/node";

export const handler = Blipit.wrapHandler(async (event, context) => {
  return { statusCode: 200, body: "ok" };
});

export default { fetch: (request) => Blipit.traceRequest(request, () => app.fetch(request)) };

8Cattura manuale, log e tentativi di accesso

Blipit.captureException(err);
Blipit.captureMessage("cache miss rate above 50%", "warning");
Blipit.setUser({ id: "user-42" });
Blipit.log.info("order placed", { order_id: 42 });
Blipit.captureSecurity({ kind: "login_failed", actor: email, ip, userAgent, outcome: "bad_password" });
await Blipit.flush();

9Dipendenze e stato dei server

Dalla 0.2 l'SDK registra anche le chiamate al database e ai servizi esterni, e CPU, memoria ed event loop del tuo server. Vedi le guide Dipendenze e Stato dei server; si controlla con tracesSampleRate, tracing: false e metrics: false.

10Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

Blipit.captureMessage("Hello from Node");

1Installazione

pip install blipit

2Inizializza all'avvio

Per Django, mettilo in cima a settings.py. Per Flask o FastAPI, prima che l'app venga creata. La chiave è nella pagina Chiavi del progetto. Con una chiave vuota, init registra un avviso e restituisce False invece di sollevare un'eccezione, così una chiave mancante non impedisce mai all'app di avviarsi.

import blipit

blipit.init(
    key="<public key>",
    environment="production",
    release="myapp@1.4.2",
)

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

4Tieni la chiave nell'ambiente

Questo SDK invia con la chiave pubblica presa dalla pagina Chiavi API del progetto. Tienila in una variabile d'ambiente: in locale in un file .env caricato dal tuo framework o da python-dotenv, in produzione nelle impostazioni del tuo host. Usa la chiave segreta solo se invii i tentativi di accesso.

BLIPIT_KEY=blipit_pk_your_public_key

import os
import blipit

blipit.init(key=os.environ.get("BLIPIT_KEY"))

5Tieni 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.*.local

6Cattura manuale e tentativi di accesso

I tentativi di accesso richiedono la chiave segreta: sul server inizializza con la chiave segreta invece di quella pubblica, altrimenti l'ingestione li rifiuta con 403 security_needs_secret_key. Piano Scale.

blipit.capture_exception(err)
blipit.capture_message("cache miss rate above 50%", level="warning")
blipit.set_user({"id": "42", "email": "ana@example.com"})
blipit.set_context("order", {"id": 1042, "total": 99.5})
blipit.capture_security("login_failed", actor=email, ip=request.META.get("REMOTE_ADDR"), outcome="bad_password")

7Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

blipit.capture_message("Hello from Python")

1Installazione

composer require blipit/blipit

2Inizializza all'avvio

PHP semplice: in cima al tuo front controller, prima che venga gestita qualsiasi richiesta. Laravel avvia Blipit dalla sua configurazione, come nel passaggio successivo. La chiave è nella pagina Chiavi del progetto. Con una chiave vuota, init scrive un avviso nel log degli errori e restituisce false invece di lanciare un'eccezione.

use Blipit\Blipit;

Blipit::init([
    "key" => "<public key>",
    "environment" => "production",
    "release" => "myapp@1.4.2",
]);

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

4Tieni la chiave nell'ambiente

Questo SDK invia con la chiave pubblica. Laravel: aggiungila a .env e a config/services.php; il service provider di Blipit viene rilevato da solo e avvia Blipit da quella configurazione, quindi non serve altro. Leggi i valori tramite config, perché env() non restituisce nulla nel codice dell'app una volta che la configurazione è in cache. PHP semplice: leggi la chiave con getenv() dall'ambiente del server.

BLIPIT_KEY=blipit_pk_your_public_key

'blipit' => [
    'key' => env('BLIPIT_KEY'),
    'environment' => env('APP_ENV'),
    'release' => env('GIT_SHA'),
],

5Tieni 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.*.local

6Laravel e Symfony

Laravel: ogni eccezione segnalata dal suo handler arriva a Blipit, così i 404 e gli errori di validazione restano fuori. Query, righe di log e chiamate del client HTTP diventano breadcrumb, e i job in coda vengono tracciati. Una riga Blipit::captureException che hai già in bootstrap/app.php può restare: la stessa eccezione non viene mai inviata due volte. Symfony: registra il listener in config/services.yaml e chiama Blipit::init presto in public/index.php e bin/console.

Blipit\Symfony\BlipitListener:
    arguments: ['@router']
    tags:
        - { name: kernel.event_listener, event: kernel.exception, method: onKernelException }
        - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
        - { name: kernel.event_listener, event: kernel.terminate, method: onKernelTerminate }
        - { name: kernel.event_listener, event: console.error, method: onConsoleError }

7Cattura manuale e tentativi di accesso

I tentativi di accesso richiedono la chiave segreta: sul server inizializza con la chiave segreta invece di quella pubblica, altrimenti l'ingestione li rifiuta con 403 security_needs_secret_key. Piano Scale.

Blipit::captureException($e);
Blipit::captureMessage("cache miss rate above 50%", "warning");
Blipit::setUser(["id" => "42", "email" => "ana@example.com"]);
Blipit::captureSecurity("login_failed", $email, "bad_password", null, $request->ip(), $request->userAgent());

8Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

Blipit::captureMessage("Hello from PHP");

1Gemfile

gem "blipit"

2Inizializza all'avvio

Rails: config/initializers/blipit.rb; non serve installare altro, perché Blipit aggiunge da solo il suo middleware Rack e la segnalazione di Active Job e Rails.error. Le app Rack e Sinatra aggiungono use Blipit::Rack. Script: prima che il tuo codice venga eseguito. La chiave è nella pagina Chiavi del progetto. Con una chiave vuota, init stampa un avviso e restituisce false invece di sollevare un'eccezione.

Blipit.init(
  key: "<public key>",
  environment: Rails.env,
  release: ENV["RELEASE"],
)

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

4Tieni la chiave nelle credentials di Rails

Questo SDK invia con la chiave pubblica. In Rails, tienila nelle credentials cifrate e leggila nell'initializer; altrove, usa una variabile d'ambiente.

bin/rails credentials:edit

blipit:
  key: blipit_pk_your_public_key

Blipit.init(
  key: Rails.application.credentials.dig(:blipit, :key),
  environment: Rails.env,
)

5Tieni 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.*.local

6Cattura manuale e tentativi di accesso

I tentativi di accesso richiedono la chiave segreta: sul server inizializza con la chiave segreta invece di quella pubblica, altrimenti l'ingestione li rifiuta con 403 security_needs_secret_key. Piano Scale.

Blipit.capture_exception(e)
Blipit.capture_message("cache miss rate above 50%", level: :warning)
Blipit.set_user(id: "42", email: "ana@example.com")
Blipit.capture_security("login_failed", email, outcome: "bad_password", ip: request.remote_ip, user_agent: request.user_agent)

7Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

Blipit.capture_message("Hello from Rails")

1Installazione

go get github.com/blipit-io/blipit-go

2Inizializza in main

Init non va mai in panic: con una chiave o un id progetto vuoti restituisce un errore e Blipit resta spento, quindi registra l'errore invece di uscire.

import (
    "log"
    "time"

    "github.com/blipit-io/blipit-go"
)

func main() {
    if err := blipit.Init(blipit.Options{
        Key:         "<public key>",
        Project:     "<project id>",
        Environment: "production",
        Release:     "myapp@1.4.2",
    }); err != nil {
        log.Printf("blipit: %v", err)
    }
    defer blipit.Flush(2 * time.Second)
}

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

4Tieni la chiave nell'ambiente

Questo SDK invia con la chiave pubblica e l'id del progetto. Leggili da variabili d'ambiente impostate dal tuo host, da una unit systemd o da docker run -e.

blipit.Init(blipit.Options{
    Key:     os.Getenv("BLIPIT_KEY"),
    Project: os.Getenv("BLIPIT_PROJECT"),
})

5Tieni 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.*.local

6Cattura manuale e tentativi di accesso

I tentativi di accesso richiedono la chiave segreta: sul server inizializza con la chiave segreta invece di quella pubblica, altrimenti l'ingestione li rifiuta con 403 security_needs_secret_key. Piano Scale.

blipit.CaptureException(err)
blipit.CaptureMessage("cache miss rate above 50%")
blipit.SetUser(blipit.User{ID: "42", Email: "ana@example.com"})
blipit.CaptureSecurity(blipit.Security{Kind: "login_failed", Actor: email, IP: ip, UserAgent: agent, Outcome: "bad_password"})

7Panic e net/http

defer blipit.Recover() in cima a main o a qualsiasi goroutine segnala un panic con il suo stack, svuota la coda e rilancia il panic. Avvolgi l'handler che servi con blipit.Handler per segnalare i panic con la richiesta e misurare ogni richiesta su Pulse, chiamata secondo il suo pattern ServeMux. Gin, Echo e Fiber usano StartRequest, SetRoute ed End, mostrati nel README del pacchetto.

go func() {
    defer blipit.Recover()
    work()
}()

mux := http.NewServeMux()
mux.HandleFunc("GET /items/{id}", item)
http.ListenAndServe(":8080", blipit.Handler(mux))

8Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

blipit.CaptureMessage("Hello from Go")

1Aggiungi repository e dipendenza

repositories {
    mavenCentral()
    maven("https://jitpack.io")
}

dependencies {
    implementation("com.github.blipit-io:blipit-java:v0.2.1")
}

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.blipit-io</groupId>
  <artifactId>blipit-java</artifactId>
  <version>v0.2.1</version>
</dependency>

2Inizializza all'avvio

Spring Boot: in cima a main, prima di SpringApplication.run, o in un metodo @PostConstruct di una classe @Configuration. Le eccezioni non catturate su qualsiasi thread vengono scritte in una coda su disco prima che l'app si fermi, poi inviate, così un crash viene segnalato anche se la rete non c'è; ciò che resta parte all'avvio successivo.

import io.blipit.Blipit;
import io.blipit.BlipitOptions;

Blipit.init(BlipitOptions.builder()
    .key("<public key>")
    .project(<project id>)
    .environment("production")
    .release("myapp@1.4.2")
    .build());

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

4Tieni la chiave nell'ambiente

Questo SDK invia con la chiave pubblica e l'id del progetto. Leggili da variabili d'ambiente oppure, in Spring Boot, da application.properties popolato dall'ambiente.

blipit.key=${BLIPIT_KEY}
blipit.project=${BLIPIT_PROJECT}

Blipit.init(BlipitOptions.builder()
    .key(System.getenv("BLIPIT_KEY"))
    .project(Long.parseLong(System.getenv("BLIPIT_PROJECT")))
    .build());

5Tieni 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.*.local

6Cattura manuale e tentativi di accesso

I tentativi di accesso richiedono la chiave segreta: sul server inizializza con la chiave segreta invece di quella pubblica, altrimenti l'ingestione li rifiuta con 403 security_needs_secret_key. Piano Scale.

Blipit.captureException(err);
Blipit.captureMessage("cache miss rate above 50%");
Blipit.captureMessage("disk almost full", Level.WARNING);
Blipit.setUser("42", "ana@example.com");
Blipit.addBreadcrumb("GET /api/cart 500", "http", Level.ERROR);
Blipit.captureSecurity("login_failed", email, "bad_password", null, ip, userAgent, null);

7Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

Blipit.captureMessage("Hello from Java");

1Installazione

dotnet add package Blipit

2Inizializza all'avvio

Mantieni vivo l'handle restituito per tutta la durata del processo. Entrambi i valori sono nella pagina Chiavi del progetto.

using Blipit;

using var blipit = Blipit.Blipit.Init(new BlipitOptions
{
    Key = "<public key>",
    Project = "<project id>",
    Environment = "production",
    Release = "myapp@1.4.2",
});

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

4Tieni la chiave nella configurazione

Questo SDK invia con la chiave pubblica e l'id del progetto. Tienili negli user secrets durante lo sviluppo e in variabili d'ambiente in produzione (Blipit__Key e Blipit__Project), poi leggili dalla configurazione.

dotnet user-secrets set "Blipit:Key" "blipit_pk_your_public_key"
dotnet user-secrets set "Blipit:Project" "12"

using var blipit = Blipit.Blipit.Init(new BlipitOptions
{
    Key = builder.Configuration["Blipit:Key"],
    Project = builder.Configuration["Blipit:Project"],
});

5Tieni 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.*.local

6ASP.NET Core e logging

Non serve aggiungere altro: chiama Init in cima a Program.cs. Le eccezioni di endpoint, controller e middleware vengono segnalate con la richiesta, anche quando le gestisce UseExceptionHandler, e con TracesSampleRate impostato ogni richiesta campionata viene misurata su Pulse in base alla sua route. BlipitLoggerProvider trasforma Information e livelli superiori in breadcrumb ed Error e superiori in eventi.

var builder = WebApplication.CreateBuilder(args);
using var blipit = Blipit.Blipit.Init(new BlipitOptions
{
    Key = builder.Configuration["Blipit:Key"],
    Project = builder.Configuration["Blipit:Project"],
    TracesSampleRate = 0.2,
});
builder.Logging.AddProvider(new BlipitLoggerProvider());

7Cattura manuale e tentativi di accesso

I tentativi di accesso richiedono la chiave segreta: sul server inizializza con la chiave segreta invece di quella pubblica, altrimenti l'ingestione li rifiuta con 403 security_needs_secret_key. Piano Scale.

Blipit.Blipit.CaptureException(ex);
Blipit.Blipit.CaptureMessage("cache miss rate above 50%", BlipitLevel.Warning);
Blipit.Blipit.SetUser(id: "42", email: "ana@example.com");
Blipit.Blipit.CaptureSecurity("login_failed", email, "bad_password", null, ip, userAgent, null);

8Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

Blipit.Blipit.CaptureMessage("Hello from .NET");

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.

2React Native

Il pacchetto collega un piccolo modulo nativo che avvia gli SDK Android e iOS di Blipit per i crash nativi; il suo file Gradle aggiunge da solo il repository JitPack. Avvolgi il componente radice così vengono segnalati anche gli errori di rendering.

npm install @blipit/react-native
npx pod-install

import * as Blipit from "@blipit/react-native";

Blipit.init({ key: "<public key>", project: <project id>, environment: "production", release: "myapp@1.4.2" });

export default Blipit.wrap(App);

3Flutter

Sostituisci runApp in main.dart con Blipit.init. Il plugin avvia gli SDK Android e iOS di Blipit per i crash nativi, e gli errori del framework Flutter e gli errori async non catturati vengono segnalati da soli.

flutter pub add blipit_flutter

import 'package:blipit_flutter/blipit_flutter.dart';

Future<void> main() async {
  await Blipit.init(
    key: '<public key>',
    project: <project id>,
    environment: 'production',
    release: 'myapp@1.4.2',
    appRunner: () => runApp(const MyApp()),
  );
}

4iOS e macOS (Swift Package)

In Xcode, File, Add Package Dependencies, e inserisci l'URL del repository; oppure aggiungilo a Package.swift e aggiungi BlipitSwift al tuo target. Con CocoaPods, usa il pod BlipitSwift. Poi chiama start una volta all'avvio. Con una chiave o un id progetto vuoti, start stampa un avviso e restituisce false invece di far crashare l'app.

.package(url: "https://github.com/blipit-io/blipit-swift", from: "0.6.0")

pod "BlipitSwift", "~> 0.6.0"

import BlipitSwift

Blipit.start(key: "<public key>", project: "<project id>", environment: "production", release: "myapp@1.4.2")

5Android

Aggiungi JitPack ai repository in settings.gradle.kts, la dipendenza al modulo app, e chiama init in Application.onCreate.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

implementation("com.github.blipit-io:blipit-android:v0.6.0")

import io.blipit.android.Blipit

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Blipit.init(this) {
            key = "<public key>"
            project = "<project id>"
            environment = "production"
            release = "myapp@1.4.2"
        }
    }
}

6Dove va la chiave in un'app

Le app includono la chiave pubblica e l'id del progetto, e va bene così: la chiave pubblica può solo inviare eventi. Non mettere mai la chiave segreta in un'app. Passale in fase di build, così restano fuori dal tuo repository.

flutter run --dart-define=BLIPIT_KEY=blipit_pk_your_public_key --dart-define=BLIPIT_PROJECT=12

const key = String.fromEnvironment('BLIPIT_KEY');
const project = int.fromEnvironment('BLIPIT_PROJECT');

EXPO_PUBLIC_BLIPIT_KEY=blipit_pk_your_public_key
EXPO_PUBLIC_BLIPIT_PROJECT=12

buildConfigField("String", "BLIPIT_KEY", ""${project.findProperty("blipitKey")}"")

BLIPIT_KEY = blipit_pk_your_public_key

7Segnalazioni di bug nelle app

Chiama showReport da una voce di menu della tua app, oppure attiva il pulsante fluttuante Segnala un bug. Lo strumento chiede prima come mostrare il problema: fare uno screenshot, registrare lo schermo (iOS) o solo descriverlo. Lo screenshot si apre a schermo intero con gli strumenti sopra e sotto, mai sopra l'immagine; pizzica o tocca due volte per lo zoom, segna il problema, aggiungi un titolo e cosa è successo e invia. Le segnalazioni arrivano in Segnalazioni di bug con i dati del dispositivo. React Native richiede react-native-view-shot per gli screenshot.

import * as Blipit from "@blipit/react-native";

export default function Root() {
  return (
    <Blipit.BlipitReporter showButton>
      <App />
    </Blipit.BlipitReporter>
  );
}

Blipit.showReport();

appRunner: () => runApp(const BlipitReporter(showButton: true, child: MyApp())),

Blipit.showReport();

Blipit.showReportButton()

Blipit.showReport()

Blipit.showReportButton()

Blipit.showReport()

8Segnala dalla schermata con il bug

Una voce Segnala un bug in un menu come Profilo cattura il menu, non il problema. Attivi i modi che partono dalla schermata stessa; sono tutti disattivati di default e non chiedono alcun permesso. shakeToReport apre il modulo quando si scuote il telefono. screenshotToReport chiede "Segnalare un bug con questa schermata?" dopo un normale screenshot e allega la cattura di Blipit (iOS e Android 14 o successivo). twoFingerReport lo apre dopo una pressione prolungata di circa un secondo con due dita, senza bloccare i tocchi dell’app. reportAfterCrash chiede cosa stava facendo la persona al primo avvio dopo un crash e collega la segnalazione a quel crash. screenPicker, attivo di default, permette a chi apre il modulo da un menu di scegliere in quale delle ultime schermate si trova il bug: le istantanee restano nella memoria del dispositivo e viene caricata solo quella scelta. Le app Jetpack Compose e SwiftUI danno un nome alle schermate con setScreen.

Blipit.init(this) {
    key = "<public key>"
    project = "<project id>"
    shakeToReport = true
    screenshotToReport = true
    twoFingerReport = true
    reportAfterCrash = true
}

navController.addOnDestinationChangedListener { _, destination, _ ->
    Blipit.setScreen(destination.route ?: "screen")
}

Blipit.start(key: "<public key>", project: "<project id>") { options in
    options.shakeToReport = true
    options.screenshotToReport = true
    options.twoFingerReport = true
    options.reportAfterCrash = true
}

CartView().onAppear { Blipit.setScreen("Cart") }

Blipit.init({
  key: "<public key>",
  project: <project id>,
  shakeToReport: true,
  screenshotToReport: true,
  twoFingerReport: true,
  reportAfterCrash: true,
});

<NavigationContainer ref={navigation} onReady={() => Blipit.trackNavigation(navigation)}>

await Blipit.init(
  key: '<public key>',
  project: <project id>,
  shakeToReport: true,
  screenshotToReport: true,
  twoFingerReport: true,
  reportAfterCrash: true,
  appRunner: () => runApp(BlipitReporter(child: MaterialApp(navigatorObservers: [BlipitNavigatorObserver()], home: const Home()))),
);

9Pulsante mobile solo per i tester

In app.blipit.io apra il progetto e, nelle impostazioni del pulsante di segnalazione, imposti Pulsante mobile nelle app per telefono su Tutti o Solo tester, con un ID utente o un’email per tester. L’app invia la persona impostata con setUser e Blipit risponde solo sì o no, quindi l’elenco dei tester non viene mai incluso nell’app. Chiamare showReportButton (showButton su React Native e Flutter) mostra ancora il pulsante a tutti.

Blipit.setUser(id = user.id, email = user.email)

Blipit.setUser(id: user.id, email: user.email)

Blipit.setUser({ id: user.id, email: user.email });

Blipit.setUser(BlipitUser(id: user.id, email: user.email));

10Accorgersi di un'app che si blocca

Alcuni guasti non causano mai un crash: la schermata iniziale continua a girare o l'accesso non torna mai. Attiva waitForReady e chiama reportReady appena compare la prima schermata utilizzabile. Racchiudi flussi come l'accesso tra startFlow ed endFlow e segna i passi con flowStep. Se uno non termina in tempo, Blipit apre un problema Bloccata con l'ultimo passo e il percorso precedente. Conta solo il tempo sullo schermo, e i limiti di tempo li stabilisce Blipit. I nomi vengono inviati così come sono scritti: usa nomi fissi, mai email o altri dati dell'utente.

Blipit.init(this) {
    key = "<public key>"
    project = "<project id>"
    waitForReady = true
}

Blipit.reportReady()

Blipit.startFlow("sign-in")
Blipit.flowStep("sign-in", "google-picker")
Blipit.endFlow("sign-in")

Blipit.start(key: "<public key>", project: "<project id>", waitForReady: true)

Blipit.reportReady()

Blipit.startFlow("sign-in")
Blipit.flowStep("sign-in", "apple-sheet")
Blipit.endFlow("sign-in")

Blipit.init({ key: "<public key>", project: <project id>, waitForReady: true });

Blipit.reportReady();

Blipit.startFlow("sign-in");
Blipit.flowStep("sign-in", "google-picker");
Blipit.endFlow("sign-in");

await Blipit.init(key: '<public key>', project: <project id>, waitForReady: true, appRunner: () => runApp(const MyApp()));

Blipit.reportReady();

Blipit.startFlow('sign-in');
Blipit.flowStep('sign-in', 'google-picker');
Blipit.endFlow('sign-in');

11Verifica che funzioni

Apri Issue in app.blipit.io. Il primo evento compare entro pochi secondi, raggruppato in una issue, e i responsabili ricevono un'email.

1Installa il modulo

Scaricalo da apps.odoo.com (blipit_monitor, gratuito) per la tua versione di Odoo e installalo come qualsiasi modulo: App, Aggiorna elenco app, installa Blipit Error Monitoring. Odoo Online non consente app di terze parti; Odoo.sh e on-premise sì.

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

3Collega

Impostazioni, Blipit: incolla la chiave segreta del progetto, spunta l'accettazione dei Termini e della licenza del modulo, e premi Salva. Si collega da solo e mostra Connesso a <project>. Una chiave pubblica o una chiave già legata a un altro database viene rifiutata con il motivo.

4Responsabili

Scegli chi riceve le email, per azienda se ne hai più di una. Ogni persona occupa una postazione del tuo piano; Blipit controlla il conteggio quando salvi.

5Segnalazioni di bug da Odoo

Il modulo aggiunge il pulsante Segnala un bug a Odoo al posto tuo; non serve scrivere codice. In Impostazioni, Blipit, Segnalazioni di bug, Visibile a, scegli chi lo vede: Utenti interni, Visitatori del sito web, Entrambi o Nessuno, e facoltativamente limita gli utenti interni a un gruppo. Le segnalazioni includono il modello, il record e il campo su cui si trovava la persona, e nome ed email dell'utente connesso vengono compilati. Posizione, colore, testo e stile arrivano da app.blipit.io, Impostazioni del progetto, Widget di segnalazione bug. Consulta la guida al pulsante di segnalazione bug per tutte le opzioni.

6Verifica che funzioni

Apri l'app Blipit in Odoo. Il prossimo errore compare lì e nella casella dei responsabili. Clicca Aggiorna da Blipit per controllare subito.