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.
Tutorial6 min read
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
localhosttoo while you build on your computer, or events from it answer403. See Add your first site. - The site key, from the site's Install screen. It isn't a secret.
- Node.js 20 or later.
1Create the project
npx create-next-app@latest northwilds-site --ts --app --eslint --no-tailwind --no-src-dir --import-alias "@/*" --no-cache-components --yescd northwilds-siterm app/page.module.cssAdd the site key:
INSIGHTS_SITE=SITE_KEY2Add the script
Put the script in the root layout, so it is on every page. Replace 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_SITEexport 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 throughhistory.pushState, so you don't neednext/scriptor a page view call in your code. INSIGHTS_SITEis read when the layout renders on the server. The page is static here, so the key is fixed when you runnext 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:
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> )}3Send 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.
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:
'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> )}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 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.
4Wait 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. To ask first, add data-consent="wait" to the script in app/layout.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:
'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.
5Check 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
POSTrequests tocollectanswering202, 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:
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.
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 lists every other cause.
Next steps
- The script: every option, opting out and labels.
- Serve Insights Orbit from your own domain: a route handler so ad blockers don't hide visits.
- Send events from a server: payments and bookings your server confirms.
- Connect Insights Orbit with the CMS Orbit SDK: if the website is built with CMS Orbit.
Was this page helpful?