# Next.js quickstart

> Add Insights Orbit to a Next.js App Router website, send your own events, wait for consent and check that visits arrive.

Source: https://docs.bifrostorbit.com/insights/developers/quickstart-nextjs/

In about 10 minutes you add Insights Orbit to a Next.js website for Northwilds. Page views count on every page, also when Next.js changes pages without reloading, a button sends a **Brochure requested** event, and an optional banner asks visitors before anything is counted.

**Tested with:** Next.js 16.4.5, React 19.3, Node.js 24.

## Before you start

You need:

- **A site in Insights Orbit** with your website's addresses under **Site settings**. Add `localhost` too while you build on your computer, or events from it answer `403`. See [Add your first site](https://docs.bifrostorbit.com/insights/everyone/add-a-site/).
- **The site key**, from the site's **Install** screen. It isn't a secret.
- **Node.js 20 or later.**

## 1. Create the project

```bash
npx create-next-app@latest northwilds-site --ts --app --eslint --no-tailwind --no-src-dir --import-alias "@/*" --no-cache-components --yes
cd northwilds-site
rm app/page.module.css
```

Add the site key:

```bash
# .env.local
INSIGHTS_SITE=SITE_KEY
```

## 2. Add the script

Put the script in the root layout, so it is on every page. Replace `app/layout.tsx`:

```tsx
// app/layout.tsx
import type { Metadata } from 'next'
import Link from 'next/link'

import './globals.css'

export const metadata: Metadata = { title: 'Northwilds' }

const site = process.env.INSIGHTS_SITE

export default function RootLayout({ children }: LayoutProps<'/'>) {
  return (
    <html lang="en">
      <head>
        {site ? <script defer data-site={site} src="https://api.bifrostorbit.com/insights/v1/script.js" /> : null}
      </head>
      <body>
        <header>
          <Link href="/">Northwilds</Link> <Link href="/trips">Trips</Link>
        </header>
        {children}
      </body>
    </html>
  )
}
```

- **A plain `<script defer>`** is all it needs. The script follows Next.js's page changes through `history.pushState`, so you don't need `next/script` or a page view call in your code.
- **`INSIGHTS_SITE`** is read when the layout renders on the server. The page is static here, so the key is fixed when you run `next build`: set it where you build.
- **Without a key**, nothing is added, so a copy of the website without the setting counts nothing.

Replace `app/page.tsx` with a page that links to the trips:

```tsx
// app/page.tsx
import Link from 'next/link'

export default function Home() {
  return (
    <main>
      <h1>Northwilds</h1>
      <p>Guided trips in the far north.</p>
      <Link href="/trips">See the trips</Link>
    </main>
  )
}
```

## 3. Send your own events

A small helper calls the script, or queues the call when the script hasn't loaded yet. The script runs the queue once it loads.

```ts
// lib/insights.ts
export type Details = Record<string, string | number | boolean>
export type Money = { revenue: number; currency: string }

type Insights = {
  track?: (name: string, details?: Details, money?: Money) => void
  consent?: (given?: boolean) => void
  q?: unknown[][]
}

declare global {
  interface Window {
    insights?: Insights
  }
}

export function track(name: string, details?: Details, money?: Money) {
  if (window.insights?.track) window.insights.track(name, details, money)
  else (window.insights ??= { q: [] }).q?.push(['track', name, details, money])
}

export function consent(given = true) {
  if (window.insights?.consent) window.insights.consent(given)
  else (window.insights ??= { q: [] }).q?.push(['consent', given])
}
```

A button on the trip page sends **Brochure requested** with the trip:

```tsx
// app/trips/brochure-button.tsx
'use client'

import { useState } from 'react'

import { track } from '@/lib/insights'

export function BrochureButton({ trip }: { trip: string }) {
  const [sent, setSent] = useState(false)
  return (
    <button
      type="button"
      disabled={sent}
      onClick={() => {
        track('Brochure requested', { trip })
        setSent(true)
      }}
    >
      {sent ? 'On its way' : 'Send me the brochure'}
    </button>
  )
}
```

```tsx
// app/trips/page.tsx
import { BrochureButton } from './brochure-button'

export default function Trips() {
  return (
    <main>
      <h1>Lofoten ski touring week</h1>
      <p>Seven days of ski touring above the fjords, from €2,450.</p>
      <BrochureButton trip="lofoten-ski-touring" />
    </main>
  )
}
```

- **Event names** are what goals look for, so use plain words. Details are text, numbers or true or false; never names or email addresses. [Send your own events](https://docs.bifrostorbit.com/insights/developers/send-events/) has the limits.
- **Revenue** goes in the third argument: `track('Trip booked', { trip: 'lofoten-ski-touring' }, { revenue: 2450, currency: 'EUR' })`.
- **To count it as success**, an Editor adds a goal under **Goals** that sends the event `Brochure requested`. See [Set up goals](https://docs.bifrostorbit.com/insights/everyone/goals/).

## 4. Wait for consent (optional)

Insights Orbit uses no cookies and keeps no personal data. Whether you still ask first is your decision with your adviser. See [What to write in your privacy notice](https://docs.bifrostorbit.com/insights/everyone/privacy-notice/). To ask first, add `data-consent="wait"` to the script in `app/layout.tsx`:

```tsx
{site ? <script defer data-site={site} data-consent="wait" src="https://api.bifrostorbit.com/insights/v1/script.js" /> : null}
```

The script now counts nothing until the page calls `insights.consent()`. It doesn't remember the answer, so your banner keeps it and calls `consent()` on every page:

```tsx
// app/consent-banner.tsx
'use client'

import { useEffect, useState, useSyncExternalStore } from 'react'

import { consent } from '@/lib/insights'

const KEY = 'northwilds-analytics'

const subscribe = (onChange: () => void) => {
  window.addEventListener('storage', onChange)
  return () => window.removeEventListener('storage', onChange)
}

export function ConsentBanner() {
  const saved = useSyncExternalStore(subscribe, () => localStorage.getItem(KEY), () => 'server')
  const [answered, setAnswered] = useState(false)

  useEffect(() => {
    if (saved === 'yes') consent()
  }, [saved])

  function choose(answer: 'yes' | 'no') {
    localStorage.setItem(KEY, answer)
    setAnswered(true)
    consent(answer === 'yes')
  }

  if (saved !== null || answered) return null
  return (
    <aside aria-label="Analytics">
      <p>May we count your visit? We use no cookies and keep no personal data.</p>
      <button type="button" onClick={() => choose('yes')}>Yes</button>
      <button type="button" onClick={() => choose('no')}>No thanks</button>
    </aside>
  )
}
```

Import it in `app/layout.tsx` and put `<ConsentBanner />` after `{children}`.

- **Page views before the answer wait in memory**, up to 50, and are sent the moment the visitor says yes, so the page where they agreed still counts.
- **No thanks** drops what is waiting, and nothing is sent on later pages.
- **If you already have a consent tool**, call `consent()` from it instead of this banner.

## 5. Check that events arrive

Run `npm run dev`, open `http://localhost:3000`, go to **Trips** and select **Send me the brochure**. If you added the banner, select **Yes** first.

- **In the browser:** the **Network** tab shows `POST` requests to `collect` answering `202`, with your page views and the event. Events are sent two seconds after they happen, or at once when the page is hidden.
- **In Insights Orbit:** **Install** says **Visits are arriving**, **Right now** on the overview shows you on `/trips`, and **Events** lists **Brochure requested** within a few seconds.
- **From the API**, on the Growth plan, with a key that reads events:

```bash
curl "https://api.bifrostorbit.com/insights/v1/events?site=SITE_KEY&name=Brochure%20requested" \
  -H "Authorization: Bearer ins_live_…"
```

It answers with the event, its `path` (`/trips`) and its details. See [Read raw events](https://docs.bifrostorbit.com/insights/developers/raw-event-api/).

Nothing arrives? Browsers with Do Not Track or Global Privacy Control on, and automated browsers such as Playwright, send nothing on purpose. [Troubleshooting for developers](https://docs.bifrostorbit.com/insights/developers/troubleshooting/) lists every other cause.

## Next steps

- [The script](https://docs.bifrostorbit.com/insights/developers/the-script/): every option, opting out and labels.
- [Serve Insights Orbit from your own domain](https://docs.bifrostorbit.com/insights/developers/first-party-proxy/): a route handler so ad blockers don't hide visits.
- [Send events from a server](https://docs.bifrostorbit.com/insights/developers/server-api/): payments and bookings your server confirms.
- [Connect Insights Orbit with the CMS Orbit SDK](https://docs.bifrostorbit.com/insights/developers/cms-orbit-sdk/): if the website is built with CMS Orbit.
