> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> SDK de navegador para ClickStack - a stack de observabilidade do ClickHouse

# JS para navegador

O SDK de navegador do ClickStack permite instrumentar sua aplicação de frontend para
enviar eventos ao ClickStack. Com isso, você pode visualizar solicitações de rede
e exceções junto com eventos de backend em uma única linha do tempo.

Além disso, ele captura e correlaciona automaticamente dados de replay de sessão, para que
você possa acompanhar visualmente e depurar o que um usuário estava vendo enquanto usava sua
aplicação.

Este guia integra o seguinte:

* **Logs do Console**
* **Replays de Sessão**
* **Solicitações XHR/Fetch/WebSocket**
* **Exceções**

<div id="getting-started">
  ## Primeiros passos
</div>

<br />

<Tabs>
  <Tab title="Importação de pacote">
    **Instale por importação de pacote (recomendado)**

    Use o comando a seguir para instalar o [pacote do navegador](https://www.npmjs.com/package/@hyperdx/browser).

    ```shell theme={null}
    npm install @hyperdx/browser
    ```

    **Inicialize o ClickStack**

    ```javascript theme={null}
    import HyperDX from '@hyperdx/browser';

    HyperDX.init({
        url: 'http://your-otel-collector:4318',
        apiKey: 'YOUR_INGESTION_API_KEY', //omita para Managed ClickStack
        service: 'my-frontend-app',
        tracePropagationTargets: [/api.myapp.domain/i], // Defina para vincular traces do frontend a requisições de backend
        consoleCapture: true, // Captura logs do console (padrão: false)
        advancedNetworkCapture: true, // Captura cabeçalhos e corpos completos de requisição/resposta HTTP (padrão: false)
    });
    ```
  </Tab>

  <Tab title="Tag de script">
    **Instale via tag de script (alternativa)**

    Você também pode incluir e instalar o script por meio de uma tag de script, em vez de
    instalá-lo via NPM. Isso expõe a variável global `HyperDX` e pode ser
    usada da mesma forma que o pacote NPM.

    Isso é recomendado se o seu site não usa um bundler no momento.

    ```html theme={null}
    <script src="//www.unpkg.com/@hyperdx/browser@0.21.0/build/index.js"></script>
    <script>
      window.HyperDX.init({
        url: 'http://localhost:4318',
        apiKey: 'YOUR_INGESTION_API_KEY', //omita para Managed ClickStack
        service: 'my-frontend-app',
        tracePropagationTargets: [/api.myapp.domain/i], // Defina para vincular traces do frontend a requisições de backend
      });
    </script>
    ```
  </Tab>
</Tabs>

<div id="options">
  ### Opções
</div>

* `apiKey` - Sua API key de ingestão do ClickStack.
* `service` - O nome do serviço com que os eventos aparecerão na UI do HyperDX.
* `tracePropagationTargets` - Uma lista de padrões regex para corresponder a
  requisições HTTP e vincular traces de frontend e backend; isso adicionará um
  cabeçalho `traceparent` adicional a todas as requisições que correspondam a
  qualquer um dos padrões. Isso deve ser definido como o domínio da API do seu
  backend (ex.: `api.yoursite.com`).
* `consoleCapture` - (Opcional) Captura todos os logs do console (padrão `false`).
* `advancedNetworkCapture` - (Opcional) Captura cabeçalhos e corpos completos
  de requisições e respostas (padrão `false`).
* `url` - (Opcional) A URL do OpenTelemetry Collector, necessária apenas para
  instâncias self-hosted.
* `maskAllInputs` - (Opcional) Se deve mascarar todos os campos de entrada no
  replay de sessão (padrão `false`).
* `maskAllText` - (Opcional) Se deve mascarar todo o texto no replay de sessão (padrão
  `false`).
* `disableIntercom` - (Opcional) Se deve desabilitar a integração com o Intercom (padrão `false`)
* `disableReplay` - (Opcional) Se deve desabilitar o replay de sessão (padrão `false`)

<div id="additional-configuration">
  ## Configuração adicional
</div>

<div id="attach-user-information-or-metadata">
  ### Associar informações ou metadados do usuário
</div>

Associar informações do usuário permitirá que você pesquise/filtre sessões e eventos
na UI do HyperDX. Isso pode ser feito a qualquer momento durante a sessão do cliente. A
sessão atual do cliente e todos os eventos enviados após essa chamada serão associados
às informações do usuário.

`userEmail`, `userName` e `teamName` preencherão a UI de sessões com os
valores correspondentes, mas podem ser omitidos. Quaisquer outros valores adicionais podem ser
especificados e usados para pesquisar eventos.

```javascript theme={null}
HyperDX.setGlobalAttributes({
  userId: user.id,
  userEmail: user.email,
  userName: user.name,
  teamName: user.team.name,
  // Outras propriedades personalizadas...
});
```

<div id="auto-capture-react-error-boundary-errors">
  ### Captura automática de erros em error boundaries do React
</div>

Se você estiver usando React, poderá capturar automaticamente erros que ocorram em
error boundaries do React ao passar seu componente de error boundary
para a função `attachToReactErrorBoundary`.

```javascript theme={null}
// Importe seu ErrorBoundary (estamos usando react-error-boundary como exemplo)
import { ErrorBoundary } from 'react-error-boundary';

// Isso se conectará ao componente ErrorBoundary e capturará quaisquer erros que ocorram
// em qualquer instância dele.
HyperDX.attachToReactErrorBoundary(ErrorBoundary);
```

<div id="send-custom-actions">
  ### Enviar ações personalizadas
</div>

Para rastrear explicitamente um evento específico da aplicação (ex.: cadastro, envio,
etc.), você pode chamar a função `addAction` com o nome do evento e metadados
opcionais do evento.

Exemplo:

```javascript theme={null}
HyperDX.addAction('Form-Completed', {
  formId: 'signup-form',
  formName: 'Signup Form',
  formType: 'signup',
});
```

<div id="enable-network-capture-dynamically">
  ### Ativar a captura de rede dinamicamente
</div>

Para ativar ou desativar a captura de rede dinamicamente, basta chamar a função `enableAdvancedNetworkCapture` ou `disableAdvancedNetworkCapture`, conforme necessário.

```javascript theme={null}
HyperDX.enableAdvancedNetworkCapture();
```

<div id="enable-resource-timing-for-cors-requests">
  ### Habilite a medição de tempo de recursos para solicitações CORS
</div>

Se o seu aplicativo frontend faz solicitações de API para um domínio diferente, você pode
opcionalmente habilitar o cabeçalho [`Timing-Allow-Origin`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Timing-Allow-Origin) para ser enviado com a solicitação. Isso permitirá que o ClickStack capture informações detalhadas de
tempo do recurso para a solicitação, como resolução de DNS, download da resposta
etc., por meio de [`PerformanceResourceTiming`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceResourceTiming).

Se você estiver usando `express` com os pacotes `cors`, poderá usar o snippet
a seguir para habilitar o cabeçalho:

```javascript theme={null}
var cors = require('cors');
var onHeaders = require('on-headers');

// ... todo o seu código

app.use(function (req, res, next) {
  onHeaders(res, function () {
    var allowOrigin = res.getHeader('Access-Control-Allow-Origin');
    if (allowOrigin) {
      res.setHeader('Timing-Allow-Origin', allowOrigin);
    }
  });
  next();
});
app.use(cors());
```