Astro

Track pages

Add the script to your root layout and replace YOUR_CLIENT_ID with your client ID. is:inline keeps Astro from bundling it. It works with static and server-rendered pages, and with View Transitions.

<html>
  <head>
    <script is:inline src="https://pieowl.com/pieowl.js" data-client-id="YOUR_CLIENT_ID" defer></script>
  </head>
  <body>
    <slot />
  </body>
</html>

What the script collects by itself (page views, outside link clicks, data-track clicks) is set in Settings → Site → What Pieowl counts, not in code. For options that need code, see Options in code.

Tracking events

Call window.pieowl, or add data-track attributes. data-track needs Clicks you marked in your code to be on in Settings → Site (it is by default).

<button onclick="window.pieowl('track', 'clicky')">Click me</button>
<button data-track="clicky" data-prop1="prop1" data-prop2="prop2">Click me</button>

<script>
  document.querySelector('#signup')?.addEventListener('click', () => {
    window.pieowl('track', 'signup_clicked', { location: 'header' });
  });
</script>

Identifying users

When you know the user on the server, render the call into the page:

---
const user = Astro.locals.user;
---

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

This call runs before pieowl.js has loaded, so add the queue line before the script tag in your layout. setGlobalProperties, increment, decrement and clear work the same way. See the Script Tag docs.

Track AI crawlers and bots

On server-rendered sites (an Astro adapter with output: 'server' or on-demand pages), report the bots the script can't see:

npm install @pieowl/bots

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();
});

Static sites have no server to see the bots. Read more in AI crawlers and bots.

Avoid ad blockers

On a server-rendered site, serve the script and send events through your own domain with an endpoint:

import { createRouteHandler } from '@pieowl/bots/route-handler';

const handler = createRouteHandler();

export const prerender = false;
export const ALL = ({ request }: { request: Request }) => handler(request);

Then switch to the init form, set apiUrl: '/api/pieowl' in init, and load the script from /api/pieowl/pieowl.js. See Avoid ad blockers.

Server-side events

Use the JavaScript SDK (@pieowl/sdk) with your client secret in endpoints and server-rendered pages.