Nuxt | Pieowl

Looking for a step-by-step tutorial? Read the Nuxt analytics guide.

Track pages

Add the script in nuxt.config.ts and replace YOUR_CLIENT_ID with your client ID. It tracks client-side route changes too.

nuxt.config.ts

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        { src: 'https://pieowl.com/pieowl.js', 'data-client-id': 'YOUR_CLIENT_ID', defer: true },
      ],
    },
  },
});

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

In components, 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).

vue

<template>
  <button type="button" @click="signup">Sign up</button>
</template>

<script setup lang="ts">
function signup() {
  window.pieowl('track', 'signup_clicked', { location: 'header' });
}
</script>

Identifying users

This is personal data. Make sure you have the user's consent before you call this.

window.pieowl('identify', {
  profileId: user.id, // Required
  email: user.email,
  properties: { tier: 'premium' },
});

setGlobalProperties, increment, decrement and clear work the same way. See the Script Tag docs.

Track AI crawlers and bots

bash

npm install @pieowl/bots

server/middleware/pieowl-bots.ts

import { trackBotRequest } from '@pieowl/bots';

export default defineEventHandler((event) => {
  trackBotRequest({ url: getRequestURL(event).href, headers: getRequestHeaders(event) }, {
    clientId: process.env.PIEOWL_CLIENT_ID!,
    clientSecret: process.env.PIEOWL_CLIENT_SECRET!,
  });
});

It reports only requests that look like a bot and never blocks the page. Read more in AI crawlers and bots.

Avoid ad blockers

Serve the script and send events through your own domain:

server/routes/api/pieowl/[...path].ts

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

export default fromWebHandler(createRouteHandler());

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

To track events from your server, use the JavaScript SDK.

Server events must include your client secret. Browsers prove where they come from with CORS headers, but servers can't, so the secret authenticates the request. Use the same client ID as in the script, add its client secret, and keep it on the server.

server/api/signup.post.ts

import { Pieowl } from '@pieowl/sdk';

const pieowlServer = new Pieowl({
  clientId: process.env.PIEOWL_CLIENT_ID!,
  clientSecret: process.env.PIEOWL_CLIENT_SECRET!,
});

export default defineEventHandler(async (event) => {
  const user = await createUser(await readBody(event));
  // In serverless functions, await so the event is sent before the function stops.
  await pieowlServer.track('sign_up', { profileId: user.id });
  return { ok: true };
});