Skip to content

Telemetry

Telemetry is what the SDK reports while it runs: its log, one entry per step it takes, and the input it captures. On the staging and test packages your page receives both: the log through onLog, and the captured input through an integration of your own. Your code decides where they go; the SDK sends neither to DEA.

Staging and test packages only. The production package writes no log and refuses every integration, so nothing on this page reaches a page you release.

When to use it

  • Watch what the SDK does while you integrate, in your own log panel or logging service
  • Record the raw input of test sessions for your own QA or analysis

Prerequisites

  • The staging package is installed — see Verify your setup. The test package works the same way and also logs DEBUG
  • Where you set requireConsent, your testers agreed — see User Consent. Nothing is captured before they do

Usage

Receive the log

Pass onLog to init. The SDK calls it with every entry, and still writes each entry to the console.

import { init } from '@dea/sdk';

init({
  appId: 'YOUR_APP_ID',
  appKey: 'YOUR_APP_KEY',
  onLog: (entry) => myLogger.log(entry.severityText, entry.eventName, entry.attributes),
});

myLogger stands for your own code. Each entry uses OpenTelemetry field names:

Field Description
timestamp When the step happened, ISO 8601
severityText DEBUG, INFO, WARN or ERROR
severityNumber The OpenTelemetry number of that level
eventName The step, for example sdk.ready or proof.not_signed
body One sentence that describes the step
attributes The step's values, for example session.id
resource The SDK release and the platform

formatLine(entry), exported by the package, renders an entry as its console line. logLevel raises the level entries are written from, for the console and onLog alike: 'warn' drops INFO, and 'off' stops both. See Logging options.

Receive the captured input

An integration is an object with a name and a setup function. The SDK calls setup once, during init, with attach. Each transporter you attach receives every object the SDK captures, through its transport method.

import { init, type SchemaObject } from '@dea/sdk';

const captured: SchemaObject[] = [];

init({
  appId: 'YOUR_APP_ID',
  appKey: 'YOUR_APP_KEY',
  integrations: [
    {
      name: 'my-capture',
      setup(attach) {
        attach({ transport: (object) => captured.push(object) });
      },
    },
  ],
});

attach returns a function that detaches the transporter. setup also receives the session as its second argument: session.getSessionInfo() answers the same as getSessionInfo() on the instance init returns.

How the objects reach your transporter:

Rule Description
Order In capture order, a moment after capture. Each transporter has its own queue, so a slow transport delays only itself
Queue limit 4096 objects. Past that, new objects are dropped until the queue drains
Errors A transporter whose transport throws 5 times in a row is detached
Consent When the user withdraws consent, the objects still queued are discarded
dispose() Nothing more arrives

Keep transport short: copy the object into your own buffer, and send from your own timer.

What an object holds

Every object carries schema, the version of its shape; session, the session id; and device: the runtime, the operating system, the surface size, the pixel ratio, the rotation, the number of touch points and the motion sensor rate. It also holds exactly one of these records:

Key When Fields
event A pointer, wheel or key event ts, kind (Kind), tool (PointerTool), buttons, position (x, y, logical pixels on device.surface), and when they apply pointer_id, scroll, force, contact, stylus, target, key (the KeyClass and modifiers, never the character)
motion One motion sensor sample, on phones and tablets ts, acceleration (m/s², three axes), rotation_rate (rad/s, three axes)
lifecycle The page goes to the background or returns ts, state (LifecycleState)
custom Your app records a custom event ts, name, data
tick A fixed heartbeat while the session runs, on desktop only ts

ts is in microseconds since the session began. Kind, PointerTool, KeyClass and LifecycleState are exported by the package, with the other types of the object.

Examples

Send test sessions to your own service

import { init, type SchemaObject } from '@dea/sdk';

const buffer: SchemaObject[] = [];

setInterval(() => {
  if (buffer.length === 0) return;
  const batch = buffer.splice(0);
  void fetch('https://qa.example.com/dea-sessions', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify(batch),
  });
}, 5000);

const dea = init({
  appId: 'YOUR_APP_ID',
  appKey: 'YOUR_APP_KEY',
  requireConsent: true,
  onLog: (entry) => console.debug('[dea]', entry.eventName, entry.attributes),
  integrations: [
    {
      name: 'qa-forwarder',
      setup(attach) {
        attach({ transport: (object) => buffer.push(object) });
      },
    },
  ],
});

// When the tester agrees:
dea.setConsent(true);

https://qa.example.com stands for your own service; allow it in connect-src of your Content Security Policy. What you send there is yours to protect: it holds your testers' raw input.