VANTAGE
Documentation

XRADAR (@xtnd-dynamics/xtnd-radar-sdk)

Repository: XTND-DYNAMICS/xtnd-radar-sdk Package: @xtnd-dynamics/xtnd-radar-sdk on GitHub Packages (2.x) Sends to: the Radar gateway, https://api.radar.vantage.xgi.io (radar-api.md)

1. Overview

XRADAR is the harvester and sender that websites and web apps add, as a dependency like XUI, to report to XVANTAGE. It captures every system event and user interaction on a page and records the visit for replay. It sends everything to the Radar gateway, which stores it in Vantage. Argus shows it under Websites (argus-web.md).

The library's README is the full reference: configuration, every event and the wire format. This page is the summary.

2. Using it

import { startRadar } from '@xtnd-dynamics/xtnd-radar-sdk';

startRadar({
  app: 'evergreenai-www',
  contextAttributes: ['data-chapter'],
  points: [{ on: 'visible', selector: '[data-chapter]', event: 'section_view' }],
});

window.dataLayer.push({ event: 'quote_requested', plan: 'pro' });
gtag('event', 'sign_up', { method: 'email' });

A new site needs three things:

  • its origins in the gateway's ALLOWED_ORIGINS (xtnd-radar-api, wrangler.jsonc);
  • .npmrc with @xtnd-dynamics:registry=https://npm.pkg.github.com;
  • a CI secret XTND_PACKAGES_TOKEN that can read XTND-DYNAMICS packages.

The site keeps no list of its own addresses. Where the gateway refuses (403), XRADAR stops after one batch and keeps nothing.

3. The data layer

The data layer is a TypeScript port of Google's data-layer-helper (Apache 2.0), with the same options, methods and merge rules. window.dataLayer.push and gtag() work as they do with Google Tag Manager, and the two can read one array.

4. What is captured

All of it unless configured off:

  • page life and page views, with every history change;
  • clicks, keys, hovers, scrolling and depth, selection and clipboard;
  • forms field by field, with values (passwords are always asterisks);
  • media;
  • errors, failed resources, CSP violations and the console;
  • every request and WebSocket;
  • navigation timing, Core Web Vitals (each rated when measured), long tasks and resources.

Where Google Tag Manager has a built-in event, XRADAR uses the same keys under xradar.*. Sites add their own named events as tracking points (click, submit, change, input, focus, hover, visible, appear, route, timer).

5. Identity and replay

Every event carries these ids:

  • visitor: the device (localStorage);
  • session: one visit, shared across tabs, ending after 30 minutes without activity;
  • view: one document load;
  • seq: the event's order within the view.

rrweb 2.1.7 records each view in its own chunk of the bundle. The recording is sent as xradar.replay events every 5 seconds: numbered, gzipped and base64-encoded. Each data layer event is marked in the recording, so the replay and the event log line up.

6. On the wire

POST /v1/events/web, sent as text/plain: a simple request with no preflight, which a beacon can also carry. Events go in batches every 5 seconds and are kept until the gateway answers 2xx. When the page is hidden they go as beacons, and the rest wait on the device for the next page. Central keys events by id.