Configuration#

Docs index - package README

Every option passed to revu.init({ ... }) is optional except apiKey. Defaults are tuned to be the right answer for a typical product surface.

Options#

sessionTimeoutMs: sessions are engagement, not page visits#

This is the single most common point of confusion, so the default is worth stating explicitly.

A session is a span of continuous engagement with your product, not a single page visit. With the default sessionTimeoutMs of 30 minutes, the SDK continues the previous session whenever the gap since the last recorded activity is under 30 minutes. That means all of the following stay inside one session:

• A page reload (refresh).
• An SPA route change.
• Opening a second tab on the same site.
• Closing the tab and reopening it within 30 minutes.
• Coming back from a 28-minute background while reading something else.

The session only rotates (gets a fresh session_id) once the gap since the last recorded activity exceeds the timeout. 30 minutes is the conventional default in behavioral analytics; it is the value behind "average session duration" numbers you have seen elsewhere.

If you want every page load to start a new session (rarely the right choice, but available for parity with very old per-load instrumentation patterns), set:

revu.init({ apiKey: "...", sessionTimeoutMs: 0 });

If your product is more like a content site where each visit really is a distinct intent, shorten the window:

revu.init({ apiKey: "...", sessionTimeoutMs: 10 * 60 * 1000 }); // 10 minutes

The session id is persisted (per persistentStorage) along with a last_seen timestamp; on every event the SDK touches last_seen (throttled so a chatty page does not pay a write per event), and the next construction reads both to decide whether to continue or rotate.

Consent and GPC#

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. There are three categories:

• analytics - the SDK's own bucket. This is the only category that gates capture: while it is "denied", every interaction is suppressed before an event is built, so nothing leaves the browser.
• marketing and functional - declarative. The SDK does not act on them; it stamps the full consent state on every event (context.consent) so the server honors the visitor's choices on the destinations downstream.

// Map a cookie banner's result straight through:
revu.consent.set({ analytics: "granted", marketing: "denied" });

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

revu.optOut() / revu.optIn() are aliases for denying / granting the analytics category, so existing wiring keeps working. The state is persisted in the same first-party store as identity, and a pre-existing binary opt-out from an earlier SDK version is honored on upgrade.

Global Privacy Control. Some browsers advertise a GPC signal (navigator.globalPrivacyControl). The SDK always stamps it on events as context.gpc so the server sees it. With honorGpc: true, a GPC signal also defaults the analytics category to denied - unless the visitor has already made an explicit choice through your banner, which always wins. The default is honorGpc: false: whether GPC legally requires suppression depends on your jurisdiction, so the decision is left to you.

revu.init({ apiKey: "...", honorGpc: true }); // auto-deny on a GPC signal

beforeSend: enrich, redact, or drop#

beforeSend runs once per event, after the SDK has built the full event but before it is queued. It is the place to add host context the SDK cannot know, strip a field, or filter events you never want to store.

revu.init({
  apiKey: "...",
  beforeSend(event) {
    // Enrich: attach something only the host knows.
    event.properties.tenant_plan = window.__APP__.plan;

    // Redact: drop a field you do not want stored.
    delete event.properties.some_internal_id;

    // Drop: filter noisy events entirely.
    if (event.event_type === "$autocapture" && event.screen === "/debug") {
      return null;
    }

    return event; // send it (mutated in place, or return a new object)
  },
});

• Return the event (the same one mutated, or a replacement object) to send it; return null or false to drop it; return nothing to send it unchanged.
• It is fail-open: if the hook throws, the original event is sent unchanged (and the error is logged when debug is on), so a bug in the hook never silently deletes analytics.
• The returned event's properties are re-sanitized to a JSON-safe shape, so the hook cannot poison the durable queue with an unserializable value.
• It does not run for events that were never built - capture suppressed by consent or sampling never reaches beforeSend.

Autocapture selector filtering#

autocaptureDenySelectors and autocaptureAllowSelectors scope which elements element-targeted autocapture (clicks, right-clicks, form-control changes) observes. Matching walks ancestors, so a selector on a container also covers the elements inside it.

revu.init({
  apiKey: "...",
  // Never autocapture anything inside these:
  autocaptureDenySelectors: [".sensitive-widget", "[data-no-track]"],
});

// Or capture ONLY inside an explicit set (everything else is ignored):
revu.init({
  apiKey: "...",
  autocaptureAllowSelectors: ["main", ".tracked"],
});

• Deny wins. An element matching a deny selector is never captured, even if it also matches an allow selector.
• A deny selector suppresses the event entirely, including the file-download, outbound-link, and rage-click events derived from a click. This is the difference from data-revu-mask, which still emits the event but redacts its fingerprint - use a deny selector when you want no event at all, and data-revu-mask when you want the interaction recorded without its labels. An invalid selector is ignored, not thrown.