Facts reviewed: 2026-10-20

Follow the [quickstart prerequisites](/docs/quickstart/) first. `useAnalytics` is an Owleye Analytics controller factory, not a React hook. Call it from an effect so server rendering does not create a tracker. Mount one instance near the application root.

```tsx
"use client";

import { useEffect } from "react";
import { useAnalytics } from "@owleye/analytics";
import { trackRules } from "@owleye/analytics/rules";

export function OwlEyeTracking({ allowed }: { allowed: boolean }) {
  useEffect(() => {
    if (!allowed) return;

    const analytics = useAnalytics("your-site-id");
    const rules = trackRules("your-site-id");
    return () => {
      rules.stop();
      analytics.stop();
    };
  }, [allowed]);

  return null;
}
```

Pass `allowed` from the site's consent or lawful-basis flow. In a Next.js App Router application, render this client component inside the root layout. Keep the layout server-rendered; only the tracking component needs the client directive. A plain React application can use the same component without the directive.

The controller observes History API navigation. Do not add a second route effect that sends a manual page view for every URL change, or you will count the same navigation twice. Query and fragment changes alone do not produce page views unless `trackQueryChanges` or `trackHashChanges` is enabled. These counting options are separate from `captureQuery` and `captureHash`, which control the URL content sent.

React development Strict Mode can initialize, clean up, and initialize an effect again. The current SDK shares active instances and avoids another automatic page view on a same-URL remount. Cleanup removes listeners, but cannot retract requests already started. Use a separate development site or `mock: true` while developing, and verify counts in a production build.

Changing `allowed` to false stops both controllers. A later true value creates a fresh rules controller and fetches current rules. Do not put credentials, user IDs, or email addresses into global event properties.