react-three-fiber

The react-three-fiber (R3F) connector. R3F renders three.js, so this package is a thin React layer over @uptimizr/three — it does not re-implement capture. It pulls the live scene, camera, and gl (WebGLRenderer) from the R3F store via useThree() and hands them to the three connector.

react, @react-three/fiber, and three are peer dependencies.

Install

npm install @uptimizr/r3f @react-three/fiber react three

Declarative component

Drop <Uptimizr /> anywhere inside your <Canvas>:

import { Canvas } from "@react-three/fiber";
import { Uptimizr } from "@uptimizr/r3f";

function App() {
  return (
    <Canvas>
      <Uptimizr projectId="your-project" endpoint="https://collect.example.com" />
      <YourScene />
    </Canvas>
  );
}

Hook

For access to the UptimizrClient (read sessionId, emit custom events, stop early), call useUptimizr() from a component rendered inside <Canvas>:

import { useUptimizr } from "@uptimizr/r3f";

function Telemetry() {
  const client = useUptimizr({
    projectId: "your-project",
    endpoint: "https://collect.example.com",
  });
  // client.track("add_to_cart", { sku: "ABC-123" });
  return null;
}

Capture starts when the hook/component mounts and stops on unmount, tearing down every listener, timer, and animation-frame callback — no cookies, no persistent IDs. World-space data is normalized to the canonical wire frame by @uptimizr/three; the session is attributed to the r3f connector.

WebXR and hit resolution

Both <Uptimizr /> and useUptimizr() accept the three connector’s full option set, including the xr option: WebXR controller/gaze capture is on by default and idles until an immersive session starts. To resolve XR rays to in-scene hits, build a probe over the R3F scene and pass it through — see three.js → WebXR for the event mapping:

import { useThree } from "@react-three/fiber";
import { createXrRaycaster, useUptimizr } from "@uptimizr/r3f";

function Telemetry() {
  const scene = useThree((s) => s.scene);
  useUptimizr({
    projectId: "your-project",
    endpoint: "https://collect.example.com",
    xr: { raycast: createXrRaycaster(scene) },
  });
  return null;
}