Privacy and data#

Docs index - package README

The SDK captures interactions, not values. The boundary is deliberately broad and enforced at the source of capture, not at the ingest endpoint.

What is masked by default#

  • Inputs are never read. Form fields (<input>, <textarea>, <select>) and any contenteditable region are sensitive; their values do not leave the browser.
  • Form submits carry metadata only. Structure (form_id, form_name, action, method, field_names[], field_types[], field_count), never values.
  • Every form-entry element is sensitive by tag, not by type. Every <input> (regardless of its type), <textarea>, and <select> is treated as sensitive, so no text or value is read from it. There is no type allowlist: a plain text or number field is masked exactly like a password field. As an extra layer, the $change interaction event skips password, file, and hidden inputs entirely.
  • Click fingerprints on sensitive targets carry no text. A form field's fingerprint never includes its value or its text. Its labels (aria_label, from aria-labelledby, aria-label, its <label>, placeholder or name, and title) are text the page author wrote, so they are kept and name the field. A label referenced through aria-labelledby that sits inside a sensitive subtree yields nothing.
  • Container text never leaks child input values. When fingerprinting a non-sensitive container, the visible-text walker skips any sensitive descendant, so a card's innerText cannot include a child input's value.

What text is sent#

Masking keeps what visitors type out. Text the page itself shows can still be sent, and some of it can be personal:

  • A click sends the visible text of the element it acts on, up to 120 characters, as fingerprint.text, plus its accessible name and title (each up to 120 characters). That element can be a whole clickable card or list row, so on a page listing orders, people or messages, the text can include a name or an email address. The value of a form field is never sent.
  • A page view sends the page's title and its meta description (up to 300 characters). On a profile or account page either can name the person.
  • A link click sends the link's URL, with sensitive query values redacted as described under URLs and query strings, and for a download, the file name.

So mark rows, cards or regions that show personal data with data-revu-mask, which removes their text and labels, and keep personal data out of page titles and meta descriptions. Where that is not possible, remove the field in beforeSend.

data-revu-mask#

Add the attribute to any element (or any ancestor) to mark its subtree sensitive. The SDK honors it everywhere a sensitive element would be honored:

  • Click fingerprints inside the subtree redact text, aria_label, and title.
  • Form submits inside the subtree skip field-name capture entirely.
  • Container text extraction skips the subtree.
<!-- Mask a PII summary card -->
<aside data-revu-mask>
  <h3>Account balance</h3>
  <p>$1,234.56</p>
</aside>

<!-- Mask one field on a form (or the whole form) -->
<form data-revu-mask>
  <input name="ssn" type="text" />
</form>

The attribute also crosses Shadow DOM boundaries: a data-revu-mask on a custom element's host applies to every element in its shadow tree.

data-revu-mask still emits the interaction, just with its labels redacted. When you want no event at all for a region - not even a redacted one - use the autocaptureDenySelectors config option instead; it suppresses the event entirely, including any file-download / outbound-link / rage events derived from the click.

URLs and query strings#

Captured URLs (the $pageview url, the referrer, and $outbound_link / $file_download targets) routinely carry secrets in their query string or fragment: a password-reset token, an email address in ?email=, an OAuth/OIDC implicit-flow #access_token=.... The SDK redacts the values of sensitive parameters at the source - in both the query and the fragment - replacing them with [redacted] before the event is built.

The redaction is by parameter name, not wholesale, because the server derives campaign attribution (UTM, click ids) from the captured URL. So utm_source, utm_medium, gclid, fbclid, and other attribution and benign params are preserved, while token, password, secret, auth, api_key, session, email, and similar credential / PII keys (matched case-insensitively, including _/--delimited variants like access_token and user_email) have their values stripped.

This is redaction at source, not a toggle: there is no option to capture raw query values. The page identity (screen / path) is the pathname plus hash and never includes the query string; the hash itself is run through the same redaction, so a credential-bearing fragment (an OAuth implicit-flow #access_token=... landing) never lands in screen or path. Hash-router routes (#/pricing) and anchors (#section) are preserved unchanged.

What the SDK does not parse client-side#

By design, several categories of work live server-side:

  • URL query parsing. Campaign attribution (UTM, click ids) is derived server-side from the $pageview URL on the first event of each session. The SDK does not ship a parser for these.
  • User agent parsing. The SDK ships the raw navigator.userAgent string; the server parses it into os, browser, and device. UA strings drift; the server can iterate on the parser without a customer redeploy.
  • IP-based geo. The SDK never reads or sends client geolocation. The server enriches based on the request's IP, which is also more durable than client APIs and never requires a permission prompt. REVU derives country, city and network from the IP when an event arrives, using local databases, so the IP is not sent to any outside service. The IP itself is kept for 30 days, for crawler verification and troubleshooting, then cleared. The events and the derived fields stay.

This is a hard boundary, not a temporary state. Anything that would require shipping a dictionary, an algorithm, or a model to the browser stays server-side. That is what keeps the bundle at around 10 kilobytes.

Environment signals#

Alongside the interaction itself, every event carries a small set of environment signals the browser reports about itself. They describe the client, never the person using it.

  • User-Agent Client Hints, low-entropy set only. ua_brands, ua_mobile, and ua_platform are read from navigator.userAgentData where the browser exposes it (Chromium and secure contexts; absent on Safari, Firefox, and plain-http pages, and simply omitted there). These are the same three values the browser already sends on every request as Sec-CH-UA headers, so they add no fingerprinting surface over the request itself. The SDK does not call getHighEntropyValues(): the full version list, platform version, and device model are fingerprinting-relevant and are never requested.
  • languages. The browser's ordered language list, the same information it already sends as Accept-Language.
  • navigation_type. Whether this page load was a fresh navigation, a reload, a back-forward restore, or a prerender, so a genuine landing can be told apart from a repeat view.
  • webdriver. Stamped only when the browser reports that it is being driven by automation, and omitted otherwise.

None of these read storage, ask for a permission, or probe the device. They exist so automated traffic can be separated from real visits, which keeps your numbers honest.

Capture is gated on a per-category consent state the host controls at runtime, so a cookie banner routes its choices through the SDK rather than wrapping every call in a check. The simplest form is the binary master switch:

revu.optOut();        // stop all capture (reject / withdraw consent)
revu.optIn();         // resume capture (accept)
revu.hasOptedOut();   // -> boolean

For per-category control, use the consent API. There are three categories - analytics, marketing, and functional - each "granted" or "denied":

revu.consent.set({ analytics: "granted", marketing: "denied" });
revu.consent.get();
// -> { analytics: "granted", marketing: "denied", functional: "granted" }

Only analytics gates capture: while it is denied, every interaction (autocapture, pageviews, custom capture() calls, identity events) is suppressed before an event is built, so nothing leaves the browser. optOut() / optIn() are aliases for denying / granting it. marketing and functional are declarative: the SDK does not act on them, it stamps the full state on every event (context.consent) so the server honors the visitor's choices on the destinations downstream.

The choice is persisted in the same first-party store as identity, so a reload honors it without re-prompting. A binary opt-out persisted by an earlier SDK version is read on the first load after upgrade, so a prior reject keeps being honored.

Changing consent does not clear identity: granting again resumes the same visitor. That is the right default for a consent toggle (a user who re-accepts is the same person). Call revu.reset() if you instead want a clean break to a new anonymous visitor.

For per-element opt-out, use data-revu-mask on the subtree.

Global Privacy Control#

Some browsers advertise a Global Privacy Control signal (navigator.globalPrivacyControl). The SDK always stamps it on events as context.gpc so the server sees it. With honorGpc: true (off by default), a GPC signal also defaults the analytics category to denied, unless the visitor has already made an explicit choice through your banner - an explicit choice always wins. The default is off because whether GPC legally requires suppression depends on your jurisdiction (it is a valid opt-out signal under CCPA/CPRA, but not the consent mechanism under GDPR), so the decision is left to you.

Dropping locally-buffered events#

optOut() stops new capture but leaves events already queued under prior consent to flush. To also discard any locally-buffered events and stored ids for a user who withdraws consent, use the local-data plugin with an npm install:

import localData from "@revu-ai/core/local-data";

const data = localData();
revu.init({ apiKey: "revu_pk_...", plugins: [data] });

// When the visitor withdraws consent:
revu.optOut();
data.clear();

It drops the queued events in memory and in storage, removes the ids and attribution records, and keeps revu_consent so the opt-out survives the next load.

With the <script> install, which does not include the plugin, clear the durable queue and identity stores yourself:

revu.optOut();
// Keep `revu_consent` so the opt-out itself is honored on the next load.
const keys = [
  "revu_anonymous_id",
  "revu_user_id",
  "revu_session_id",
  "revu_session_last_seen",
  "revu_session_started_at",
  "revu_attribution_first",
  "revu_attribution_last",
];
try {
  // The queue is an index (`revu_event_queue`) plus numbered chunks
  // (`revu_event_queue.0`, `.1`, ...) that hold the events themselves.
  // Removing the index alone would leave every buffered event behind.
  for (let i = localStorage.length - 1; i >= 0; i--) {
    const key = localStorage.key(i);
    if (key && key.startsWith("revu_event_queue")) localStorage.removeItem(key);
  }
  for (const key of keys) localStorage.removeItem(key);
} catch {}
for (const key of keys) {
  // If you set `cookieDomain`, add `; Domain=<that value>` here too.
  document.cookie = `${key}=; Path=/; Max-Age=0; SameSite=Lax`;
}

This clears what is stored. Events the open page already holds in memory still flush as described above.