JavaScript (Node / Generic)

@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 instead.

Installation

npm install @pieowl/sdk

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

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

import { pieowl } from './pieowl';

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

Usage

Tracking events

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

import { pieowl } from './pieowl';

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

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

pieowl.track('invoice_paid', { profileId: 'user_123', plan: 'pro' });

Identifying users

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

import { pieowl } from './pieowl';

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:

import { pieowl } from './pieowl';

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.

import { pieowl } from './pieowl';

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.

import { pieowl } from './pieowl';

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

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 for how purchases are credited, and Revenue tracking for checkout flows.

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

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

Create or update a group:

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):

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

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

import { pieowl } from './pieowl';

pieowl.clear()

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