Tout site web

Installation npm install @blipit/browser

Le SDK navigateur Blipit pèse 10 Ko. Il capture les erreurs non interceptées, les rejets de promesses non gérés et les requêtes en échec, conserve les clics et les requêtes qui ont mené à chaque erreur, enregistre les web vitals, place un bouton Signaler un bug sur chaque page et peut enregistrer un session replay lorsqu'une erreur survient. Installez-le depuis npm dans une application packagée, ou ajoutez une seule balise script à n'importe quelle page.

Collez-le dans Claude Code, Cursor ou tout autre assistant de code IA. Il contient les étapes et le code. Dans app.blipit.io, sous Clés API, le même prompt est fourni avec votre clé déjà renseignée.
Vidéo : installer Blipit dans n'importe quel stack, à partir de 0:32

1Obtenir vos clés

Connectez-vous sur app.blipit.io et ouvrez Clés API dans la barre latérale, puis votre projet. Chaque projet a deux clés. La clé publique commence par blipit_pk_ : elle va dans le code navigateur et applicatif, ne peut qu'envoyer des événements et peut être vue par n'importe qui sans risque. La clé secrète commence par blipit_sk_ : elle reste sur votre serveur ou dans Odoo, jamais dans un navigateur, car elle peut aussi lire et modifier les problèmes. La clé secrète n'est affichée qu'une fois, juste après sa création, alors copiez-la à ce moment-là ; si vous la perdez, appuyez sur Créer une nouvelle clé secrète, et l'ancienne cesse aussitôt de fonctionner. Certains SDK ont aussi besoin de l'identifiant de projet, affiché sur la même page.

Clés API dans app.blipit.io : la clé publique (blipit_pk_) pour le code navigateur et la clé secrète (blipit_sk_) pour les serveurs et Odoo.
Clés API dans app.blipit.io : la clé publique (blipit_pk_) pour le code navigateur et la clé secrète (blipit_sk_) pour les serveurs et Odoo.
Une nouvelle clé secrète n'est affichée qu'une fois. Copiez-la maintenant : elle est stockée sous forme de hash et ne peut plus être affichée.
Une nouvelle clé secrète n'est affichée qu'une fois. Copiez-la maintenant : elle est stockée sous forme de hash et ne peut plus être affichée.

2Avec npm

Appelez init une seule fois dans votre fichier d'entrée, avant le rendu de l'application, avec la clé publique. Avec Vite (React, Vue, Svelte), gardez la clé dans .env sous le nom VITE_BLIPIT_KEY ; seules les variables VITE_ atteignent le navigateur, et le serveur de développement ne lit .env qu'au démarrage.

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

3Sans bundler : une balise script

Collez ceci dans le <head> de chaque page, ou dans l'emplacement de code personnalisé de votre plateforme, avec votre clé publique écrite en clair. Ce n'est pas un problème : la clé publique ne peut qu'envoyer des événements.

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>

4Gardez les clés hors de git

Gardez les clés dans des variables d'environnement ou dans les réglages de secrets de votre hébergeur, jamais dans du code que vous committez, et ajoutez vos fichiers .env à .gitignore. Une clé publique dans une page web est normale. Si une clé secrète se retrouve un jour dans git, sur une page publique, dans une capture d'écran ou dans un chat, ouvrez Clés API, appuyez sur Créer une nouvelle clé secrète, et collez la nouvelle clé partout où l'ancienne était utilisée : l'ancienne clé cesse immédiatement de fonctionner.

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

5Indiquer à Blipit qui est l'utilisateur (facultatif)

Après la connexion, attachez l'utilisateur pour que les problèmes indiquent qui a été touché et que les replays puissent être retrouvés par utilisateur.

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

6React, Vue, Angular et Svelte : signaler les erreurs interceptées

Les frameworks interceptent les erreurs dans les composants avant que le navigateur ne les voie, donc transmettez-les aussi à Blipit. Les erreurs non interceptées partout ailleurs sont signalées d'elles-mêmes.

React 19 (src/main.tsx)
createRoot(document.getElementById("root")!, {
  onCaughtError: (error) => Blipit.captureException(error),
  onUncaughtError: (error) => Blipit.captureException(error),
}).render(<App />);
Ou, React 18 et antérieur : une 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);
};

7Rapports de bugs : le bouton Signaler un bug

Dès que le SDK démarre avec votre clé publique, un bouton Signaler un bug apparaît dans le coin inférieur droit de chaque page, dans la langue du visiteur. Un clic ouvre le formulaire de signalement : une capture de la page à annoter, un sélecteur d'élément, un enregistrement d'écran facultatif, ainsi qu'un titre et une description. Modifiez la position, le style, le texte, la couleur et le raccourci clavier dans le code, comme ci-dessous, ou pour tous vos sites à la fois dans app.blipit.io, Paramètres du projet, Widget de rapport de bug ; les options du code l'emportent. Le guide du bouton de rapport de bug présente chaque option avec des captures d'écran et une démo en direct.

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",
  },
});
Le bouton Signaler un bug par défaut, en bas à droite.
Le bouton Signaler un bug par défaut, en bas à droite.
Le formulaire : une capture d'écran annotée, le titre et ce qui s'est passé.
Le formulaire : une capture d'écran annotée, le titre et ce qui s'est passé.

8Ouvrir le formulaire depuis votre propre bouton

Pour placer un bouton Signaler un bug dans votre propre en-tête ou menu, utilisez le bouton officiel : Blipit.reportButton() renvoie un bouton prêt à l'emploi avec l'icône Blipit et Signaler un bug dans la langue du visiteur, et les apps React peuvent afficher <BlipitReportButton /> depuis @blipit/nextjs/react (npm install @blipit/nextjs). Vous préférez votre propre design ? Appelez openReport() depuis n'importe quel gestionnaire de clic, ou attachReport(element) pour brancher un élément qui existe déjà. Dans les deux cas, le formulaire s'ouvre exactement comme depuis le bouton flottant. L'icône Blipit ne peut être utilisée qu'à côté de Signaler un bug, comme le montre le bouton officiel.

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

export function Header() {
  return (
    <header>
      <a href="/">Acme</a>
      <BlipitReportButton variant="outline" size="sm" />
    </header>
  );
}
Bouton officiel, 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 simple
<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>
Le bouton officiel Signaler un bug dans l'en-tête d'un site.
Le bouton officiel Signaler un bug dans l'en-tête d'un site.
Un bouton Report Issue personnalisé dans l'en-tête de la page ouvre le formulaire Blipit.
Un bouton Report Issue personnalisé dans l'en-tête de la page ouvre le formulaire Blipit.

9Masquer le bouton par défaut

Pour ne garder que votre propre bouton, désactivez le bouton flottant avec feedbackWidget: false dans le code (feedbackWidget={false} sur <Blipit />), ou désactivez Afficher le bouton de rapport de bug dans les réglages Widget de rapport de bug du projet pour le masquer sur tous les sites qui utilisent la clé. openReport() et attachReport() continuent de fonctionner dans les deux cas.

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

10Pré-remplir le formulaire et ajouter du contexte

Appelez setUser après la connexion : le nom et l'e-mail de la personne qui signale sont pré-remplis, et elle reçoit un e-mail quand vous répondez ou changez le statut. setReportMetadata ajoute vos propres champs, comme le forfait ou la taille du panier, à chaque signalement ; il s'exécute à l'envoi du signalement, donc les valeurs sont à jour.

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

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

11Toutes les options et fonctions

  • key : la clé publique (blipit_pk_). Obligatoire.
  • environment et release : affichés sur chaque événement ; release alimente les régressions et les source maps. environment vaut production par défaut.
  • debug: true affiche dans la console ce que fait le SDK, avec des lignes qui commencent par [blipit].
  • sampleRate (de 0 à 1), ignoreErrors (chaînes ou motifs) et beforeSend (modifie un événement, ou renvoie null pour l'ignorer) contrôlent ce qui est envoyé. autoMuteExtensions (activé par défaut) ignore les erreurs qui proviennent uniquement d'extensions de navigateur.
  • webVitals (activé par défaut), replay ({ sessionSampleRate, onErrorSampleRate }) et autoSessionTracking (taux sans crash, nécessite release).
  • feedbackWidget: false masque le bouton Signaler un bug, ou un objet avec position, style, text, color, font, match et shortcut le modifie. theme: "light", "dark" ou "auto" définit le thème du formulaire.
  • user ({ id, name, email }) et company (un nom ou { id, name }) pré-remplissent le formulaire et sont ajoutés aux signalements.
  • endpoint : uniquement pour un ingest auto-hébergé ; la valeur par défaut est https://in.blipit.io/api/v1/events.
  • Fonctions : captureException(error), captureMessage(text, level), setUser, setTag(key, value), addBreadcrumb({ category, message }), openReport(), attachReport(element), reportButton(options), updateWidget(options), setReportMetadata(fn), showFeedback() et flush(), qui renvoie une promesse une fois les événements en file d'attente envoyés.
  • Les réglages du widget modifiés dans le tableau de bord atteignent les navigateurs en moins d'une heure, car le SDK les conserve aussi longtemps ; une fenêtre privée affiche la modification immédiatement.

12Vérifier que ça fonctionne

Rechargez votre site. Le bouton Signaler un bug apparaît dans le coin inférieur droit, et en moins d'une minute la page vue s'affiche sous Web vitals dans app.blipit.io. Envoyez ensuite un événement de test : appelez captureMessage une fois depuis votre code, ou, avec la balise script, exécutez la ligne ci-dessous dans la console du navigateur. Il apparaît sous Problèmes en quelques secondes.

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

13Si le bouton ou les événements n'apparaissent pas

  • Ouvrez la console du navigateur et cherchez les lignes qui commencent par [blipit]. Activez debug (debug: true dans init, ou debug sur <Blipit />) pour savoir si le bouton a été affiché, désactivé dans le code ou masqué par le réglage du projet.
  • Next.js n'envoie au navigateur que les variables dont le nom commence par NEXT_PUBLIC_, donc utilisez NEXT_PUBLIC_BLIPIT_KEY. Vite n'envoie que les variables VITE_, donc utilisez VITE_BLIPIT_KEY. Avec tout autre nom, la clé est vide dans le navigateur et Blipit ne démarre pas.
  • Redémarrez le serveur de développement après avoir ajouté ou modifié .env ou .env.local. Il ne les lit qu'au démarrage.
  • Sur Vercel ou tout autre hébergeur, ajoutez la même variable dans les variables d'environnement du projet et redéployez. Les valeurs NEXT_PUBLIC_ et VITE_ sont écrites dans le build, donc un déploiement en cours ne voit jamais une valeur ajoutée plus tard.
  • Utilisez la clé publique (blipit_pk_). Une clé secrète (blipit_sk_) est refusée dans le navigateur avec une erreur dans la console ; si l'une d'elles s'est déjà retrouvée sur une page, créez une nouvelle clé secrète.
  • Dans Next.js, <Blipit /> se place dans le app/layout.tsx racine (ou pages/_app.tsx) pour s'exécuter sur chaque page. Dans les autres applications, appelez init une seule fois dans le fichier d'entrée, avant le rendu de l'application.
  • Afficher le bouton de rapport de bug doit être activé dans app.blipit.io, Paramètres du projet, Widget de rapport de bug, et votre code ne doit pas passer feedbackWidget: false. Le SDK conserve les paramètres du projet jusqu'à une heure, donc testez une modification dans une fenêtre privée.
  • Les bloqueurs de publicité et les extensions de confidentialité peuvent bloquer in.blipit.io. Essayez une fenêtre privée avec les extensions désactivées.
  • Si votre site envoie une Content Security Policy, autorisez script-src https://blipit.io, connect-src https://in.blipit.io, img-src data: et media-src blob:. L'éditeur du signalement se charge depuis blipit.io/sdk au premier clic, la capture est dessinée à partir d'une image data: et les enregistrements d'écran sont eux aussi envoyés à in.blipit.io. Avec debug, la console indique quand la politique a bloqué la capture. Pour que les enregistrements d'écran aient du son, l'en-tête Permissions-Policy de votre site doit autoriser microphone=(self), et display-capture=(self) pour l'enregistrement d'écran ; avec microphone=() les enregistrements fonctionnent sans son.
  • Vérifiez la version installée avec npm ls @blipit/browser @blipit/nextjs (ou pnpm list @blipit/browser @blipit/nextjs) et comparez-la au journal des modifications. pnpm 11 attend un jour avant d'installer une nouvelle version (minimum-release-age) : le jour de la sortie, pnpm add installe donc sans prévenir la version précédente. Pour obtenir la nouvelle tout de suite : pnpm add @blipit/browser@<version> @blipit/nextjs@<version> --config.minimum-release-age=0.
  • Toujours bloqué ? Écrivez à support@blipit.io en joignant les lignes [blipit] de la console.

Bon à savoir

  • Options : sampleRate (0 à 1), ignoreErrors (chaînes ou motifs), beforeSend pour écarter ou modifier un événement, maxBreadcrumbs, webVitals (activé par défaut), autoSessionTracking pour les taux sans crash (nécessite release).
  • blipit.io/sdk/blipit.js sert toujours la dernière version (0.3.23). Les versions figées se trouvent à blipit.io/sdk/0.3.23/blipit.js si vous voulez maîtriser les mises à jour.
  • Si votre site envoie une Content Security Policy, autorisez script-src https://blipit.io (la balise script, ainsi que l'éditeur du signalement et le module de replay, chargés depuis blipit.io/sdk/<version>/ à la première utilisation), connect-src https://in.blipit.io (les événements, les captures et les enregistrements d'écran partent tous vers in.blipit.io), img-src data: (la capture est dessinée à partir d'une image de la page) et media-src blob: (les enregistrements sont lus dans le signalement). La capture recharge les images et les polices de la page : leurs hôtes doivent donc aussi figurer dans connect-src, sinon elles restent vides. Aucun changement de style-src n'est nécessaire. Avec la balise script, appelez Blipit.init depuis votre propre fichier .js ou donnez un nonce au script en ligne, car une politique stricte bloque les scripts en ligne. Pour que les enregistrements d'écran aient du son, l'en-tête Permissions-Policy de votre site doit autoriser microphone=(self), et display-capture=(self) pour l'enregistrement d'écran ; avec microphone=() les enregistrements fonctionnent sans son.
  • Garder Blipit à jour : le guide Garder Blipit à jour (docs.blipit.io/updates) explique la bannière de mise à jour, les e-mails pour les versions importantes, l'avis dans votre console de développement et la commande de mise à jour pour cette plateforme.
  • Un projet par application et par plateforme : chaque projet choisit sa plateforme à sa création (Android, iOS, React Native, Flutter, Web, Backend ou Odoo), et Blipit refuse avec une erreur claire les données de toute autre plateforme. Une app iOS et une app Android ont donc besoin de deux projets avec deux clés. Les releases, les versions, les taux de plantage et les builds des stores diffèrent selon la plateforme, et les mélanger dans un projet les rend tous faux. Un projet Web accepte aussi la partie serveur de la même app web (le serveur Next.js ou Node), et un projet React Native ou Flutter accepte aussi ses propres rapports de plantage natifs Android et iOS.

Bloqué ? Écrivez à support@blipit.io. Les clés et l'identifiant de chaque projet sont sous Clés API dans app.blipit.io.