SDK Web (Browser)

Le SDK Pionne pour navigateur. Auto-capture les erreurs JS, les promises non gérées, et enrichit chaque event avec le contexte du browser (URL, viewport, locale, User-Agent).

Version actuelle : 0.3.6

Installation

npm install @pionne/web

Ou via CDN dans une balise <script> :

<script src="https://unpkg.com/@pionne/web@0.1.0/dist/pionne.umd.js"></script>

Quickstart

Initialise le SDK le plus tôt possible — idéalement avant le rendu de ton app, dans main.ts ou un <script> en haut du <head>.

import { Pionne } from '@pionne/web';

Pionne.init({
  token: 'pio_live_…',
  release: '1.0.0',
  environment: 'production',
  sampleRate: 1.0,
  scrubPii: true,
});

API

Pionne.init(options);
Pionne.captureException(error, { tags, contexts });
Pionne.captureMessage('Quelque chose va mal', { level: 'warning' });
Pionne.setUser({ id: 'user_42' });
Pionne.setTags({ feature: 'checkout' });
Pionne.setEnabled(false); // kill switch
Pionne.addBreadcrumb({ category: 'ui', message: 'Click on #buy' });
Pionne.wrap(fn); // wrap un callback pour capturer ses throws

Auto-capture

window.onerror — exceptions non capturées
window.onunhandledrejection — promises rejetées sans .catch()

Auto-context

User-Agent, viewport (width/height), locale (navigator.language)
URL courante, referrer
Release, environment

Auto-breadcrumbs

console.log / console.warn / console.error
fetch() — URL avec query string strippée

Options

Option	Type	Description
`token`	`string`	Token Pionne (`pio_live_…`)
`release`	`string`	Version de l’app
`environment`	`string`	`production`, `staging`, etc.
`sampleRate`	`number`	0.0 — 1.0, ratio d’events envoyés
`scrubPii`	`boolean`	Masque emails, téléphones, IBAN
`beforeSend`	`(event) => event \| null`	Hook de filtrage
`sendGeography`	`boolean`	Opt-in : géoloc IP (ville/région/pays) attachée à chaque event. Défaut `false`.
`geographyEndpoint`	`string`	URL du lookup IP→geo. Défaut `https://ipapi.co/json/`.

Géographie (opt-in)

Comme Sentry, Pionne peut afficher la ville/région/pays approximatif du visiteur sur chaque event — utile pour repérer une régression localisée à un pays ou un FAI. Désactivé par défaut pour la vie privée.

Pionne.init({
  token: 'pio_live_…',
  sendGeography: true, // ← opt-in
});

Comment ça marche :

Un seul appel HTTP au démarrage vers https://ipapi.co/json/ (timeout 4 s).
Le résultat (ville, région, pays, code pays ISO) est mis en cache et joint à chaque event sous contexts.geo.
Si le lookup échoue (offline, blocage adblock, rate-limit), le SDK continue silencieusement sans géo.
Aucune coordonnée GPS, aucun tracking persistant — c’est juste l’inverse-DNS de l’IP du visiteur.

Tu veux ton propre fournisseur ? Passe geographyEndpoint: 'https://geo.tonapi.com/' — toute URL renvoyant un JSON { city, region, country, country_code } (ou country_name) marche.

Frameworks

import { Pionne, PionneErrorBoundary } from '@pionne/web';
import ReactDOM from 'react-dom/client';
import App from './App';

Pionne.init({ token: 'pio_live_…' });

ReactDOM.createRoot(document.getElementById('root')!).render(
  <PionneErrorBoundary fallback={<p>Oups, on a planté.</p>}>
    <App />
  </PionneErrorBoundary>
);

import { createApp } from 'vue';
import { Pionne } from '@pionne/web';
import App from './App.vue';

Pionne.init({ token: 'pio_live_…' });

const app = createApp(App);
app.config.errorHandler = (err) => Pionne.captureException(err as Error);
app.mount('#app');

import { Pionne } from '@pionne/web';
import App from './App.svelte';

Pionne.init({ token: 'pio_live_…' });

const app = new App({ target: document.getElementById('app')! });

// Svelte n'a pas de hook global — utilise window
window.addEventListener('error', (e) => Pionne.captureException(e.error));

export default app;

<script src="https://unpkg.com/@pionne/web@0.1.0/dist/pionne.umd.js"></script>
<script>
  Pionne.init({ token: 'pio_live_…' });
</script>

Source maps

Comme en React Native, les builds prod sont minifiés. Pour avoir des stacks lisibles, upload tes source maps :

npx @pionne/web upload-sourcemaps \
  --release 1.0.0 \
  --dir ./dist \
  --token pio_live_…

Tu peux aussi automatiser via un plugin Vite ou Webpack — voir le guide Source maps. Le concept est universel : ce qui change, c’est juste l’outil de build.

Anti-token-theft

Le pinning de Bundle ID est mobile uniquement (iOS/Android/RN/Flutter) — il protège contre la décompilation d’un APK/IPA. Sur web, le token vit dans une env var bundlée par ton bundler (VITE_PIONNE_TOKEN, NEXT_PUBLIC_PIONNE_TOKEN…) et est trivialement extractible du JS livré au navigateur — le mécanisme de bundle pinning ne peut rien y faire.

Le champ “Bundle ID” est masqué dans l’app mobile pour les projets Web. Pour limiter les abus :

Régénère le token (avec grace period 24 h) si tu suspectes une fuite — voir Tokens.
Rate-limit per-token côté serveur — voir Rate limits.
Tags pour différencier des déploiements/environnements :

Pionne.init({
  token: import.meta.env.VITE_PIONNE_TOKEN,
  tags: { deployment: 'prod', tenant: window.location.host },
});

Plus de détails : Bundle ID Pinning → Backends sans bundle_id.

Voir aussi

SDK React Native — pour les apps mobiles
SDK Node.js — pour le backend Node
API Ingest — protocole HTTP brut
Source maps — symbolication des stacks