✦ Cookieless analytics, built around daily rotating IDs
☰
All featuresWeb AnalyticsCustom EventsCookieless AnalyticsIntegrationsPricingDocumentationComparisonsFree toolsBlogGlossary
Installation guide

Install cookieless analytics in Next.js

Add one browser SDK instance to the App Router and send a pageview after client navigation. Keep server rendering free of browser-only initialization.

Prepare the SDK from source

The SDK package is currently private and unpublished. Clone its repository and build the browser bundle. The source repository uses pnpm; application integration examples below use npm. Pin a reviewed commit for a production deployment.

Build the source and a local package archive

git clone https://github.com/yosriady/untitled-analytics-sdk.git
cd untitled-analytics-sdk
pnpm install
pnpm build
pnpm pack

Install the local SDK archive

Run this command in your Next.js application after building the SDK. This is a local dependency while the public package remains unreleased.

Application install command

npm install ../untitled-analytics-sdk/untitled-analytics-web-0.1.0.tgz

Create a browser-only singleton

Disable automatic pageviews in this integration so the route observer owns page tracking. The getter avoids initializing during server rendering and reuses one instance across client renders.

Shared SDK module

// src/lib/analytics.ts
import { createAnalytics } from '@untitled-analytics/web';

let instance: ReturnType<typeof createAnalytics> | undefined;
export function getAnalytics() {
  if (typeof window === 'undefined') return undefined;
  return instance ??= createAnalytics({
    writeKey: 'YOUR_SDK_WRITE_KEY',
    endpoint: 'https://api.your-domain.com',
    autoPageviews: false,
  });
}

Observe App Router navigation

Read the pathname and search parameters in a client component. The SDK removes full page queries from the transmitted URL while retaining selected attribution fields. The SDK’s same-path guard avoids duplicate empty page calls on the shared instance.

Client route observer

// src/components/analytics-tracker.tsx
'use client';
import { useEffect } from 'react';
import { usePathname, useSearchParams } from 'next/navigation';
import { getAnalytics } from '../lib/analytics';

export function AnalyticsTracker() {
  const pathname = usePathname();
  const search = useSearchParams().toString();
  useEffect(() => { getAnalytics()?.page(); }, [pathname, search]);
  return null;
}

Mount the observer once

Wrap the component in Suspense in your root layout. Place it inside the body alongside your application content. Use an additional authentication hook to call identify when your account is available.

App Router root layout

import { Suspense } from 'react';
import { AnalyticsTracker } from '../components/analytics-tracker';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <html lang="en"><body>
    {children}
    <Suspense fallback={null}><AnalyticsTracker /></Suspense>
  </body></html>;
}

Verify pageviews and custom events

Register your actual site origin and use its public SDK write key. The endpoint is your deployed API origin, not a Tinybird URL. Open the published site, check that the bundle loads, and inspect successful collector requests and the project activity feed. Collection is queued, so allow for delivery latency.

Trigger a second page and a custom event. Confirm one expected pageview per navigation. Disable duplicate analytics installations. Identify an account only after login and clear the SDK user ID at logout. Review campaign fields, properties, and optional replay on a non-sensitive page first.

Frequently asked questions

Is the npm package public?

No. Build from source and install the local archive, or host the built browser bundle. Do not assume npm install @untitled-analytics/web resolves yet.

Which endpoint do I use?

Use your deployed analytics API origin, such as https://api.your-domain.com. Do not expose Tinybird or database credentials in browser code.

How do I check installation?

Verify bundle loading and successful collector requests, then inspect the project activity feed for the page and a named test event.

Sources and implementation