Tempusxr Français
Menu
  1. Docs
  2. Build with the SDK

Basic analytics

Know how many people open an experience, what they look at, what they tap, and for how long. The analytics send four kinds of event and nothing about the person.

It is off by default: nothing is sent unless you give an endpoint.

Turn it on

With loadScene(), one option:

const experience = await loadScene('https://example.com/s/abc123/scene.json', {
  container: '#ar',
  analytics: { endpoint: 'https://a.example.com/e' },
});

Without a scene file, plug it into any experience:

import { createAnalytics } from '@tempusxr/sdk-core';

const analytics = createAnalytics({ endpoint: 'https://a.example.com/e', scene: 'abc123' });
const experience = await loadScene(url, { container: '#ar', onEvent: analytics.onEvent });

To see the events while you build, open the scene example with ?analytics on the dev server (pnpm dev): it prints what it receives.

What is measured

EventWhenExtra field
openedThe experience started (after start()). Once per visit.
foundA target is found. Every time, so the count says how often people look at it.target
tapA tap ran a behavior.node
timeSeconds spent in the experience, sent every 15 seconds while the page is visible, and once more when the page is hidden or closed.seconds since the last time

Every event carries scene (the scene id), visit, and at (milliseconds since 1970). Nothing else.

What is sent

Events are grouped and sent to your endpoint with a POST, content type application/json:

{
  "v": 1,
  "events": [
    { "type": "opened", "scene": "abc123", "visit": "9f3c0a1b7e2d4c58", "at": 1793536000000 },
    { "type": "found", "scene": "abc123", "visit": "9f3c0a1b7e2d4c58", "at": 1793536003210, "target": "poster" },
    { "type": "time", "scene": "abc123", "visit": "9f3c0a1b7e2d4c58", "at": 1793536018000, "seconds": 15 }
  ]
}

Your server answers 204. Any other answer is ignored.

Privacy

Options

OptionWhat it does
endpointWhere the batches go. Without it, nothing is sent.
sceneThe scene id. loadScene fills it in.
consentA function that returns whether you may collect.
respectPrivacySignalsDefault true.
batchSizeEvents sent together at most. Default 20.
flushMsThe longest an event waits before it is sent. Default 5000.
timeMsHow often time is sent. Default 15000.
maxQueueEvents kept while waiting. The oldest are dropped past this. Default 100.

It never gets in the way

The client is created when the experience starts and never touches the frame loop. It sends with navigator.sendBeacon (so it still works when the page closes) and falls back to fetch with keepalive. A failed send is ignored: no retry, no error in your experience. The time of a page that is hidden is not counted.

The collecting service is not part of the SDK yet. It comes with the Viewer backend. The format above is the contract.