# Astro quickstart

> Add Insights Orbit to an Astro website, send your own events, wait for consent and check that visits arrive.

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

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 `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 22 or later.**

## 1. Create the project

```bash
npm create astro@latest northwilds-site -- --template withastro/astro/examples/minimal --install --no-git --yes
cd northwilds-site
mkdir -p src/layouts src/lib src/components
```

Add the site key:

```bash
# .env
PUBLIC_INSIGHTS_SITE=SITE_KEY
```

A static build writes the key into the pages, so set it where you build.

## 2. Add the script

A layout puts the script on every page:

```astro
---
// src/layouts/Layout.astro
const site = import.meta.env.PUBLIC_INSIGHTS_SITE
const { 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:inline`** tells 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`:

```astro
---
// src/pages/index.astro
import 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>
```

## 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
// src/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])
}
```

The trip page has a button, and a `<script>` that Astro bundles for the browser sends the event:

```astro
---
// src/pages/trips.astro
import 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](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 the layout:

```astro
{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:

```astro
<!-- 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.

## 5. Check 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 `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_…"
```

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/): 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.
- [Read raw events](https://docs.bifrostorbit.com/insights/developers/raw-event-api/): every event for your own data tools.
