React | Pieowl

Good to know

All tracking on this page happens in the browser.

For React single-page apps, use @pieowl/web directly. You don't need a separate React SDK: create one Pieowl instance and import it where you need it.

Installation

Step 1: Install

bash

npm install @pieowl/web

Step 2: Initialize

Create a shared Pieowl instance in your project:

src/pieowl.ts

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

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

clientId is enough. What the SDK collects by itself (page views, outside link clicks, data-track clicks) is set in Settings → Site → What Pieowl counts, not in code.

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)

Step 3: Usage

Import the instance in your components:

tsx

import { pieowl } from '@/pieowl';

function MyComponent() {
  const handleClick = () => {
    pieowl.track('button_click', { button: 'signup' });
  };

  return <button onClick={handleClick}>Trigger event</button>;
}

Usage

Tracking events

Call 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).

tsx

import { pieowl } from '@/pieowl';

function MyComponent() {
  useEffect(() => {
    pieowl.track('my_event', { foo: 'bar' });
  }, []);

  return <div>My Component</div>;
}

Identifying users

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

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

tsx

import { pieowl } from '@/pieowl';

function LoginComponent() {
  const handleLogin = (user: User) => {
    pieowl.identify({
      profileId: user.id, // Required
      firstName: user.firstName,
      lastName: user.lastName,
      email: user.email,
      properties: {
        tier: 'premium',
      },
    });
  };

  return <button onClick={() => handleLogin(user)}>Login</button>;
}

Setting global properties

To set properties that are sent with every event:

tsx

import { pieowl } from '@/pieowl';

function App() {
  useEffect(() => {
    pieowl.setGlobalProperties({
      app_version: '1.0.2',
      environment: 'production',
    });
  }, []);

  return <div>App</div>;
}

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.

tsx

import { pieowl } from '@/pieowl';

function MyComponent() {
  const handleAction = () => {
    pieowl.increment({
      profileId: '1',
      property: 'visits',
      value: 1, // optional
    });
  };

  return <button onClick={handleAction}>Increment</button>;
}

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.

tsx

import { pieowl } from '@/pieowl';

function MyComponent() {
  const handleAction = () => {
    pieowl.decrement({
      profileId: '1',
      property: 'visits',
      value: 1, // optional
    });
  };

  return <button onClick={handleAction}>Decrement</button>;
}

Working with groups

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

tsx

import { pieowl } from '@/pieowl';

function LoginComponent() {
  const handleLogin = async (user: User) => {
    // 1. Identify the user
    pieowl.identify({ profileId: user.id, email: user.email });

    // 2. Create/update the group entity (only when data changes)
    pieowl.upsertGroup({
      id: user.organizationId,
      type: 'company',
      name: user.organizationName,
      properties: { plan: user.plan },
    });

    // 3. Link the user to their group — tags all future events
    pieowl.setGroup(user.organizationId);
  };

  return <button onClick={() => handleLogin(user)}>Login</button>;
}

Clearing user data

To clear the current user's data (including groups):

tsx

import { pieowl } from '@/pieowl';

function LogoutComponent() {
  const handleLogout = () => {
    pieowl.clear();
    // ... logout logic
  };

  return <button onClick={handleLogout}>Logout</button>;
}

Revenue tracking

Call purchase() with your order number 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 from the browser only work after you turn on Accept revenue sent from the browser in Settings → Site → Revenue. Each purchase is credited to the current visit. See Revenue attribution.

tsx

import { pieowl } from '@/pieowl';

function CheckoutComponent() {
  const handlePurchase = async () => {
    // Track a purchase right away
    await pieowl.purchase({ id: 'A-1001', amount: 29.99, currency: 'EUR' });

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

  return <button onClick={handlePurchase}>Purchase</button>;
}

Optional: create a hook

If you prefer a React hook, write a small wrapper:

src/hooks/usePieowl.ts

import { pieowl } from '@/pieowl';

export function usePieowl() {
  return pieowl;
}

Then use it in your components:

tsx

import { usePieowl } from '@/hooks/usePieowl';

function MyComponent() {
  const pieowl = usePieowl();
  
  useEffect(() => {
    pieowl.track('my_event', { foo: 'bar' });
  }, []);

  return <div>My Component</div>;
}