Documentation
ruen

Documentation

Web-SDK overview

The Web-SDK is the browser-side data collection library of the Rockstat platform. It is installed on a site with a single snippet, loads lib.js from your server, and then works on its own: it collects page views, clicks, forms, activity, scrolling, tab switching, and, on request, session recording. The current version is 5.2.

How it is built#

  1. The snippet creates the global rstat4 function and a call queue, then, on configure with the server parameter, connects https://<server>/lib.js. The library lives on your domain, so ad blockers do not touch it.
  2. lib.js initializes on DOMContentLoaded, drains the queue, and enables the trackers from the configuration. The entire API is a single function: rstat4('method', ...arguments).
  3. Trackers generate events, and the library wraps them in a common envelope with the page, session, user, and browser data and sends it to the server.

The size of lib.js is about 100 KB. rrweb for session recording is not included in it and is loaded as a separate bundle only when recording starts.

Features#

Sessions are counted in the browser#

The session number, its type, and advertising marks are determined on the client and arrive at the server ready-made in the sess block. A session begins with any event, is restarted on timeout or on arrival from a new significant source. More.

The visitor identifier, session data, last campaign, userId, and traits are stored in localStorage with the rst4: prefix and are duplicated in cookies with the rst4- prefix. Cookies are set on the site's domain, so the identifier is shared across all subdomains.

HTTPS only#

By default the library does not start on http pages. For local development there is the parameter allowHTTP: true. Encrypting form field values requires a secure context in any case.

Transport#

Events are sent via navigator.sendBeacon, and if it fails — via fetch with keepalive and retries. Requests expecting a response go only via fetch. Library errors are sent with a pixel to the log service. More.

Field value encryption#

Form field values are not collected by default. They can be enabled as plain text or encrypted in the browser with a public RSA key, so that only a server with the private key can decrypt them. More.

Session recording#

Recording via rrweb with all input fields masked by default and CSS classes for excluding parts of the page. The buffer is packed with fflate and sent in batches that fit within the beacon limit. More.

Synchronization with GA4 and Metrica#

The client id of Google Analytics 4 and Yandex Metrica is picked up automatically and added to every message, which makes it possible to reconcile data across systems. More.

The server → browser channel over WebSocket and pixel interception are reserved and are not active in version 5.x.

Browser support#

The build targets current browsers (browserslist: > 0.25%, not dead), but the bundle does not use syntax newer than ES2019 and has been tested on real devices with Android 11–17 and iOS 15–18. Capabilities that a browser lacks (Battery API, Client Hints, storage.estimate) simply do not make it into the data.

Sections#