Script Tag

Installation

Paste this tag into the <head> of your page and replace YOUR_CLIENT_ID with your client ID.

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

What gets collected

You choose this in the dashboard, in Settings → Site → What Pieowl counts:

• Page views: every page someone opens. On by default.
• Clicks on links to other sites: which outside links people click. On by default.
• Clicks you marked in your code: elements with data-track="…". On by default.
• Address changes after #: for one-page sites that change only the part after #. Off by default.
• Session replay: records visits so you can watch them later. Off by default. See Session replay.

The script loads these settings on every page. A change reaches your site within about a minute, with no code to edit.

Calling Pieowl before the script loads

window.pieowl('track', ...) works once pieowl.js has loaded. To call it earlier, put this line before the script tag. It queues your calls and sends them in order once the script is ready. Until then only the window.pieowl('track', ...) form works, not window.pieowl.track(...).

<script>window.pieowl=window.pieowl||function(){(window.pieowl.q=window.pieowl.q||[]).push(arguments)};</script>
<script src="https://pieowl.com/pieowl.js" data-client-id="YOUR_CLIENT_ID" defer></script>

Options in code

Most sites need no options. For options from the list below, such as filter or disabled, use the init form instead of data-client-id: the queue line, then init with your options, then the script tag without data-client-id.

<script>
  window.pieowl=window.pieowl||function(){(window.pieowl.q=window.pieowl.q||[]).push(arguments)};
  window.pieowl('init', {
    clientId: 'YOUR_CLIENT_ID',
    // your options, e.g. disabled: true
  });
</script>
<script src="https://pieowl.com/pieowl.js" defer></script>

Options

Common options

• apiUrl - The URL of the Pieowl API (default: https://api.pieowl.com). Change it only to send events through your own proxy
• clientId - The client id of your application
• clientSecret - The client secret of your application (only required for server-side events)
• filter - A function that will be called before sending an event. If it returns false, the event will not be sent
• disabled - If true, events are queued and not sent until you call ready() (useful for consent)

Web options

What the script collects by itself is set per site in Settings → Site → What Pieowl counts, not in code. The four options below are only a fallback, used when the script can't load those settings.

• trackScreenViews - Fallback for Page views (default: true)
• trackOutgoingLinks - Fallback for Clicks on links to other sites (default: true)
• trackAttributes - Fallback for Clicks you marked in your code, elements with data-track (default: true)
• trackHashChanges - Fallback for Address changes after #, for hash-based routers (default: false)
• sessionReplay - Technical options for the screen recorder. Most sites need none. Turning replay on and choosing how many visits to record is done in Settings → Site → What Pieowl counts. Text and form fields are always hidden. See session replay docs.
  • blockSelector - CSS selector for elements to replace with a placeholder (default: [data-pieowl-replay-block])
  • blockClass - Class name that blocks elements from being recorded
  • ignoreSelector - CSS selector for elements excluded from interaction tracking
  • flushIntervalMs - How often (ms) recorded events are sent to the server (default: 10000)
  • maxEventsPerChunk - Maximum events per payload chunk (default: 200)
  • maxPayloadBytes - Maximum payload size in bytes (default: 1048576)
  • scriptUrl - Custom URL for the replay script (script-tag builds only)

Usage

You can call every method in two ways: window.pieowl('track', ...) or window.pieowl.track(...). The second form works only after pieowl.js has loaded. This page uses the first form.

Tracking events

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

<button type="button" onclick="window.pieowl('track', 'my_event', { foo: 'bar' })">
  Track event
</button>

<button type="button" data-track="my_event" data-foo="bar">Track event</button>

Identifying users

To identify a user, call window.pieowl('identify') with a unique ID.

window.pieowl('identify', {
  profileId: '123', // Required
  firstName: 'Joe',
  lastName: 'Doe',
  email: 'joe@doe.com',
  properties: {
    tier: 'premium',
  },
});

Setting global properties

To set properties that are sent with every event:

window.pieowl('setGlobalProperties', {
  app_version: '1.0.2',
  environment: 'production',
});

Incrementing properties

To increase a numeric property on a user profile.

• value is the amount to add. If you leave it out, the property goes up by 1.

window.pieowl('increment', {
  profileId: '1',
  property: 'visits',
  value: 1 // optional
});

Decrementing properties

To decrease a numeric property on a user profile.

• value is the amount to subtract. If you leave it out, the property goes down by 1.

window.pieowl('decrement', {
  profileId: '1',
  property: 'visits',
  value: 1 // optional
});

Tracking revenue

Send the order number as id and the amount in normal units, like 49.99. currency is optional and defaults to your site currency. The same order sent twice counts once. Purchases and refunds sent from the browser are rejected unless you turn on Accept revenue sent from the browser in Settings → Site → Revenue. Each purchase is credited to the current visit. See Revenue attribution for how purchases are credited, and Revenue tracking for checkout flows.

window.pieowl('purchase', { id: 'A-1001', amount: 49.99, currency: 'EUR' });

// Refund the whole order, or pass amount for part of it
window.pieowl('refund', { id: 'A-1001' });

Clearing user data

To clear the current user's data, for example on logout:

window.pieowl('clear');

Advanced usage

Filtering events

Add a filter function to the init options (see Options in code). If it returns false, the event is not sent.

This example turns tracking off for users who have a disable_tracking item in local storage.

window.pieowl('init', {
  clientId: 'YOUR_CLIENT_ID',
  filter: () => localStorage.getItem('disable_tracking') === null,
});

Using the Web SDK with npm

npm install @pieowl/web

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

export const pieowl = new Pieowl({
  clientId: 'YOUR_CLIENT_ID',
});

import { pieowl } from './pieowl.js';

pieowl.track('my_event', { foo: 'bar' });

TypeScript

Getting TypeScript errors when you call window.pieowl? Add a type definition file to your project.

Simple

Paste this into any of your .d.ts files.

declare global {
  interface Window {
    pieowl: {
      q?: IArguments[];
      (...args: [
        'init' | 'track' | 'identify' | 'setGlobalProperties' | 'increment' | 'decrement' | 'revenue' | 'clear',
        ...any[]
      ]): void;
    };
  }
}

Strict typing (from the SDK)

npm install @pieowl/web

/// <reference types="@pieowl/web" />