Installer AppSignal pour Browser

Browser monitoring est une fonctionnalité en beta d’AppSignal Labs. Le package @appsignal/browser est publié sous le tag beta sur npm, et sa configuration ainsi que son API peuvent encore changer d’une release beta à l’autre. Partagez vos retours dans notre communauté Discord.

Suivez ce guide pour ajouter le suivi des erreurs et les Web Vitals du navigateur à votre application. Les exemples Plain JS et React couvrent aussi le tracing distribué, le filtrage des erreurs, le masquage et les tags. Vous pouvez générer le code de votre application dans le Browser SDK install flow, ou suivre les exemples ci-dessous. Si vous n’avez pas encore ajouté votre application à AppSignal, suivez d’abord le guide d’installation.

Trouver votre Front-end API key

Trouvez la Front-end API key sous Front-end error monitoring, dans les paramètres de votre application. Elle se trouve sur la page « Push & deploy ». Utilisez la clé de l’application et de l’environnement que vous souhaitez surveiller. Cette clé est destinée à être incluse dans le code du navigateur. Elle est différente des Push API keys utilisées par les intégrations back-end. L’install flow insère votre clé dans le code généré. Dans les exemples ci-dessous, remplacez <YOUR_FRONTEND_API_KEY> par votre propre clé.

Générer le snippet dans AppSignal

Le Browser SDK install flow vous permet de choisir Plain JS ou React et de sélectionner les fonctionnalités à inclure. Route template est sélectionné par défaut. Les exemples complets ci-dessous incluent toutes les options :

Options	Ce qui est inclus dans votre snippet
Route template	`setRouteTemplate()` s’exécute à chaque changement de route, afin que `/users/42` puisse être rapporté comme `/users/:id`.
Distributed tracing	Ajoute `tracePropagationTargets` afin que les requêtes API correspondantes portent un en-tête `traceparent`. Remplacez l’hôte d’exemple par le vôtre. Cela ne configure que le navigateur ; le service API qui reçoit la requête a aussi besoin d’une instrumentation de tracing.
Error filtering	`beforeError` ignore les erreurs qui correspondent aux motifs d’exemple pour les navigateurs et extensions. Adaptez les motifs à votre application.
Error tags	`setTags()` ajoute des valeurs comme un plan ou un tenant aux erreurs après la connexion.
Sensitive data masking	`privacy.dom` masque du texte ou exclut les breadcrumbs de clic pour les éléments sélectionnés. Remplacez les sélecteurs CSS d’exemple par les vôtres.

L’install flow génère du code Browser SDK. Sélectionner Distributed tracing n’instrumente pas votre service API. Pour voir ses spans à côté d’une erreur de requête du navigateur, suivez aussi la configuration back-end. Les deux versions montrent aussi comment rapporter une erreur que vous capturez vous-même. La version React inclut une error boundary pour les erreurs de rendu.

Installer le package

Installez AppSignal pour Browser depuis le tag beta. Le tracing distribué et le rapport des requêtes échouées nécessitent la version 1.0.0-beta.7 ou ultérieure. L’install flow affiche actuellement une commande sans version ; utilisez l’une de ces commandes pour la version bêta :

npm install @appsignal/browser@beta

yarn add @appsignal/browser@beta

pnpm add @appsignal/browser@beta

Committez votre lockfile et vérifiez le snippet lorsque vous mettez à jour pendant la bêta.

Initialiser le SDK

Importez votre configuration AppSignal avant le code applicatif que vous souhaitez surveiller. Remplacez process.env.NODE_ENV et process.env.APP_REVISION par les valeurs équivalentes de votre système de build. Définissez appVersion sur votre tag de release ou votre SHA de commit afin qu’AppSignal puisse associer les erreurs aux sourcemaps. Ces exemples incluent toutes les options de l’install flow. Remplacez api.example.com/** par l’hôte et le chemin de votre API pour le tracing distribué. Remplacez les sélecteurs CSS, les tags et l’exemple de routeur par les valeurs de votre application.

Plain JS
React

1. Initialisez AppSignal dans appsignal.js.

appsignal.js

import { init } from "@appsignal/browser";

const IGNORED = [
  /ResizeObserver loop/,
  /^Script error\.?$/,
  /-extension:\/\//,
  /webkit-masked-url/,
];

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  // Inactive builds send nothing. Replace these with your build values.
  active: process.env.NODE_ENV === "production",
  appVersion: process.env.APP_REVISION,
  // Match your API host and path.
  tracePropagationTargets: ["api.example.com/**"],
  privacy: {
    // Mask text or exclude clicks on these elements.
    dom: { maskText: [".user-email"], blockElement: ["#card-form"] },
  },
  beforeError: (error) => {
    const text = [error.message, error.stack, error.filename].join(" ");
    return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
  },
});

Importez-le en premier dans votre point d’entrée :

main.js

import "./appsignal";

// Start your application after this import.

2. Rapportez les changements de route depuis votre routeur. Remplacez router.on par le hook de navigation de votre routeur. Rapportez aussi la route initiale, puis rapportez son modèle à chaque navigation.

router.js

import { setRouteTemplate } from "@appsignal/browser";

router.on("navigate", (route) => {
  setRouteTemplate(route.pattern); // "/users/:id", not "/users/42"
});

3. Ajoutez des tags après la connexion. Utilisez des valeurs de l’utilisateur ou du compte connecté. Appelez clearTags() à la déconnexion pour effacer les tags enregistrés.

account.js

import { setTags } from "@appsignal/browser";

setTags({ plan: "pro", tenant: "acme" });

4. Rapportez les erreurs que vous capturez vous-même. Remplacez save() par votre propre opération.

save.js

import { captureError } from "@appsignal/browser";

try {
  save();
} catch (error) {
  captureError(error);
}

1. Initialisez AppSignal dans appsignal.js. Importez ce fichier avant le démarrage de votre application React.

appsignal.js

import { init } from "@appsignal/browser";

const IGNORED = [
  /ResizeObserver loop/,
  /^Script error\.?$/,
  /-extension:\/\//,
  /webkit-masked-url/,
];

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  // Inactive builds send nothing. Replace these with your build values.
  active: process.env.NODE_ENV === "production",
  appVersion: process.env.APP_REVISION,
  // Match your API host and path.
  tracePropagationTargets: ["api.example.com/**"],
  privacy: {
    // Mask text or exclude clicks on these elements.
    dom: { maskText: [".user-email"], blockElement: ["#card-form"] },
  },
  beforeError: (error) => {
    const text = [error.message, error.stack, error.filename].join(" ");
    return IGNORED.some((pattern) => pattern.test(text)) ? null : error;
  },
});

Importez-le en premier dans votre point d’entrée :

main.jsx

import "./appsignal";

// Start your React application after this import.

2. Rapportez les changements de route. Rendez RouteReporter à l’intérieur de votre routeur et passez-lui son modèle de route courant comme routePattern. Les hooks React doivent s’exécuter à l’intérieur d’un composant.

RouteReporter.jsx

import { useEffect } from "react";
import { setRouteTemplate } from "@appsignal/browser";

export function RouteReporter({ routePattern }) {
  useEffect(() => {
    setRouteTemplate(routePattern); // "/users/:id", not "/users/42"
  }, [routePattern]);

  return null;
}

Consultez les exemples de route React pour React Router et Next.js.3. Ajoutez des tags après la connexion. Utilisez des valeurs de l’utilisateur ou du compte connecté. Appelez clearTags() à la déconnexion pour effacer les tags enregistrés.

account.js

import { setTags } from "@appsignal/browser";

setTags({ plan: "pro", tenant: "acme" });

4. Interceptez les erreurs de rendu à la racine de votre application. La boundary rapporte les erreurs de rendu qui n’atteignent pas le gestionnaire d’erreurs global du navigateur.

AppRoot.jsx

import { captureError } from "@appsignal/browser";
import { ErrorBoundary } from "@appsignal/browser/react";

<ErrorBoundary
  captureError={captureError}
  fallback={<p>This page didn't load. Reload to try again.</p>}
>
  <App />
</ErrorBoundary>

5. Rapportez les erreurs que vous capturez vous-même. Remplacez save() par votre propre opération.

save.js

import { captureError } from "@appsignal/browser";

try {
  save();
} catch (error) {
  captureError(error);
}

Si vous n’avez besoin que du suivi des erreurs, des breadcrumbs et des web vitals, utilisez un appsignal.js plus simple. Remplacez <YOUR_APP_REVISION> par votre tag de release ou votre SHA de commit :

import { init } from "@appsignal/browser";

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  active: process.env.NODE_ENV === "production",
  appVersion: "<YOUR_APP_REVISION>",
});

Importez appsignal.js en premier dans votre point d’entrée, comme montré ci-dessus. Cette configuration plus simple n’ajoute pas d’en-têtes traceparent à vos requêtes API. Pour toute configuration, active: false empêche le SDK de collecter ou d’envoyer des données. endpoint utilise par défaut l’origine de la page actuelle. Définissez-le sur https://appsignal-endpoint.net, sauf si vous faites transiter les requêtes AppSignal par votre propre domaine. Consultez toutes les options de configuration.

Installation sans bundler

Si votre site charge le JavaScript avec des balises <script> et n’utilise pas de bundler, utilisez le build UMD. Il expose le SDK sous le nom AppsignalBrowser sur window :

<script src="https://cdn.jsdelivr.net/npm/@appsignal/browser@1.0.0-beta.7/dist/browser.umd.js"></script>
<script>
  AppsignalBrowser.init({
    key: "<YOUR_FRONTEND_API_KEY>",
    endpoint: "https://appsignal-endpoint.net",
    appVersion: "<YOUR_APP_REVISION>",
  });
</script>

Remplacez la version dans l’URL lorsque vous effectuez une mise à jour. Une version fixe évite qu’un changement inattendu du SDK n’affecte votre site.

Signaler la route actuelle

Suivez cette étape pour une application monopage avec des routes comme /users/42. Passez le modèle de route, par exemple /users/:id, à chaque navigation de votre routeur. AppSignal l’utilise pour regrouper les erreurs et les web vitals par route. Les exemples complets ci-dessus montrent où appeler setRouteTemplate(). Si vous ne définissez pas de modèle de route, le SDK rapporte le chemin de la page actuelle. Cela signifie que /users/42 et /users/43 peuvent apparaître comme des groupes d’erreurs distincts. Consultez les exemples de route React pour React Router et Next.js.

Vérifier l’installation

Déployez un build avec active défini sur true. Vous pouvez temporairement utiliser active: true en développement.
Ouvrez la page et exécutez ce code dans la console du navigateur :
JavaScript
setTimeout(() => { throw new Error("AppSignal test error"); }, 0);
Le timer permet à l’erreur d’atteindre le gestionnaire d’erreurs global de la page. Une erreur levée directement dans la console est généralement interceptée par la console elle-même.
Ouvrez Browser > Errors dans AppSignal et trouvez AppSignal test error.

Les web vitals apparaissent une fois que le SDK les envoie. Cela se produit, par exemple, lorsque la page est masquée ou que la route change. Si aucune donnée n’apparaît, consultez le dépannage pour Browser.

Content Security Policy

Si votre site utilise une Content Security Policy, autorisez le point de terminaison AppSignal configuré dans sa directive connect-src. Par exemple, ajoutez le point de terminaison à vos sources déjà autorisées :

Content-Security-Policy: connect-src 'self' https://appsignal-endpoint.net

Assets hébergés sur un CDN

Suivez cette étape si le JavaScript de votre site se charge depuis une autre origine, comme un CDN. Sans accès cross-origin, le navigateur peut ne rapporter que Script error., sans stack trace ni numéro de ligne. Le SDK écarte ces erreurs opaques car elles ne peuvent pas être retracées jusqu’à votre code. Servez le script avec un en-tête Access-Control-Allow-Origin qui autorise l’origine de votre page, et ajoutez crossorigin="anonymous" à la balise de script :

<script src="https://cdn.example.com/bundle.js" crossorigin="anonymous"></script>

<%= javascript_include_tag "application", :crossorigin => :anonymous %>

Désinstallation

Retirez l’import appsignal.js et les autres appels à @appsignal/browser de votre code. Retirez tout ErrorBoundary importé depuis @appsignal/browser/react.
Retirez le package et mettez à jour votre lockfile avec npm uninstall @appsignal/browser, yarn remove @appsignal/browser ou pnpm remove @appsignal/browser. Si vous avez installé le build UMD, retirez plutôt sa balise <script>.
Déployez le changement. Le nouveau build cesse de rapporter des données du navigateur.
Si cette application AppSignal ne servait qu’au browser monitoring, vous pouvez éventuellement supprimer l’application.

Pour arrêter la collecte sans désinstaller, appelez destroy(). Cela envoie les données en attente et arrête la collecte jusqu’à la prochaine exécution de init(), par exemple après un rechargement de page.

SDK & télémétrie

SDK de langage

Outils de télémétrie

Trouver votre Front-end API key

Générer le snippet dans AppSignal

Installer le package

Initialiser le SDK

Installation sans bundler

Signaler la route actuelle

Vérifier l’installation

Content Security Policy

Assets hébergés sur un CDN

Désinstallation

​Trouver votre Front-end API key

​Générer le snippet dans AppSignal

​Installer le package

​Initialiser le SDK

​Installation sans bundler

​Signaler la route actuelle

​Vérifier l’installation

​Content Security Policy

​Assets hébergés sur un CDN

​Désinstallation

Trouver votre Front-end API key

Générer le snippet dans AppSignal

Installer le package

Initialiser le SDK

Installation sans bundler

Signaler la route actuelle

Vérifier l’installation

Content Security Policy

Assets hébergés sur un CDN

Désinstallation