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

# Instalando o AppSignal para Browser

<Note>
  Browser monitoring é uma funcionalidade em beta do [AppSignal Labs](/labs). O
  pacote `@appsignal/browser` é publicado sob a tag `beta` no npm, e sua
  configuração e API ainda podem mudar entre releases beta. Compartilhe seu
  feedback na nossa [comunidade no Discord](https://discord.gg/EjF6ykYx63).
</Note>

Use este guia para adicionar rastreamento de erros e Web Vitals do navegador à sua aplicação. Os exemplos em Plain JS e React também cobrem distributed tracing, filtragem de erros, mascaramento e tags.

Você pode gerar o código da sua aplicação no [Browser SDK install flow](https://appsignal.com/redirect-to/organization?to=sites/new/browser), ou seguir os exemplos abaixo. Se você ainda não adicionou sua aplicação ao AppSignal, siga primeiro o [guia de instalação](/guides/new-application).

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

Encontre a **Front-end API key** em **Front-end error monitoring**, na página [“Push & deploy”](https://appsignal.com/redirect-to/app?to=api_keys) das configurações da sua aplicação. Use a chave da aplicação e do ambiente que você quer monitorar. Essa chave deve ser incluída no código do navegador. Ela é diferente das Push API keys usadas pelas integrações de back-end.

O install flow já insere sua chave no código gerado. Nos exemplos abaixo, substitua `<YOUR_FRONTEND_API_KEY>` pela sua própria chave.

<h2 id="generate-the-snippet-in-appsignal">
  Gerar o snippet no AppSignal
</h2>

O [Browser SDK install flow](https://appsignal.com/redirect-to/organization?to=sites/new/browser) permite escolher **Plain JS** ou **React** e selecionar quais recursos incluir. Ele começa com **Route template** selecionado. Os exemplos completos abaixo incluem todas as opções:

| Opções | O que é incluído no seu snippet |
| - | - |
| Route template | `setRouteTemplate()` roda quando sua rota muda, para que `/users/42` possa ser relatado como `/users/:id`. |
| Distributed tracing | Adiciona `tracePropagationTargets` para que as requisições de API correspondentes levem um cabeçalho `traceparent`. Substitua o host de exemplo pelo seu. Isso configura apenas o navegador; o serviço de API que recebe a requisição também precisa de [instrumentação de tracing](/browser/distributed-tracing#before-you-start). |
| Error filtering | `beforeError` descarta erros que correspondem aos padrões de exemplo de navegador e extensão. Ajuste os padrões para a sua aplicação. |
| Error tags | `setTags()` adiciona valores como um plano ou tenant aos erros após o login. |
| Sensitive data masking | `privacy.dom` mascara texto ou exclui breadcrumbs de clique de elementos selecionados. Substitua os seletores CSS de exemplo pelos seus. |

O install flow gera código do Browser SDK. Selecionar **Distributed tracing** não instrumenta seu serviço de API. Para ver os spans dele junto com um erro de requisição do navegador, siga também a [configuração do back-end](/browser/distributed-tracing#before-you-start).

As duas versões também mostram como relatar um erro que você mesmo capturar. A versão em React inclui um error boundary para erros de renderização.

<h2 id="install-the-package">
  Instalar o pacote
</h2>

Instale o AppSignal para Browser a partir da tag `beta`. Distributed tracing e o relato de requisições com falha exigem a versão 1.0.0-beta.7 ou posterior. O install flow atualmente mostra um comando sem versão; use um destes comandos para a versão beta:

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

Faça commit do seu lockfile e revise o snippet ao atualizar durante a beta.

<h2 id="initialize-the-sdk">
  Inicializar o SDK
</h2>

Importe sua configuração do AppSignal antes do código da aplicação que você quer monitorar. Substitua `process.env.NODE_ENV` e `process.env.APP_REVISION` pelos valores equivalentes do seu sistema de build. Defina `appVersion` como sua tag de release ou SHA do commit, para o AppSignal associar os erros aos [sourcemaps](/browser/error-tracking#sourcemaps).

Esses exemplos incluem todas as opções do install flow. Substitua `api.example.com/**` pelo host e caminho da sua API para o [distributed tracing](/browser/distributed-tracing#enable-it). Substitua os seletores CSS, as tags e o exemplo de roteador pelos valores da sua aplicação.

<Tabs>
  <Tab title="Plain JS">
    **1. Inicialize o AppSignal em `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;
      },
    });
    ```

    Importe este arquivo primeiro no seu ponto de entrada:

    ```js main.js theme={null}
    import "./appsignal";

    // Start your application after this import.
    ```

    **2. Relate mudanças de rota a partir do seu roteador.** Substitua `router.on` pelo hook de navegação do seu roteador. Relate também a rota inicial e, depois, relate o modelo dela a cada navegação.

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

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

    **3. Adicione tags após o login.** Use valores do usuário ou da conta autenticada. Chame [`clearTags()`](/browser/configuration#api-reference) no logout para limpar as tags armazenadas.

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

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

    **4. Relate erros que você mesmo capturar.** Substitua `save()` pela sua própria operação.

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

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

  <Tab title="React">
    **1. Inicialize o AppSignal em `appsignal.js`.** Importe este arquivo antes de sua aplicação React iniciar.

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

    Importe este arquivo primeiro no seu ponto de entrada:

    ```js main.jsx theme={null}
    import "./appsignal";

    // Start your React application after this import.
    ```

    **2. Relate mudanças de rota.** Renderize `RouteReporter` dentro do seu roteador e passe o modelo de rota atual como `routePattern`. Hooks do React precisam rodar dentro de um componente.

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

    Veja os [exemplos de rota do React](/browser/react#reporting-the-current-route) para React Router e Next.js.

    **3. Adicione tags após o login.** Use valores do usuário ou da conta autenticada. Chame [`clearTags()`](/browser/configuration#api-reference) no logout para limpar as tags armazenadas.

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

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

    **4. Capture erros de renderização na raiz da sua aplicação.** O boundary relata erros de renderização que não chegam ao handler de erro global do navegador.

    ```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. Relate erros que você mesmo capturar.** Substitua `save()` pela sua própria operação.

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

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

**Se você só precisa de rastreamento de erros, breadcrumbs e web vitals**, pode começar com um arquivo `appsignal.js` menor. Substitua `<YOUR_APP_REVISION>` pela sua tag de release ou SHA do 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>

Importe `appsignal.js` primeiro no seu ponto de entrada, como mostrado acima. Essa configuração menor não adiciona cabeçalhos `traceparent` às suas requisições de API.

Para qualquer configuração, `active: false` impede que o SDK colete ou envie dados. `endpoint` usa por padrão a origem da página atual. Defina-o como `https://appsignal-endpoint.net`, a menos que você faça proxy das requisições do AppSignal pelo seu próprio domínio. Veja [todas as opções de configuração](/browser/configuration).

<h2 id="install-without-a-bundler">
  Instalação sem bundler
</h2>

Se o seu site carrega JavaScript com tags `<script>` e não usa um bundler, use o build UMD. Ele expõe o SDK como `AppsignalBrowser` em `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>

Substitua a versão na URL ao atualizar. Uma versão fixa evita uma mudança inesperada do SDK no seu site.

<h2 id="report-the-current-route">
  Reportar a rota atual
</h2>

Use esta etapa para uma aplicação de página única com rotas como `/users/42`. Passe o modelo de rota, como `/users/:id`, quando seu roteador navegar. O AppSignal o usa para agrupar erros e web vitals por rota. Os exemplos completos acima mostram onde chamar `setRouteTemplate()`.

Se você não definir um modelo de rota, o SDK relata o caminho atual da página. Isso significa que `/users/42` e `/users/43` podem aparecer como grupos de erro separados. Veja os [exemplos de rota do React](/browser/react#reporting-the-current-route) para React Router e Next.js.

<h2 id="verify-the-installation">
  Verificar a instalação
</h2>

1. Implante um build com `active` definido como `true`. Você pode usar `active: true` temporariamente em desenvolvimento.
2. Abra a página e execute este código no console do navegador:

   ```js JavaScript theme={null}
   setTimeout(() => { throw new Error("AppSignal test error"); }, 0);
   ```

   O timer permite que o erro chegue ao handler de erro global da página. Um erro lançado diretamente no console geralmente é tratado pelo próprio console.
3. Abra **Browser > Errors** no AppSignal e encontre **AppSignal test error**.

As web vitals aparecem depois que o SDK as envia. Isso acontece, por exemplo, quando a página fica oculta ou a rota muda. Se nenhum dado aparecer, veja a [solução de problemas do Browser](/browser/troubleshooting).

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

Se o seu site usa uma Content Security Policy, permita o endpoint do AppSignal configurado na diretiva `connect-src`. Por exemplo, adicione o endpoint às suas origens já permitidas:

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

<h2 id="assets-hosted-on-a-cdn">
  Assets hospedados em CDN
</h2>

Use esta etapa se o JavaScript do seu site carrega de outra origem, como um CDN. Sem acesso cross-origin, o navegador pode relatar apenas `Script error.`, sem stack trace e sem número de linha. O SDK descarta esses erros opacos porque não é possível rastreá-los até o seu código.

Sirva o script com um cabeçalho `Access-Control-Allow-Origin` que permita a origem da sua página, e adicione `crossorigin="anonymous"` à tag 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">
  Desinstalação
</h2>

1. Remova o import de `appsignal.js` e outras chamadas a `@appsignal/browser` do seu código. Remova qualquer `ErrorBoundary` importado de `@appsignal/browser/react`.
2. Remova o pacote e atualize seu lockfile com `npm uninstall @appsignal/browser`, `yarn remove @appsignal/browser` ou `pnpm remove @appsignal/browser`. Se você instalou o build UMD, remova a tag `<script>` dele.
3. Implante a mudança. O novo build para de relatar dados do navegador.
4. Se essa aplicação do AppSignal era usada só para browser monitoring, você pode opcionalmente [remover a aplicação](/guides/application/deleting-applications).

Para parar a coleta sem desinstalar, chame `destroy()`. Isso envia os dados pendentes e para a coleta até `init()` rodar novamente, por exemplo após um reload da página.


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