Astro quickstart
Add Insights Orbit to an Astro website, send your own events, wait for consent and check that visits arrive.
Tutorial5 min read
In about 10 minutes you add Insights Orbit to an Astro website for Northwilds. Page views count on every page, a button sends a Brochure requested event, and an optional banner asks visitors before anything is counted.
Tested with: Astro 7.4.7, @astrojs/check for types, Node.js 24, with a static build served by astro preview.
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 22 or later.
1Create the project
npm create astro@latest northwilds-site -- --template withastro/astro/examples/minimal --install --no-git --yescd northwilds-sitemkdir -p src/layouts src/lib src/componentsAdd the site key:
PUBLIC_INSIGHTS_SITE=SITE_KEYA static build writes the key into the pages, so set it where you build.
2Add the script
A layout puts the script on every page:
---// src/layouts/Layout.astroconst site = import.meta.env.PUBLIC_INSIGHTS_SITEconst { title = 'Northwilds' } = Astro.props---<html lang="en"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width" /> <title>{title}</title> {site && <script is:inline defer data-site={site} src="https://api.bifrostorbit.com/insights/v1/script.js"></script>} </head> <body> <header> <a href="/">Northwilds</a> <a href="/trips">Trips</a> </header> <slot /> </body></html>is:inlinetells Astro to leave the tag as it is instead of processing and bundling it.- Without a key, no script is added.
Use the layout on the home page. Replace src/pages/index.astro:
---// src/pages/index.astroimport Layout from '../layouts/Layout.astro'---<Layout> <main> <h1>Northwilds</h1> <p>Guided trips in the far north.</p> <a href="/trips">See the trips</a> </main></Layout>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])}The trip page has a button, and a <script> that Astro bundles for the browser sends the event:
---// src/pages/trips.astroimport Layout from '../layouts/Layout.astro'---<Layout title="Lofoten ski touring week"> <main> <h1>Lofoten ski touring week</h1> <p>Seven days of ski touring above the fjords, from €2,450.</p> <button type="button" data-brochure="lofoten-ski-touring">Send me the brochure</button> </main></Layout><script> import { track } from '../lib/insights' document.querySelectorAll<HTMLButtonElement>('[data-brochure]').forEach((button) => { button.addEventListener('click', () => { track('Brochure requested', { trip: button.dataset.brochure! }) button.textContent = 'On its way' button.disabled = true }) })</script>- 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 the layout:
{site && <script is:inline defer data-site={site} data-consent="wait" src="https://api.bifrostorbit.com/insights/v1/script.js"></script>}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:
<!-- src/components/ConsentBanner.astro --><aside id="consent" aria-label="Analytics" hidden> <p>May we count your visit? We use no cookies and keep no personal data.</p> <button type="button" data-answer="yes">Yes</button> <button type="button" data-answer="no">No thanks</button></aside><script> import { consent } from '../lib/insights' const KEY = 'northwilds-analytics' const banner = document.getElementById('consent')! const saved = localStorage.getItem(KEY) if (saved === 'yes') consent() banner.hidden = saved !== null banner.querySelectorAll<HTMLButtonElement>('[data-answer]').forEach((button) => { button.addEventListener('click', () => { localStorage.setItem(KEY, button.dataset.answer!) banner.hidden = true consent(button.dataset.answer === 'yes') }) })</script>In the layout, import it with import ConsentBanner from '../components/ConsentBanner.astro' and put <ConsentBanner /> after <slot />.
- The page where the visitor answers still counts: its page view waits in memory and is sent the moment they say yes. Astro pages load one by one, so pages they left before answering aren't counted.
- 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:4321, 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_…"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: so ad blockers don't hide visits.
- Send events from a server: payments and bookings your server confirms.
- Read raw events: every event for your own data tools.
Was this page helpful?