How to add analytics to Astro

Analytics shows you how people use your Astro site. This guide sets up Pieowl to track page views, custom events and users. It takes about five minutes.

Pieowl fits Astro well. The script loads async, so it doesn't block rendering. It tracks page views on static and server-rendered pages, and the setup is one script tag in your layout.

Prerequisites

• An Astro project
• A Pieowl account (start a 14-day free trial)
• Your Client ID from the Pieowl dashboard

Get your snippet

There is no package to install. Pieowl is one script tag, loaded from pieowl.com. The snippet has two parts. The first line creates a small queue, so calls made before pieowl.js loads (like the identify call below) are sent once it's ready. The second loads the script with your Client ID.

Add the script to your layout

The script starts tracking. Put it in your root layout so it loads on every page. Place it inside <head> so it is ready before the user clicks anything. is:inline tells Astro to leave the script as it is.

<html>
  <head>
    <script is:inline>window.pieowl=window.pieowl||function(){(window.pieowl.q=window.pieowl.q||[]).push(arguments)};</script>
    <script is:inline src="https://pieowl.com/pieowl.js" data-client-id="your-client-id" defer></script>
  </head>
  <body>
    <slot />
  </body>
</html>

By default Pieowl records a page view each time someone opens a new page, and clicks on links to other sites. You can change this in Settings → Site → What Pieowl counts, with no code to edit.

Track AI crawlers (optional)

AI crawlers and search bots don't run JavaScript, so the script never sees them. On a server-rendered Astro site, add @pieowl/bots in your middleware to count them. It needs your client secret, so keep both keys in environment variables.

npm install @pieowl/bots

// src/middleware.ts
import { trackBotRequest } from '@pieowl/bots';
import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware((context, next) => {
  trackBotRequest(context.request, {
    clientId: import.meta.env.PIEOWL_CLIENT_ID,
    clientSecret: import.meta.env.PIEOWL_CLIENT_SECRET,
  });
  return next();
});

Track custom events

Page views are tracked for you. You will also want to track the actions that matter to your business. Pieowl adds a global window.pieowl function that you can call from any event handler.

<button onclick="window.pieowl('track', 'button_clicked', {button_name: 'signup'})">
  Sign up
</button>

The first argument is always 'track'. The second is the event name. The third is an optional object of properties. Keep event names the same across your codebase. snake_case is a good habit.

If you'd rather not write JavaScript, use data attributes. Any button or link with a data-track attribute sends an event when clicked. This needs Clicks you marked in your code to be on in Settings → Site (it is by default).

<button data-track="button_clicked" data-button-name="signup">
  Sign up
</button>

The data-track value becomes the event name. Every other data-* attribute becomes a property. Names are turned into camelCase, so data-button-name arrives as buttonName.

Tracking form submissions

Forms are a common thing to track. Send an event in the onsubmit handler and let the form submit as normal.

<form onsubmit="window.pieowl('track', 'form_submitted', {form_name: 'contact'}); return true;">
  <input type="email" name="email" placeholder="Your email" required />
  <button type="submit">Submit</button>
</form>

return true lets the form submit after the tracking call.

Identify users

When a user logs in, you can link their activity to a profile. Call window.pieowl('identify') with the user's data. define:vars passes the user from the server to the script.

---
const user = await getCurrentUser();
---

<script is:inline define:vars={{ user }}>
  window.pieowl('identify', {
    profileId: user.id,
    firstName: user.firstName,
    lastName: user.lastName,
    email: user.email,
    properties: {
      plan: user.plan,
    },
  });
</script>

Pieowl keeps the profile ID in memory only. It does not store it in a cookie or in local storage. Each full page load starts fresh, so render this script on every page where the user is logged in. Your layout is a good place for it.

Setting global properties

Sometimes you want the same properties on every event, such as an app version or environment. setGlobalProperties lets you set them once.

<script is:inline define:vars={{ mode: import.meta.env.MODE }}>
  window.pieowl('setGlobalProperties', {
    app_version: '1.0.2',
    environment: mode,
  });
</script>

These properties are merged with the properties you pass to each tracking call.

Verify your setup

Open your Astro site and visit a few pages. Then open the Pieowl dashboard and check the realtime view. Page views should show up within seconds.

No events? Open the browser console and look for errors. The most common causes are a wrong Client ID or an ad blocker that stops the script from loading. You can also check the Network tab for requests to api.pieowl.com.

Next steps

The script tag reference covers more options, such as event filters. The Astro docs cover bot tracking and the ad-blocker proxy.