JavaScript Integration

This package helps with integrating Userlist into Node.js applications for server side tracking.

Installation

To install this package, use one of the commands corresponding to your package manager.

Via NPM:

1
npm install @userlist/push

Via Yarn:

1
yarn add @userlist/push

Configuration

The only required configuration is the Push API key. You can get your Push API key via the Push API settings in your Userlist account.

Configuration values can either be set via the constructor or as environment variables. The environment take precedence over configuration values from the constructor.

Configuration via environment variables:

1
USERLIST_PUSH_KEY=401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39

Configuration via an constructor:

1
2
3
4
5
import Userlist from "@userlist/push";

const userlist = new Userlist({
  pushKey: "401e5c498be718c0a38b7da7f1ce5b409c56132a49246c435ee296e07bf2be39",
});

Usage

TIP: All of the following methods return promises. In order to decouple your application from our service, we recommend to not await them. If you decide to still await them, make sure to add proper error handling.

Tracking Users

To send user data into Userlist, use the userlist.users.push method. This method will create a new user if the user doesn’t exist yet, or update the existing user if it does. Properties that aren’t present in the payload are ignored and remain unchanged.

1
2
3
4
5
6
7
8
userlist.users.push({
  identifier: user.id,
  email: user.email,
  properties: {
    first_name: user.first_name,
    last_name: user.last_name,
  },
});

It’s also possible to delete a user from Userlist, using the userlist.users.delete method.

1
userlist.users.delete({ identifier: user.id, email: user.email });

Tracking Companies

To send company data into Userlist, use the userlist.companies.push method. This method will create a new company if the company doesn’t exist yet, or update the existing company if it does. Properties that aren’t present in the payload are ignored and remain unchanged.

1
2
3
4
5
6
7
8
userlist.companies.push({
  identifier: company.id,
  name: company.name,
  properties: {
    plan: company.plan,
    trial_ends_at: company.trial_ends_at,
  },
});

It’s also possible to delete a company from Userlist, using the userlist.companies.delete method.

1
userlist.companies.delete({ identifier: company.id });

Tracking Relationships

To create or update relationships between users and companies, use the userlist.relationships.push method. You need to specify both the user and company identifiers.

1
2
3
4
5
6
7
userlist.relationships.push({
  user: user.id,
  company: company.id,
  properties: {
    role: "admin",
  },
});

It’s also possible to delete a relationship using the userlist.relationships.delete method.

1
2
3
4
userlist.relationships.delete({
  user: user.id,
  company: company.id,
});

Tracking Events

To track custom events use the userlist.events.push method.

1
2
3
4
5
6
7
userlist.events.push({
  name: "project_created",
  user: user.id,
  properties: {
    project_name: project.name,
  },
});

Sending Messages

To send messages to your users, use the userlist.messages.push method. You can specify the user, template name, and any properties needed for the message template.

1
2
3
4
5
6
7
userlist.messages.push({
  user: user.id,
  template: "welcome_message",
  properties: {
    project_name: project.name,
  },
});