Express | Pieowl

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

Good to know

An Express app needs up to three pieces. Use the ones you need:

Pages and visitors: the HTML script in the pages Express serves.
AI crawlers and bots: @pieowl/bots, which reports the bots the script can't see.
Server-side events (sign-ups, payments): @pieowl/sdk.

Track pages

Add the script to your HTML template (EJS, Pug, Handlebars or static files) and replace YOUR_CLIENT_ID with your client ID.

views/layout.html

<script src="https://pieowl.com/pieowl.js" data-client-id="YOUR_CLIENT_ID" defer></script>

For events, identifying users and all options, see the Script Tag docs.

Track AI crawlers and bots

bash

npm install @pieowl/bots

import { trackBots } from '@pieowl/bots/express';

app.use(trackBots({
  clientId: process.env.PIEOWL_CLIENT_ID,
  clientSecret: process.env.PIEOWL_CLIENT_SECRET,
}));

Requests from AI and search bots are reported after the response is sent, with the status code. Visitors cause no extra work. Behind a proxy or load balancer, set Express's trust proxy so req.ip is the bot's IP. Read more in AI crawlers and bots.

Avoid ad blockers

Serve the script and send events through your own domain:

import { createRouteHandler } from '@pieowl/bots/express';

app.use('/api/pieowl', 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

Use the JavaScript SDK with your client secret. Keep the secret on the server.

bash

npm install @pieowl/sdk

pieowl.ts

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

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

import { pieowl } from './pieowl';

app.post('/sign-up', async (req, res) => {
  const user = await createUser(req.body);
  // Pass profileId on each call: one instance serves every visitor.
  pieowl.track('sign_up', { profileId: user.id, plan: req.body.plan });
  res.json({ ok: true });
});

Server events get their location from the request IP, which is your server's. To use the visitor's location, create an instance for the request and forward the IP and user agent:

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

function pieowlFor(req) {
  const pieowl = new Pieowl({
    clientId: process.env.PIEOWL_CLIENT_ID,
    clientSecret: process.env.PIEOWL_CLIENT_SECRET,
  });
  if (req.ip) pieowl.api.addHeader('pieowl-client-ip', req.ip);
  pieowl.api.addHeader('user-agent', req.get('user-agent') ?? '');
  return pieowl;
}

Working with groups

Groups let you track analytics at the account or company level. See the Groups guide for the full walkthrough.

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

app.post('/login', async (req, res) => {
  const user = await loginUser(req.body);
  const pieowl = pieowlFor(req);

  pieowl.identify({ profileId: user.id, email: user.email });
  pieowl.upsertGroup({
    id: user.organizationId,
    type: 'company',
    name: user.organizationName,
    properties: { plan: user.plan },
  });
  pieowl.setGroup(user.organizationId);

  res.json({ ok: true });
});

For every method, see the JavaScript SDK.