Events, tracking continuity and diagnostics
Track lifecycle and visibility
| Event | Main fields | Use |
|---|---|---|
targetFound |
targetId, timestampMs, pose |
First detection or reacquisition |
targetLost |
targetId, timestampMs, retained, reason |
Confirmed loss, removal or stop |
targetVisibility |
targetId, visible, reason |
Control visibility in a custom renderer |
trackingQuality |
targetId, timestampMs, state, score, processingMs, issues, diagnosis |
Guide users and diagnose tracking |
Listen through scene.addEventListener(name, callback) and read event.detail, or subscribe via engine.on(name, callback). The engine returns an unsubscribe function. ar-ready means the scene is prepared. Use target events to determine whether a marker is visible.
Avoid flicker and restarts
The loss grace period absorbs brief interruptions. The target states are tracking, recovering and lost. Found/lost events occur on transitions, so load assets once and keep playback independent of these events. Enable keep-content-on-lost to retain the last displayed transform after confirmed loss. In a running scene, call scene.engine.setKeepContentOnLost(enabled) and update the attribute for the next session.
const scene = document.querySelector('webar-scene');
scene.addEventListener('trackingQuality', ({detail}) => {
if (detail.issues.includes('small-target')) console.log('Move closer');
if (detail.issues.includes('blur')) console.log('Hold the camera steady');
});
Quality scores range from 0 to 1 and are heuristic. Use motion, inlier count and measured timings with the issue labels. Diagnostics