O que o rrweb grava e como funcionam suas opções de privacidade

O que é o rrweb?

A biblioteca open source rrweb, abreviação de "record and replay the web", grava a sessão de um usuário no navegador como JSON estruturado e a reproduz como uma reconstrução assistível da página. O README do projeto a descreve como "a tool for recording and replaying users' interactions on the web." Ela fica em github.com/rrweb-io/rrweb, o repositório foi criado em outubro de 2018, e o código é escrito em TypeScript para que o gravador e o player compartilhem um único formato de evento tipado.

O rrweb é uma biblioteca, não um produto. Ele entrega um gravador que emite eventos e um player que os consome. Para onde esses eventos vão, por quanto tempo você os guarda e quem pode assisti-los é trabalho do seu código. Essa divisão é o motivo de tantas ferramentas comerciais de replay partirem dele, e de o session replay em geral parecer tão parecido de um fornecedor para outro.

O rrweb grava vídeo?

Não. O rrweb grava o estado da página, não os pixels. Ao iniciar, o gravador percorre o DOM e o serializa em uma árvore de nós, cada um com um id numérico único. A documentação de serialização do projeto chama essa saída de "descriptive": scripts são trocados por tags noscript de marcação, valores de inputs são copiados para um atributo value, URLs relativas se tornam absolutas, e folhas de estilo externas são embutidas para que o replay ainda renderize quando o CSS original estiver inacessível.

Depois desse snapshot completo, tudo é diff. O gravador anexa um MutationObserver e um conjunto de listeners, e a documentação do observer lista o que ele captura:

• Mudanças no DOM: criação e remoção de nós, mudanças de atributos e mudanças de texto
• Movimento do mouse
• Interação do mouse: mouse up e down, clique, duplo clique, menu de contexto, focus, blur, e touch start, move e end
• Rolagem da página ou de elementos
• Mudanças no tamanho da janela
• Entrada de dados

Todo evento carrega um timestamp e um type numérico. Os tipos de evento são DomContentLoaded, Load, FullSnapshot, IncrementalSnapshot, Meta e Custom, e os eventos incrementais acrescentam um campo data.source que diz se a mudança foi uma mutação, um movimento do mouse, uma rolagem e assim por diante.

O replayer reconstrói o snapshot dentro de um iframe e aplica os eventos incrementais em ordem. Ele nunca executa o JavaScript da página gravada. A documentação de sandbox do rrweb explica que o atributo sandbox do iframe bloqueia envio de formulários, pop-ups como window.open, e scripts, incluindo handlers inline e URLs javascript:. Como a página é reconstruída a partir de nós, o texto em um replay é texto de verdade, que você pode selecionar. Se você precisar mesmo de um arquivo de vídeo, o monorepo traz o rrvideo, que ele descreve como "a tool for transforming the session recorded by rrweb into a video."

A mesma dependência de MutationObserver define o piso de navegadores do rrweb. O guia afirma que "rrweb does not support IE11 and below because it uses the MutationObserver API".

Quais pacotes do rrweb você deve instalar?

O guia do rrweb recomenda @rrweb/record mais @rrweb/replay para a maioria dos projetos, e @rrweb/all quando você quer um único import para gravação, replay e o packer. A tabela lista os principais pacotes do monorepo como o README de pacotes os descreve. Todos estavam na versão 2.1.6 no npm, publicada em 18 de setembro de 2026, quando esta página foi escrita.

Pacote	O que faz
@rrweb/record	O código de gravação, feito para rodar no seu app ou página de front-end
@rrweb/replay	Reconstrói e reproduz eventos gravados em um iframe
@rrweb/all	Gravação, replay e o packer em um único pacote, sem plugins
rrweb-player	Uma interface de reprodução com pausa, avanço rápido e busca, construída sobre @rrweb/replay
rrweb-snapshot	Serializa o DOM e o reconstrói, a base do evento FullSnapshot
@rrweb/packer	Compressão por evento antes da transferência pela rede
@rrweb/types, @rrweb/utils	Tipos e helpers compartilhados
rrdom, rrdom-nodejs	Um DOM virtual usado para avançar rapidamente as mutações durante o replay, mais uma versão para Node.js
rrvideo	Converte uma gravação em vídeo
rrweb	O pacote original, com gravação e replay juntos

O pacote rrweb original é onde a documentação e o registro discordam. O guia diz: "The rrweb package is deprecated. It still works, but new projects should use @rrweb/record and @rrweb/replay." No npm, o rrweb 2.1.6 não traz nenhum aviso de descontinuação, e ainda é mais baixado que o seu substituto: a API de downloads do npm contou 1,874,214 downloads do rrweb na semana de 15 a 21 de setembro de 2026, contra 498,366 do @rrweb/record. Quem o instala não recebe nenhum aviso. Se você está começando do zero, siga o guia e instale os pacotes separados, porque o rrweb é o pacote que os mantenedores planejam enxugar e remover.

Sob qual licença o rrweb é distribuído?

O rrweb é distribuído sob a MIT License. O arquivo LICENSE do repositório abre com "Copyright (c) 2018 Contributors", e o npm lista MIT para cada pacote acima. A MIT permite usar, modificar e distribuir o rrweb em software comercial de código fechado, desde que você mantenha o aviso de copyright e o de licença.

Essa licença permissiva explica os forks. O pacote de replay da Sentry depende de @sentry/rrweb e @sentry/rrweb-snapshot, segundo o package.json dele no repositório sentry-javascript. O SDK de navegador da PostHog depende de @posthog/rrweb e @posthog/rrweb-record. Os dois fornecedores mantêm a própria cópia, então uma correção no rrweb upstream não chega aos usuários deles até o fornecedor fazer o merge, e os nomes de opções e padrões nos SDKs deles diferem dos do próprio rrweb.

Quais opções do rrweb controlam a privacidade?

O rrweb expõe seus controles de privacidade como opções de record(). Os nomes e padrões abaixo foram copiados da tabela Record Options em guide.md.

Opção	Padrão	O que faz
blockClass	'rr-block'	Elementos a bloquear, como string ou RegExp
blockSelector	null	Um seletor para elementos a bloquear
ignoreClass	'rr-ignore'	Elementos cujos eventos de entrada são ignorados, como string ou RegExp
ignoreSelector	null	Um seletor para elementos a ignorar
maskTextClass	'rr-mask'	Elementos cujo texto é mascarado, como string ou RegExp
maskTextSelector	null	Um seletor para elementos a mascarar
maskAllInputs	false	Mascara todo o conteúdo de inputs como *
maskInputOptions	{ password: true }	Mascara alguns tipos de input
maskInputFn	nenhum	Lógica personalizada para mascarar o conteúdo de inputs
maskTextFn	nenhum	Lógica personalizada para mascarar conteúdo de texto
ignoreCSSAttributes	null	Um array de atributos CSS a ignorar
recordCanvas	false	Se deve gravar elementos canvas
recordCrossOriginIframes	false	Se deve gravar iframes cross-origin, o que exige o rrweb injetado em cada frame filho

As três classes se comportam de forma diferente, e as pessoas as confundem. A seção de privacidade do guia explica. Um elemento com .rr-block "will not be recorded. Instead, it will replay as a placeholder with the same dimension." Um elemento com .rr-ignore "will not record its input events." E "all text of elements with the class name .rr-mask and their children will be masked." Bloquear remove o elemento. Ignorar mantém o elemento mas descarta o que o usuário digita nele. Mascarar mantém o layout e substitui os caracteres.

Três classes de privacidade, três efeitos

blockClassRemove o elemento, reproduz um espaço reservado

ignoreClassMantém o elemento, descarta seus eventos de entrada

maskTextClassMantém o elemento, substitui seu texto

O que o rrweb mascara por padrão?

O rrweb mascara uma coisa por padrão: o valor de campos de senha. O guia diz isso em uma linha, "input[type="password"] will be masked by default", e o código-fonte do gravador confirma: quando maskAllInputs não é true e você não passa maskInputOptions, o gravador recorre a { password: true }.

Todo o resto, incluindo campos de email, telefone, endereço e texto livre, sai do navegador do jeito que foi digitado, a menos que você configure mais. maskInputOptions aceita estas chaves, de MaskInputOptions nos tipos do rrweb-snapshot: color, date, datetime-local, email, month, number, range, search, tel, text, time, url, week, textarea, select e password. Definir maskAllInputs: true liga todas elas de uma vez.

Não existe opção para desmascarar um filho dentro de um pai mascarado. O rrweb não tem configuração de unmask ou unblock, então os fornecedores que oferecem isso o construíram no próprio fork. Se você compara bibliotecas pelos padrões, nossa análise de onde os padrões de redação de PII deixam dados expostos coloca o rrweb ao lado da Sentry e do Clarity.

Uma regra prática para uma instalação nova: comece com maskAllInputs: true, acrescente maskTextClass ou maskTextSelector a qualquer contêiner que renderize dados de conta, e coloque blockClass em widgets de terceiros que você não tem motivo para ver.

Como reduzir o tamanho de uma gravação do rrweb?

A receita de armazenamento do rrweb lista três estratégias: bloquear elementos do DOM que emitem muitos eventos, usar a configuração sampling para descartar eventos, e comprimir ou deduplicar o que você guarda.

A opção sampling reduz eventos dentro de uma gravação em vez de escolher quais sessões gravar. As chaves dela vêm do tipo SamplingStrategy. mousemove aceita false ou um limite de throttle, mouseInteraction aceita false ou um mapa por interação, scroll e media aceitam limites de throttle, input aceita 'all' ou 'last', e canvas aceita 'all' ou uma taxa de snapshots entre 1 e 60 por segundo. O exemplo da receita define scroll: 150 com o comentário "do not emit twice in 150ms" e input: 'last' para manter só o valor final de uma sequência digitada. Isso é amostragem por evento, uma alavanca diferente da taxa de amostragem do session replay que os fornecedores expõem.

Para compressão, o @rrweb/packer fornece uma função pack que você passa como packFn, e o unpack correspondente vai para o replayer como unpackFn. A receita observa que comprimir a sessão inteira no backend costuma ser melhor que a compressão por evento. slimDOMOptions remove partes do DOM como scripts e comentários, e checkoutEveryNth ou checkoutEveryNms tiram um novo snapshot completo em intervalos, o que permite manter só o último trecho de uma sessão quando um erro dispara. O guia avisa que isso é aproximado: com checkoutEveryNth: 200 você acaba enviando "the last 200 to 400 events".

O custo de gravação também é uma questão de velocidade da página. Os números publicados sobre o que um gravador acrescenta ao tamanho do bundle e ao tempo da main thread estão reunidos em quanto o session replay deixa um site mais lento.

Perguntas frequentes

O rrweb é gratuito para uso comercial?

Sim. O rrweb tem licença MIT, então você pode usá-lo e modificá-lo em software comercial de código fechado. Você precisa manter o aviso de copyright e o texto da licença junto com o código que distribui.

O rrweb captura o que os usuários digitam?

Sim, a menos que você mascare. O rrweb grava eventos de input e mascara apenas input[type="password"] por padrão. Defina maskAllInputs: true ou liste tipos específicos de input em maskInputOptions para mascarar mais.

Qual é a diferença entre blockClass e maskTextClass no rrweb?

blockClass (padrão 'rr-block') remove um elemento da gravação e reproduz um placeholder do mesmo tamanho. maskTextClass (padrão 'rr-mask') mantém o elemento e substitui o texto dentro dele e dos filhos.

Devo instalar rrweb ou @rrweb/record?

Instale @rrweb/record para gravação e @rrweb/replay para reprodução. O guia do rrweb chama o pacote combinado rrweb de descontinuado, mesmo que o npm não mostre nenhum aviso de descontinuação nele.

O rrweb consegue gravar canvas e iframes?

Sim, e os dois vêm desligados por padrão. recordCanvas: false e recordCrossOriginIframes: false são os padrões, e iframes cross-origin também exigem o rrweb injetado em cada frame filho.

Quais navegadores o rrweb suporta?

O rrweb suporta navegadores que implementam MutationObserver. O guia dele afirma que não suporta o Internet Explorer 11 e versões anteriores.

Como a opção sampling do rrweb reduz o tamanho de uma gravação?

A configuração sampling reduz os eventos dentro de uma sessão em vez de descartar gravações inteiras. scroll e media aceitam um limite de throttle, mousemove também, e input aceita 'last' para manter apenas o último valor de uma sequência digitada. O exemplo da receita de armazenamento define scroll: 150, de modo que uma rolagem só é emitida uma vez a cada 150 milissegundos.

É possível converter uma gravação do rrweb em um arquivo de vídeo?

O monorepo do rrweb inclui o rrvideo, descrito como "a tool for transforming the session recorded by rrweb into a video." Isso transforma uma gravação feita de um snapshot do DOM e mutações em um arquivo de vídeo real. O rrweb em si continua sem gravar vídeo; o rrvideo é uma etapa de conversão separada, executada depois.

Quantos downloads o pacote rrweb descontinuado tem em comparação com @rrweb/record?

Na semana de 15 a 21 de setembro de 2026, o npm contou 1,874,214 downloads do pacote rrweb contra 498,366 do @rrweb/record. O guia chama o rrweb de descontinuado, mas o npm não mostra nenhum aviso de descontinuação nele, então instalá-lo não mostra aviso nenhum. O pacote mais antigo continua sendo baixado muito mais que seu substituto.

O Sentry e o PostHog usam o pacote rrweb original diretamente?

O Sentry e o PostHog mantêm cada um seu próprio fork em vez de depender do rrweb diretamente. O pacote de replay do Sentry depende de @sentry/rrweb e @sentry/rrweb-snapshot, e o SDK de navegador do PostHog depende de @posthog/rrweb e @posthog/rrweb-record. Uma correção no rrweb original só chega aos usuários deles quando o fornecedor a incorpora, e os nomes de opções e padrões de cada fork diferem dos do rrweb.