Plainflow Node.js Client

Our Node.js library lets you record analytics data from your node code.

This library is open-source, so you can check it out on Github.

All of our server-side libraries are built for high-performance, so you can use them in your web server controller code. This library uses an internal queue to make identify and track calls non-blocking and fast. It also batches messages and flushes asynchronously to our servers.

Getting Started

Install the Module

Run:

npm install --save plainflow

This will add our Node library module to your package.json. The module exposes an Plainflow constructor, which you need to initialize with your Secret Key, like so:

var Plainflow = require('plainflow');
var analytics = new Plainflow('YOUR_SECRET_KEY');

Of course, you’ll want to replace YOUR_SECRET_KEY with your actual Secret Key that you can find in the API Keys section of the Settings area.

This will create an instance of Plainflow that you can use to send data to Plainflow. The default initialization settings are production-ready and queue 20 messages before sending any requests. In development you might want to use development settings.

Identify

identify lets you tie a user to their actions and record traits about them. It includes a unique User ID and any optional traits you know about them.

We recommend calling identify a single time when the user’s account is first created, and only identifying again later when their traits change.

Exampleidentifycall:

plainflow.identify({
  userId: 'iutgo8ty9f',
  traits: {
    name: 'Mark Twain',
    email: 'mark.twain@plainflow.com',
    plan: 'Basic',
    friends: 42
  }
});

This call is identifying Mark by his unique User ID (the one you know him by in your database) and labeling him with name, email, plan and friends traits.

The identify call has the following fields:

user_id StringThe ID for this user in your database.
traits Object, optionalA dictionary of traits you know about the user. Things like: email, name or friends.
timestamp Date, optionalA Javascript date object representing when the identify took place. If the identify just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past make sure you to send a timestamp.
context Object, optionalA dictionary of extra context to attach to the call. Note: context differs from traits because it is not attributes of the user itself.
anonymous_id String, optionalAn ID to associated with the user when you don’t know who they are (eg., the anonymousId generated by plainflow.js)

Find details on the identify method payload in our Identify Documentation.

Track

track lets you record the actions your users perform. Every action triggers what we call an “event”, which can also have associated properties.

You’ll want to track events that are indicators of success for your site, like Signed Up, Item Purchased or Article Bookmarked.

To get started, we recommend tracking just a few important events. You can always add more later!

Example track call:

plainflow.track({
  userId: 'iutgo8ty9f',
  event: 'Item Purchased',
  properties: {
    revenue: 42.24,
    shippingMethod: '48h'
  }
});

This example track call tells us that your user just triggered the Item Purchased event with a revenue of $42.24 and chose your hypothetical ‘48h’ shipping.

track event properties can be anything you want to record. In this case, revenue and shipping method.

The track call has the following fields:

user_id StringThe ID for this user in your database.
event StringThe name of the event you’re tracking. We recommend human-readable names like Song Played or Status Updated.
properties Object, optionalA dictionary of properties for the event. If the event was Product Added, it might have properties like price or product.
timestamp Date, optionalA Javascript date object representing when the track took place. If the track just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past make sure you to send a timestamp.
context Object, optionalA dictionary of extra context to attach to the call. Note: context differs from traits because it is not attributes of the user itself.
anonymous_id String, optionalAn ID to associated with the user when you don’t know who they are (eg., the anonymousId generated byplainflow.js)

Find details on best practices in event naming as well as the track method payload in our Track Documentation.

Page

The page method lets you record page views on your website, along with optional extra information about the page being viewed.

If you’re using our client-side setup in combination with the Node.js library, page calls are already tracked for you by default. However, if you want to record your own page views manually and aren’t using our client-side library, read on!

Example page call:

plainflow.page({
  userId: 'iutgo8ty9f',
  category: 'Docs',
  name: 'Node Library',
  properties: {
    url: '/docs/developers/data-tracking-libraries/node.html',
    path: 'docs/developers/data-tracking-libraries/node/',
    title: 'Node Library',
    referrer: 'https:/www.plainflow.com'
  }
});

The page call has the following fields:

user_id StringThe ID for this user in your database.
category String, optionalThe category of the page. Useful for things like ecommerce where many pages often live under a larger category.
name String, optionalThe name of the of the page, for example Signup or Home.
properties Object, optionalA dictionary of properties of the page. A few properties specially recognized and automatically translated: url, title, referrer and path, but you can add your own too!
timestamp Date, optionalA Javascript date object representing when the track took place. If the track just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past make sure you to send a timestamp.
context Object, optionalA dictionary of extra context to attach to the call. Note:contextdiffers fromtraitsbecause it is not attributes of the user itself.
anonymous_idString, optionalAn ID to associated with the user when you don’t know who they are (eg.,the anonymousId generated byplainflow.js)

Find details on the page payload in our Page Documentation.

Alias

alias is how you associate one identity with another. This is an advanced method, but it is required to manage user identities successfully in_some_of our destinations.

Example alias call:

plainflow.alias({
  previousId: 'old_id',
  userId: 'new_id'
});

The alias call has the following fields:

user_id StringThe ID for this user in your database.
previous_id StringThe previous ID to alias from.

Here’s a full example of how we might use the alias call:

// the anonymous user does actions ...
plainflow.track({ userId: 'anonymous_user', event: 'Anonymous Event' })
// the anonymous user signs up and is aliased
plainflow.alias({ previousId: 'anonymous_user', userId: 'identified@gmail.com' })
// the identified user is identified
plainflow.identify({ userId: 'identified@gmail.com', traits: { plan: 'Free' } })
// the identified user does actions ...
plainflow.track({ userId: 'identified@gmail.com', event: 'Identified Action' })

For more details about alias, including the alias call payload, check out our Alias Documentarion.


Configuration

The second argument to the Plainflow constructor is an optional dictionary of settings to configure the module.

var plainflow = new Plainflow('YOUR_SECRET_KEY', {
  flushAt: 20,
  flushInterval: 10000
});
flush_at NumberThe number of messages to enqueue before flushing.
flush_interval NumberThe number of milliseconds to wait before flushing the queue automatically.

Development

You can use this initialization during development to make the library flush every time a message is submitted, so that you can be sure your calls are working properly before pushing to production.

var plainflow = new Plainflow('YOUR_SECRET_KEY', { flushAt: 1 });

Historical Import

You can import historical data by adding the timestamp argument to any of your method calls. This can be helpful if you’ve just switched to Plainflow.

Note: If you’re tracking things that are happening right now, leave out thetimestampand our servers will timestamp the requests for you.

Batching

Our libraries are built to support high performance environments. That means it is safe to use our Node library on a web server that’s serving hundreds of requests per second.

Every method you call does not result in an HTTP request, but is queued in memory instead. Messages are then flushed in batch in the background, which allows for much faster operation.

By default, our library will flush:

  • The very first time it gets a message.
  • Every 20 messages (controlled by options.flush_at ).
  • If 10 seconds has passed since the last flush (controlled by options.flush_interval )

There is a maximum of500kbper batch request and15kbper call.

If you don’t want to batch messages, you can turn batching off by setting theflushAtoption to1, like so:

var analytics = new Plainflow('YOUR_SECRET_KEY', { flushAt: 1 });

Batching means that your message might not get sent right away. But every method call takes an optional callback, which you can use to know when a particular message is flushed from the queue, like so:

plainflow.track({
  userId: 'iutgo8ty9f',
  event: 'Ultimate Played'
}, function(err, batch){
  if (err) // There was an error flushing your message...
  // Your message was successfully flushed!
});

You can also flush on demand. For example, at the end of your program, you need to flush to make sure that nothing is left in the queue. To do that, call the flush method:

plainflow.flush(function(err, batch){
  console.log('Flushed, and now this program can exit!');
});

Multiple Clients

Different parts of your application may require different types of batching. In that case, you can initialize multiple instances of Plainflow with different settings:

var Plainflow = require('plainflow');
var marketingPlainflow = new Plainflow('MARKETING_SECRET_KEY');
var appPlainflow = new Plainflow('APP_SECRET_KEY');

Troubleshooting

If you’re having trouble we have a few tips that help common problems.

No events in my debugger

  1. Double check that you’ve followed all the steps in the Quickstart.
  2. Make sure that you’re calling one of our API methods once the library is successfully installed.

Not using Plainflow yet? Get your free account here. 👈