Privacidade e filtragem de dados do navegador

Browser monitoring é uma funcionalidade em beta do AppSignal 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.

Telemetria de front-end está mais perto de dados pessoais do que telemetria de back-end. URLs carregam tokens, formulários carregam números de cartão, e o texto de um botão pode ser o total de um pedido. O AppSignal para Browser é conservador por padrão, e todas as decisões restantes são suas para configurar.

O que é protegido por padrão

Sem nenhuma configuração:

A maioria dos campos de URL criados pelo SDK omite parâmetros de query por padrão. Isso cobre URLs de páginas de erro, URLs de páginas de web vitals, breadcrumbs de navegação e breadcrumbs de fetch/XMLHttpRequest. O breadcrumb de rede inicial do carregamento do documento é uma exceção, explicada abaixo.
O SDK não lê corpos de requisição ou resposta de chamadas de rede. Revise os dados que seu próprio código coloca em erros, saída do console, tags ou breadcrumbs manuais.
Nenhum cookie é lido ou escrito. O SDK guarda valores appsignal_* em localStorage e sessionStorage. Isso inclui IDs aleatórios de sessão, aba e visitante, o horário de atividade e as tags que você definiu. O ID de visitante é um valor aleatório sem nada pessoal. O ID de visitante persiste entre visitas. Trate-o como identificador no seu aviso de privacidade.
Avisos e erros do console são cortados após os primeiros 200 caracteres. O SDK não captura console.log.
Nada é enviado quando active é false. O SDK não altera nada na página, não inicia temporizadores e não faz requisições.

URLs e parâmetros de query

privacy.queryParamsAllowlist lista os parâmetros de query a manter nos campos de URL abaixo. Os demais parâmetros de query são removidos desses campos. Você pode usar * para corresponder a vários nomes de uma vez, então utm_* mantém todos os parâmetros UTM. A lista padrão é vazia, o que remove todos eles. Isso se aplica a breadcrumbs de fetch/XMLHttpRequest e de navegação. Também se aplica a erros de requisição relatados automaticamente, URLs de páginas de erro, referrers e URLs de páginas de web vitals.

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  privacy: {
    queryParamsAllowlist: ["utm_*", "page"],
  },
});

Com essa configuração:

URL	Campo de URL filtrado
`https://example.com/search?q=alice@corp.com&page=2`	`https://example.com/search?page=2`
`https://example.com/dashboard?utm_source=email&token=abc`	`https://example.com/dashboard?utm_source=email`
`https://example.com/callback#access_token=ey123&token_type=bearer`	`https://example.com/callback`
`https://example.com/checkout#/payment`	inalterada

As duas últimas linhas são o par importante. As duas URLs têm algo depois de um #, e são tratadas de formas diferentes de propósito. A terceira URL tem dados no formato de query simples depois do #, então o SDK remove o token dela desses campos filtrados. A quarta URL é uma rota baseada em hash, que o SDK preserva. Isso inclui qualquer texto de query dentro de uma rota baseada em hash, como #/payment?token=abc. Mantenha segredos fora de rotas baseadas em hash. Âncoras simples como #pricing também são preservadas.

O breadcrumb de rede inicial do carregamento do documento atualmente usa a URL de destino completa, mesmo quando queryParamsAllowlist está vazio. networkBlocklist não o filtra. Se as URLs de destino puderem conter segredos, descarte esse breadcrumb com beforeBreadcrumb:

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

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  endpoint: "https://appsignal-endpoint.net",
  beforeBreadcrumb: (breadcrumb) =>
    breadcrumb.category === "network" && breadcrumb.data?.initiator === "document"
      ? null
      : breadcrumb,
});

Excluindo requisições de rede

privacy.networkBlocklist lista chamadas fetch e XMLHttpRequest que não devem deixar breadcrumb, e que também nunca são relatadas como requisições com falha. A requisição continua acontecendo normalmente. Apenas o registro dela é ignorado. Os padrões são comparados com o host e o caminho da URL. Um * sozinho corresponde a uma parte do caminho, e ** corresponde a qualquer número de partes.

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  privacy: {
    networkBlocklist: [
      "api.stripe.com/**",      // every request to that host
      "*/auth/token",           // that path on any host
      "example.com/users/*/card" // any single ID in that position
    ],
  },
});

Mascarando e bloqueando elementos da página

Duas opções controlam o que é registrado quando um usuário seleciona algo. As duas opções recebem seletores CSS. Selecionar um contêiner também cobre seus descendentes. privacy.dom.maskText substitui o texto de um elemento correspondente por [masked]. O breadcrumb continua sendo registrado, então você mantém o fato de que alguém o selecionou:

maskText: [".pay-button"]

click  button "Pay $42.00"   →   click  button "[masked]"

Um rótulo data-breadcrumb tem precedência sobre o mascaramento de texto. Não coloque valores sensíveis nesse atributo. privacy.dom.blockElement não registra nada. Use para formulários de cartão, números de documento e qualquer coisa que nunca deva aparecer:

blockElement: ["#card-form"]

click  input#cvc   →   (nothing recorded)

Essas duas opções afetam apenas o que é registrado quando um usuário seleciona algo. Elas não tocam mensagens de erro, URLs de rede nem avisos e erros do console. Para isso, use queryParamsAllowlist, networkBlocklist e as duas funções da seção a seguir.

Filtrando erros e breadcrumbs

Dois hooks permitem filtrar erros antes de serem relatados e breadcrumbs antes de entrarem no buffer. Nenhum dos dois pode ser async. beforeError roda para erros que passam pelo sampling e pelo limite de taxa global. Retorne null para descartar um erro, ou altere seus campos para remover texto sensível:

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

const EMAIL_PATTERN = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  beforeError: (event) => {
    // Drop known noise
    if (/ResizeObserver/.test(event.message)) return null;

    // Redact email addresses from the message and the stack
    event.message = event.message.replace(EMAIL_PATTERN, "[redacted]");
    event.stack = event.stack?.replace(EMAIL_PATTERN, "[redacted]");
    return event;
  },
});

Retornar null não envia nenhum erro e não adiciona nenhum breadcrumb de erro. O limite de taxa global é verificado primeiro, então erros descartados ainda contam para ele. Uma requisição com falha chega aqui como HTTPError ou TimeoutError. Seus campos url, method, status e duration_ms ficam em context.request. Se você redigir a URL ali, redija-a também na mensagem de erro, que contém a URL da requisição. beforeBreadcrumb roda uma vez para cada breadcrumb, no momento em que ele é registrado. Retorne null para descartá-lo, ou altere seu message e seu data:

init({
  key: "<YOUR_FRONTEND_API_KEY>",
  beforeBreadcrumb: (breadcrumb) => {
    if (breadcrumb.category === "console") return null;
    return breadcrumb;
  },
});

beforeError não consegue ver breadcrumbs, porque eles são anexados ao erro depois que essa função o aprovou. Use beforeBreadcrumb para limpar o conteúdo dos breadcrumbs.

Nenhuma das duas funções pode ser async. Se beforeError retornar uma promise, o AppSignal registra um console.error e descarta o erro. Faça qualquer trabalho lento antes de chamar captureError, não dentro dessas funções.

Nada é coletado até init() rodar, então pedir consentimento primeiro é uma questão de não chamá-lo até obtê-lo:

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

if (consent.granted("analytics")) {
  init({ key: "<YOUR_FRONTEND_API_KEY>", endpoint: "https://appsignal-endpoint.net" });
}

consent.on("revoked", () => destroy());

destroy() interrompe a coleta imediatamente, enviando o que já havia reunido. Isso afeta apenas a página em que o usuário está. Guarde a decisão dele por conta própria e verifique-a antes de chamar init(), ou a próxima página que ele abrir começa a coletar de novo.

O que você pode dizer aos seus usuários

Um erro relatado pode incluir até 25 breadcrumbs recentes. Dependendo do que aconteceu antes dele, eles podem descrever:

As páginas que abriram.
O que selecionaram e em que ponto da tela selecionaram. Rótulos de clique podem incluir texto visível, então mascare elementos sensíveis.
As requisições que a página fez, e se cada uma teve sucesso.
Avisos e erros que a página registrou no console.
Tarefas longas.

O erro também inclui todas as tags que você definiu. Lotes de web vitals contêm valores de métricas e contexto da visita, mas não incluem esse histórico de breadcrumbs por padrão. A página de breadcrumbs tem a lista completa. Cada lote de web vitals também carrega contexto da visita. Isso inclui IDs aleatórios de sessão, aba e visitante, a URL da página e seu referrer. Também inclui o user agent, o tamanho da tela e da janela, o idioma e o fuso horário. Onde o navegador os disponibiliza, também carrega o tipo de conexão e quanta memória o dispositivo tem. O SDK não lê diretamente valores de campos de formulário, corpos de rede ou cookies. O SDK gera um ID de visitante aleatório. Ele persiste no dispositivo entre visitas. Suas próprias mensagens de erro, tags e breadcrumbs podem conter detalhes pessoais. Revise-os antes de enviar dados ao AppSignal.

SDKs & telemetria

SDKs de linguagem

Ferramentas de telemetria

Privacidade e filtragem de dados do navegador

O que é protegido por padrão

URLs e parâmetros de query

Excluindo requisições de rede

Mascarando e bloqueando elementos da página

O que você pode dizer aos seus usuários

​O que é protegido por padrão

​URLs e parâmetros de query

​Excluindo requisições de rede

​Mascarando e bloqueando elementos da página

​Filtrando erros e breadcrumbs

​Consentimento de rastreamento

​O que você pode dizer aos seus usuários

O que é protegido por padrão

URLs e parâmetros de query

Excluindo requisições de rede

Mascarando e bloqueando elementos da página

Filtrando erros e breadcrumbs

Consentimento de rastreamento

O que você pode dizer aos seus usuários