# JavaScript (Node / Generic)

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





`@pieowl/sdk` is the core SDK. Use it on the server, or in any JavaScript runtime that isn't a browser. For websites, use the [Web SDK](/docs/sdks/web) instead.

Installation [#installation]

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

  <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/sdk
      ```
    </CodeBlockTab>

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

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

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

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

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

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

  Keep the client secret on the server. Never ship it to the browser.

  Options [#options]

  <CommonSdkConfig />

  Step 3: Usage [#step-3-usage]

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

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

Usage [#usage]

Tracking events [#tracking-events]

Call `pieowl.track()` with an event name and optional properties.

```ts title="index.ts"
import { pieowl } from './pieowl';

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

To track an event for a specific user, pass `profileId`:

```ts title="index.ts"
pieowl.track('invoice_paid', { profileId: 'user_123', plan: 'pro' });
```

Identifying users [#identifying-users]

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

<PersonalDataWarning />

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

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="index.js"
import { pieowl } from './pieowl';

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="index.js"
import { pieowl } from './pieowl';

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="index.js"
import { pieowl } from './pieowl';

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

Tracking revenue [#tracking-revenue]

Call `purchase()` when your server learns the payment went through. Send your 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. Send the visitor's `deviceId` (from `pieowl.getDeviceId()` in the browser), and the purchase is credited to their visit. See [Revenue attribution](/docs/revenue-attribution) for how purchases are credited, and [Revenue tracking](/docs/revenue-tracking) for checkout flows.

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

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

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

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.

**Create or update a group:**

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

pieowl.upsertGroup({
  id: 'org_acme',
  type: 'company',
  name: 'Acme Inc',
  properties: { plan: 'enterprise' },
});
```

**Assign the current user to a group** (call after `identify`):

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

pieowl.setGroup('org_acme');
// or multiple groups:
pieowl.setGroups(['org_acme', 'team_eng']);
```

Once set, every later `track()` call includes the group IDs.

Clearing user data [#clearing-user-data]

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

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

pieowl.clear()
```

Server-side tips [#server-side-tips]

* **Location:** Pieowl looks up the country and city from the request IP. On a server, that is your server's IP. To use the visitor's IP, forward it in the `pieowl-client-ip` header: `pieowl.api.addHeader('pieowl-client-ip', visitorIp)`. Headers are set on the instance, so on a server that handles many visitors, create one instance per request for this (see [Express](/docs/sdks/express#server-side-events)).
* **Shared instances:** `identify()` and `setGroup()` store the user on the instance. On a server that handles many users, pass `profileId` on each `track()` call instead.