> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installer AppSignal pour Browser

<Note>
  Browser monitoring est une fonctionnalité en beta d'[AppSignal Labs](/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](https://discord.gg/EjF6ykYx63).
</Note>

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](https://appsignal.com/redirect-to/organization?to=sites/new/browser), ou suivre les exemples ci-dessous. Si vous n'avez pas encore ajouté votre application à AppSignal, suivez d'abord le [guide d'installation](/guides/new-application).

<h2 id="find-your-front-end-api-key">
  Trouver votre Front-end API key
</h2>

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 »](https://appsignal.com/redirect-to/app?to=api_keys). 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é.

<h2 id="generate-the-snippet-in-appsignal">
  Générer le snippet dans AppSignal
</h2>

Le [Browser SDK install flow](https://appsignal.com/redirect-to/organization?to=sites/new/browser) 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](/browser/distributed-tracing#before-you-start). |
| 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](/browser/distributed-tracing#before-you-start).

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.

<h2 id="install-the-package">
  Installer le package
</h2>

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 :

<CodeGroup>
  ```sh npm theme={null}
  npm install @appsignal/browser@beta
  ```

  ```sh yarn theme={null}
  yarn add @appsignal/browser@beta
  ```

  ```sh pnpm theme={null}
  pnpm add @appsignal/browser@beta
  ```
</CodeGroup>

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

<h2 id="initialize-the-sdk">
  Initialiser le SDK
</h2>

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](/browser/error-tracking#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é](/browser/distributed-tracing#enable-it). Remplacez les sélecteurs CSS, les tags et l'exemple de routeur par les valeurs de votre application.

<Tabs>
  <Tab title="Plain JS">
    **1. Initialisez AppSignal dans `appsignal.js`.**

    ```js appsignal.js theme={null}
    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 :

    ```js main.js theme={null}
    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.

    ```js router.js theme={null}
    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()`](/browser/configuration#api-reference) à la déconnexion pour effacer les tags enregistrés.

    ```js account.js theme={null}
    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.

    ```js save.js theme={null}
    import { captureError } from "@appsignal/browser";

    try {
      save();
    } catch (error) {
      captureError(error);
    }
    ```
  </Tab>

  <Tab title="React">
    **1. Initialisez AppSignal dans `appsignal.js`.** Importez ce fichier avant le démarrage de votre application React.

    ```js appsignal.js theme={null}
    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 :

    ```js main.jsx theme={null}
    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.

    ```jsx RouteReporter.jsx theme={null}
    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](/browser/react#reporting-the-current-route) 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()`](/browser/configuration#api-reference) à la déconnexion pour effacer les tags enregistrés.

    ```js account.js theme={null}
    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.

    ```jsx AppRoot.jsx theme={null}
    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.

    ```js save.js theme={null}
    import { captureError } from "@appsignal/browser";

    try {
      save();
    } catch (error) {
      captureError(error);
    }
    ```
  </Tab>
</Tabs>

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

<CodeGroup>
  ```js appsignal.js theme={null}
  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>",
  });
  ```
</CodeGroup>

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](/browser/configuration).

<h2 id="install-without-a-bundler">
  Installation sans bundler
</h2>

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

<CodeGroup>
  ```html HTML theme={null}
  <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>
  ```
</CodeGroup>

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.

<h2 id="report-the-current-route">
  Signaler la route actuelle
</h2>

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](/browser/react#reporting-the-current-route) pour React Router et Next.js.

<h2 id="verify-the-installation">
  Vérifier l'installation
</h2>

1. Déployez un build avec `active` défini sur `true`. Vous pouvez temporairement utiliser `active: true` en développement.
2. Ouvrez la page et exécutez ce code dans la console du navigateur :

   ```js JavaScript theme={null}
   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.
3. 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](/browser/troubleshooting).

<h2 id="content-security-policy">
  Content Security Policy
</h2>

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 :

<CodeGroup>
  ```http HTTP theme={null}
  Content-Security-Policy: connect-src 'self' https://appsignal-endpoint.net
  ```
</CodeGroup>

<h2 id="assets-hosted-on-a-cdn">
  Assets hébergés sur un CDN
</h2>

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 :

<CodeGroup>
  ```html HTML theme={null}
  <script src="https://cdn.example.com/bundle.js" crossorigin="anonymous"></script>
  ```

  ```erb Rails theme={null}
  <%= javascript_include_tag "application", :crossorigin => :anonymous %>
  ```
</CodeGroup>

<h2 id="uninstall">
  Désinstallation
</h2>

1. Retirez l'import `appsignal.js` et les autres appels à `@appsignal/browser` de votre code. Retirez tout `ErrorBoundary` importé depuis `@appsignal/browser/react`.
2. 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>`.
3. Déployez le changement. Le nouveau build cesse de rapporter des données du navigateur.
4. Si cette application AppSignal ne servait qu'au browser monitoring, vous pouvez éventuellement [supprimer l'application](/guides/application/deleting-applications).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.