# React

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







Good to know [#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 [#installation]

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

  ```bash
  npm install @pieowl/web
  ```

  Step 2: Initialize [#step-2-initialize]

  Create a shared Pieowl instance in your project:

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

  <CommonSdkConfig />

  <WebSdkConfig />

  Step 3: Usage [#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>;
  }
  ```
</Steps>

Usage [#usage]

Tracking events [#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 [#identifying-users]

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

<PersonalDataWarning />

```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 [#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 [#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 [#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 [#working-with-groups]

Groups let you track analytics at the account or company level. See the [Groups guide](/docs/get-started/groups) 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 [#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 [#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](/docs/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 [#optional-create-a-hook]

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

```ts title="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>;
}
```