# Script Tag

URL: https://pieowl.com/docs/sdks/script





Installation [#installation]

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

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

What gets collected [#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](/docs/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 [#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(...)`.

```html title="index.html"
<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 [#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`.

```html title="index.html"
<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 [#options]

<CommonSdkConfig />

<WebSdkConfig />

Usage [#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 [#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).

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

```html title="index.html"
<button type="button" data-track="my_event" data-foo="bar">Track event</button>
```

Identifying users [#identifying-users]

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

<PersonalDataWarning />

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

Setting global properties [#setting-global-properties]

To set properties that are sent with every event:

```js title="main.js"
window.pieowl('setGlobalProperties', {
  app_version: '1.0.2',
  environment: 'production',
});
```

Incrementing properties [#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.

```js title="main.js"
window.pieowl('increment', {
  profileId: '1',
  property: 'visits',
  value: 1 // optional
});
```

Decrementing properties [#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.

```js title="main.js"
window.pieowl('decrement', {
  profileId: '1',
  property: 'visits',
  value: 1 // optional
});
```

Tracking revenue [#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](/docs/revenue-attribution) for how purchases are credited, and [Revenue tracking](/docs/revenue-tracking) for checkout flows.

```js title="main.js"
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 [#clearing-user-data]

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

```js title="main.js"
window.pieowl('clear');
```

Advanced usage [#advanced-usage]

Filtering events [#filtering-events]

Add a `filter` function to the `init` options (see [Options in code](#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.

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

Using the Web SDK with npm [#using-the-web-sdk-with-npm]

<Steps>
  Step 1: Install the SDK [#step-1-install-the-sdk]

  <CodeBlockTabs defaultValue="npm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="yarn">
        yarn
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npm install @pieowl/web
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash
      pnpm add @pieowl/web
      ```
    </CodeBlockTab>

    <CodeBlockTab value="yarn">
      ```bash
      yarn add @pieowl/web
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```bash
      bun add @pieowl/web
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  Step 2: Initialize the SDK [#step-2-initialize-the-sdk]

  ```js title="pieowl.js"
  import { Pieowl } from '@pieowl/web';

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

  Step 3: Use the SDK [#step-3-use-the-sdk]

  ```js title="main.js"
  import { pieowl } from './pieowl.js';

  pieowl.track('my_event', { foo: 'bar' });
  ```
</Steps>

TypeScript [#typescript]

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

Simple [#simple]

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

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

Strict typing (from the SDK) [#strict-typing-from-the-sdk]

<Steps>
  Step 1: Install the SDK [#step-1-install-the-sdk-1]

  <CodeBlockTabs defaultValue="npm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="pnpm">
        pnpm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="yarn">
        yarn
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="bun">
        bun
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npm install @pieowl/web
      ```
    </CodeBlockTab>

    <CodeBlockTab value="pnpm">
      ```bash
      pnpm add @pieowl/web
      ```
    </CodeBlockTab>

    <CodeBlockTab value="yarn">
      ```bash
      yarn add @pieowl/web
      ```
    </CodeBlockTab>

    <CodeBlockTab value="bun">
      ```bash
      bun add @pieowl/web
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  Step 2: Create a type definition file [#step-2-create-a-type-definition-file]

  Create a `pieowl.d.ts` file and paste this line:

  ```ts title="pieowl.d.ts"
  /// <reference types="@pieowl/web" />
  ```
</Steps>