- Docs
- 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
| Event | When | Extra field |
|---|---|---|
opened | The experience started (after start()). Once per visit. | |
found | A target is found. Every time, so the count says how often people look at it. | target |
tap | A tap ran a behavior. | node |
time | Seconds 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
- No cookie and no storage. The
visitid is random, made when the page loads, and kept only in the page. It counts visits and never people, and it cannot follow someone from one day to the next. - Nothing else leaves the phone: no address of the person, no device details, no location. (Your own server sees the usual network information of any request. Do not keep what you do not need.)
- Do Not Track and Global Privacy Control are respected by default (
respectPrivacySignals: falseturns that off). - Consent: pass
consent: () => boolean. Events are dropped until it returns true, so a banner can decide. - This is meant to need no consent banner in most places, but that is for you and a lawyer to confirm for your case.
Options
| Option | What it does |
|---|---|
endpoint | Where the batches go. Without it, nothing is sent. |
scene | The scene id. loadScene fills it in. |
consent | A function that returns whether you may collect. |
respectPrivacySignals | Default true. |
batchSize | Events sent together at most. Default 20. |
flushMs | The longest an event waits before it is sent. Default 5000. |
timeMs | How often time is sent. Default 15000. |
maxQueue | Events 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.