Cosa registra rrweb e come funzionano le sue opzioni di privacy

Che cos'è rrweb?

La libreria open source rrweb, abbreviazione di "record and replay the web", registra la sessione di un utente nel browser come JSON strutturato e la riproduce come una ricostruzione guardabile della pagina. Il README del progetto la descrive come "a tool for recording and replaying users' interactions on the web", cioè uno strumento per registrare e riprodurre le interazioni degli utenti sul web. Si trova su github.com/rrweb-io/rrweb, il repository è stato creato a ottobre 2018 e il codice è scritto in TypeScript, quindi il recorder e il player condividono un unico formato di eventi tipizzato.

rrweb è una libreria, non un prodotto. Ti dà un recorder che emette eventi e un player che li consuma. Dove finiscono quegli eventi, per quanto tempo li conservi e chi può guardarli sono compiti del tuo codice. Per questo tanti strumenti commerciali di replay partono da qui, ed è anche il motivo per cui la session replay in generale è così simile da un fornitore all'altro.

rrweb registra video?

No. rrweb registra lo stato della pagina, non i suoi pixel. All'avvio il recorder percorre il DOM e lo serializza in un albero di nodi, ognuno con un id numerico univoco. La documentazione sulla serializzazione del progetto definisce questo output "descrittivo". Gli script vengono sostituiti da tag noscript segnaposto, i valori degli input vengono copiati in un attributo value, gli URL relativi diventano assoluti e i fogli di stile esterni vengono incorporati, così la replay si vede anche quando il CSS originale non è raggiungibile.

Dopo questo snapshot completo, tutto il resto è un diff. Il recorder collega un MutationObserver e una serie di listener, e la documentazione dell'observer elenca ciò che cattura:

• Modifiche al DOM: creazione ed eliminazione di nodi, cambi di attributi e cambi di testo
• Movimento del mouse
• Interazioni del mouse: pressione e rilascio dei tasti, click, doppio click, menu contestuale, focus, blur e inizio, movimento e fine del tocco
• Scorrimento della pagina o di un elemento
• Cambi di dimensione della finestra
• Input

Ogni evento porta con sé un timestamp e un type numerico. I tipi di evento sono DomContentLoaded, Load, FullSnapshot, IncrementalSnapshot, Meta e Custom, e gli eventi incrementali aggiungono un campo data.source che indica se la modifica è stata una mutazione, un movimento del mouse, uno scorrimento e così via.

Il replayer ricostruisce lo snapshot dentro un iframe e applica gli eventi incrementali in ordine. Non esegue mai il JavaScript della pagina registrata. La documentazione sulla sandbox di rrweb spiega che l'attributo sandbox dell'iframe blocca l'invio dei form, i pop-up come window.open e gli script, compresi gli handler inline e gli URL javascript:. Poiché la pagina viene ricostruita a partire dai nodi, il testo in una replay è testo vero che puoi selezionare. Se ti serve davvero un file video, il monorepo include rrvideo, che descrive come "a tool for transforming the session recorded by rrweb into a video", cioè uno strumento che trasforma in video la sessione registrata da rrweb.

La stessa dipendenza da MutationObserver stabilisce il limite minimo dei browser supportati. La guida afferma che "rrweb does not support IE11 and below because it uses the MutationObserver API", cioè che rrweb non supporta IE11 e versioni precedenti perché usa l'API MutationObserver.

Quali pacchetti rrweb dovresti installare?

La guida di rrweb consiglia @rrweb/record più @rrweb/replay per la maggior parte dei progetti, e @rrweb/all quando vuoi un unico import per registrazione, replay e packer. La tabella elenca i pacchetti principali del monorepo così come li descrive il README dei pacchetti. Al momento della stesura di questa pagina, ognuno era alla versione 2.1.6 su npm, pubblicata il 18 settembre 2026.

Pacchetto	Cosa fa
@rrweb/record	Il codice di registrazione, pensato per girare nella tua app front-end o nella tua pagina
@rrweb/replay	Ricostruisce e riproduce in un iframe gli eventi registrati
@rrweb/all	Registrazione, replay e packer in un solo pacchetto, senza plugin
rrweb-player	Un'interfaccia di riproduzione con pausa, avanzamento veloce e ricerca nel tempo, costruita su @rrweb/replay
rrweb-snapshot	Serializza il DOM e lo ricostruisce, è la base dell'evento FullSnapshot
@rrweb/packer	Compressione evento per evento prima del trasferimento in rete
@rrweb/types, @rrweb/utils	Tipi e funzioni di supporto condivisi
rrdom, rrdom-nodejs	Un DOM virtuale usato per avanzare velocemente le mutazioni durante la replay, più una versione per Node.js
rrvideo	Converte una registrazione in video
rrweb	Il pacchetto originale con registrazione e replay insieme

Il pacchetto rrweb originale è il punto in cui documentazione e registro non concordano. La guida dice: "The rrweb package is deprecated. It still works, but new projects should use @rrweb/record and @rrweb/replay." In italiano, il pacchetto rrweb è deprecato, funziona ancora, ma i nuovi progetti dovrebbero usare @rrweb/record e @rrweb/replay. Su npm, però, rrweb 2.1.6 non riporta alcun avviso di deprecazione e scarica ancora più del suo sostituto. L'API dei download di npm ha contato 1.874.214 download di rrweb nella settimana dal 15 al 21 settembre 2026, contro 498.366 di @rrweb/record. Chi lo installa non riceve nessun avviso. Se parti da zero, segui la guida e installa i pacchetti separati, perché il pacchetto rrweb è quello che i maintainer prevedono di snellire e poi rimuovere.

Con quale licenza è rilasciato rrweb?

rrweb è rilasciato con licenza MIT. Il file LICENSE del repository si apre con "Copyright (c) 2018 Contributors", e npm indica MIT per ciascuno dei pacchetti qui sopra. La licenza MIT ti permette di usare, modificare e distribuire rrweb in software commerciale a codice chiuso, a patto di mantenere l'avviso di copyright e di licenza.

Questa licenza permissiva spiega i fork. Il pacchetto replay di Sentry dipende da @sentry/rrweb e @sentry/rrweb-snapshot, secondo il suo package.json nel repository sentry-javascript. L'SDK browser di PostHog dipende da @posthog/rrweb e @posthog/rrweb-record. Entrambi i fornitori mantengono una propria copia, quindi una correzione nel rrweb originale non arriva ai loro utenti finché il fornitore non la integra, e i nomi delle opzioni e i valori predefiniti nei loro SDK differiscono da quelli di rrweb.

Quali opzioni di rrweb controllano la privacy?

rrweb espone i controlli sulla privacy come opzioni di record(). I nomi e i valori predefiniti qui sotto sono copiati dalla tabella Record Options di guide.md.

Opzione	Predefinito	Cosa fa
blockClass	'rr-block'	Elementi da bloccare, come stringa o RegExp
blockSelector	null	Un selettore per gli elementi da bloccare
ignoreClass	'rr-ignore'	Elementi di cui vengono ignorati gli eventi di input, come stringa o RegExp
ignoreSelector	null	Un selettore per gli elementi da ignorare
maskTextClass	'rr-mask'	Elementi il cui testo viene mascherato, come stringa o RegExp
maskTextSelector	null	Un selettore per gli elementi da mascherare
maskAllInputs	false	Maschera tutto il contenuto degli input con *
maskInputOptions	{ password: true }	Maschera alcuni tipi di input
maskInputFn	nessuno	Logica personalizzata per mascherare il contenuto degli input
maskTextFn	nessuno	Logica personalizzata per mascherare il contenuto testuale
ignoreCSSAttributes	null	Un array di attributi CSS da ignorare
recordCanvas	false	Se registrare o meno gli elementi canvas
recordCrossOriginIframes	false	Se registrare o meno gli iframe cross-origin, cosa che richiede di iniettare rrweb in ogni frame figlio

Le tre classi si comportano in modo diverso e spesso si confondono. La sezione sulla privacy della guida lo spiega bene. Un elemento con .rr-block "non verrà registrato. Verrà invece riprodotto come un segnaposto con le stesse dimensioni". Un elemento con .rr-ignore "non registrerà i suoi eventi di input". E "tutto il testo degli elementi con il nome di classe .rr-mask e dei loro figli verrà mascherato". Bloccare rimuove l'elemento. Ignorare mantiene l'elemento ma scarta ciò che l'utente scrive al suo interno. Mascherare mantiene il layout e sostituisce i caratteri.

Tre classi per la privacy, tre effetti

blockClassRimuove l'elemento, riproduce un segnaposto

ignoreClassMantiene l'elemento, scarta i suoi eventi di input

maskTextClassMantiene l'elemento, sostituisce il suo testo

Cosa maschera rrweb per impostazione predefinita?

Per impostazione predefinita rrweb maschera una sola cosa: il valore dei campi password. La guida lo dice in una riga, "input[type="password"] verrà mascherato per impostazione predefinita", e il codice sorgente del recorder lo conferma: quando maskAllInputs non è true e non passi nessun maskInputOptions, il recorder ripiega su { password: true }.

Tutto il resto, compresi i campi email, telefono, indirizzo e testo libero, lascia il browser così come è stato digitato, a meno che tu non configuri qualcosa in più. maskInputOptions accetta queste chiavi, tratte da MaskInputOptions nei tipi di rrweb-snapshot: color, date, datetime-local, email, month, number, range, search, tel, text, time, url, week, textarea, select e password. Impostando maskAllInputs: true le attivi tutte insieme.

Non esiste nessuna opzione per smascherare un figlio dentro un genitore mascherato. rrweb non ha impostazioni unmask o unblock, quindi i fornitori che le offrono le hanno integrate nel proprio fork. Se confronti le librerie in base ai valori predefiniti, la nostra analisi su dove i default di redazione dei PII lasciano i dati esposti mette rrweb accanto a Sentry e Clarity.

Una regola pratica per una nuova installazione: parti con maskAllInputs: true, aggiungi maskTextClass o maskTextSelector a ogni contenitore che mostra dati dell'account, e metti blockClass sui widget di terze parti che non hai alcun motivo di vedere.

Come si riduce la dimensione di una registrazione rrweb?

La ricetta di rrweb per lo storage elenca tre strategie: bloccare gli elementi del DOM che emettono molti eventi, usare la configurazione sampling per scartare eventi, e comprimere o deduplicare ciò che conservi.

L'opzione sampling sfoltisce gli eventi dentro una registrazione, invece di scegliere quali sessioni registrare. Le sue chiavi arrivano dal tipo SamplingStrategy. mousemove accetta false o una soglia di throttle, mouseInteraction accetta false o una mappa per singola interazione, scroll e media accettano soglie di throttle, input accetta 'all' o 'last', e canvas accetta 'all' o una frequenza di snapshot tra 1 e 60 al secondo. L'esempio della ricetta imposta scroll: 150 con il commento "do not emit twice in 150ms" (non emettere due volte in 150ms) e input: 'last' per tenere solo il valore finale di una sequenza digitata. Questo è un campionamento a livello di evento, una leva diversa dal tasso di campionamento delle session replay offerto dai fornitori.

Per la compressione, @rrweb/packer fornisce una funzione pack da passare come packFn, mentre il corrispondente unpack va al replayer come unpackFn. La ricetta osserva che comprimere l'intera sessione sul backend di solito dà risultati migliori della compressione evento per evento. slimDOMOptions elimina parti del DOM come script e commenti, mentre checkoutEveryNth o checkoutEveryNms acquisiscono a intervalli un nuovo snapshot completo, il che ti permette di conservare solo l'ultimo tratto di una sessione quando scatta un errore. La guida avverte che il risultato è approssimativo: con checkoutEveryNth: 200 finisci per inviare "gli ultimi 200-400 eventi".

Il costo della registrazione è anche una questione di velocità della pagina. I numeri pubblicati su ciò che un recorder aggiunge alla dimensione del bundle e al tempo del main thread sono raccolti in quanto la session replay rallenta un sito.

Domande frequenti

rrweb è gratuito per l'uso commerciale?

Sì. rrweb è distribuito con licenza MIT, quindi puoi usarlo e modificarlo anche in software commerciale a codice chiuso. Devi conservare l'avviso di copyright e il testo della licenza insieme al codice che pubblichi.

rrweb registra quello che scrivono gli utenti?

Sì, a meno che tu non lo mascheri. rrweb registra gli eventi input e per impostazione predefinita maschera solo input[type="password"]. Imposta maskAllInputs: true oppure elenca tipi di input specifici in maskInputOptions per mascherarne di più.

Che differenza c'è tra blockClass e maskTextClass in rrweb?

blockClass (predefinito 'rr-block') rimuove un elemento dalla registrazione e nella riproduzione mostra un segnaposto della stessa dimensione. maskTextClass (predefinito 'rr-mask') mantiene l'elemento e sostituisce il testo al suo interno e quello dei suoi figli.

Devo installare rrweb o @rrweb/record?

Installa @rrweb/record per la registrazione e @rrweb/replay per la riproduzione. La guida di rrweb definisce deprecato il pacchetto combinato rrweb, anche se npm non mostra alcun avviso di deprecazione.

rrweb può registrare canvas e iframe?

Sì, ma entrambi sono disattivati per impostazione predefinita. I valori predefiniti sono recordCanvas: false e recordCrossOriginIframes: false, e per gli iframe cross-origin devi anche inserire rrweb in ogni frame figlio.

Quali browser supporta rrweb?

rrweb supporta i browser che implementano MutationObserver. La sua guida precisa che Internet Explorer 11 e le versioni precedenti non sono supportati.

Come fa l'opzione sampling di rrweb a ridurre le dimensioni della registrazione?

La configurazione sampling sfoltisce gli eventi all'interno di una sessione, invece di scartare intere registrazioni. scroll e media accettano una soglia di throttle, lo stesso vale per mousemove, mentre input accetta 'last' per conservare solo il valore finale di una sequenza digitata. L'esempio della guida allo storage imposta scroll: 150, così lo scroll genera un evento solo ogni 150 millisecondi.

Si può convertire una registrazione rrweb in un file video?

Il monorepo di rrweb include rrvideo, descritto come "a tool for transforming the session recorded by rrweb into a video." Trasforma una registrazione fatta di uno snapshot del DOM e di mutazioni in un vero file video. rrweb di per sé non registra video: rrvideo è un passaggio di conversione separato, da eseguire dopo.

Quanti download ha il pacchetto rrweb deprecato rispetto a @rrweb/record?

Nella settimana dal 15 al 21 settembre 2026, npm ha contato 1.874.214 download del pacchetto rrweb contro 498.366 di @rrweb/record. La guida definisce rrweb deprecato, ma npm non mostra alcun avviso di deprecazione, quindi installandolo non compare nessun avviso. Il pacchetto più vecchio viene ancora scaricato molto più del suo sostituto.

Sentry e PostHog usano direttamente il pacchetto rrweb originale?

Sentry e PostHog mantengono ciascuno un proprio fork invece di dipendere direttamente da rrweb. Il pacchetto replay di Sentry dipende da @sentry/rrweb e @sentry/rrweb-snapshot, mentre l'SDK browser di PostHog dipende da @posthog/rrweb e @posthog/rrweb-record. Una correzione nel rrweb originale arriva ai loro utenti solo quando il fornitore la integra, e i nomi delle opzioni e i valori predefiniti di ogni fork sono diversi da quelli di rrweb.