Plainflow.js Web Tracker

Plainflow.js makes it dead simple to send your data to any tool without having to learn, test or implement a new API every time.

Getting Started

Head over to our plainflow.js QuickStart Guide which will help you implement plainflow.js on your site in just a few minutes.

Identify

The identify method is how you associate your users and their actions to a recognizable userId and traits.

Note: We recommend against using identify for anonymous visitors to your site. plainflow.js automatically retrieves an anonymousId from localStorage or assigns one for new visitors. It will be attached to all page and track events both before and after an identify.

identify method definition:

plainflow.identify([userId], [traits], [options], [callback]);

The identify call has the following fields:

userId optionalStringThe database ID for the user. If you don’t know who the user is yet, you can omit the userId and just record traits. You can read more about identities in the identify reference.
traits optionalObjectA dictionary of traits you know about the user, like their email or name. You can read more about traits in the identify reference.
options optionalObjectA dictionary of options. Note: If you do not pass a traits object, pass an empty object (ie, ‘{}’) before options
callback optionalFunctionA function that is executed after a short timeout, giving the browser time to make outbound requests first.

By default, traits are cached in the browser’s local storage and attached to each subsequent identify call. For example, you might do that when someone signs up for a newsletter but hasn’t yet created an account on your site:

Example identify with hard-coded information:

plainflow.identify({
  nickname: 'MTwain',
  favoriteCompiler: 'A-0',
  industry: 'Publishing'
});

and when the user completes signup:

plainflow.identify('4356wrevff32789fre42', {
  name: 'Mark Twain',
  email: 'mark.twain@plainflow.com'
});

The traits object for the second call will also include nickname, favoriteCompiler, and industry.

You may omit both traits and options passing the callback as the second argument if

plainflow.identify('12091906-01011992', function(){
  // Do something after the identify request has been sent
});

Track

The track method lets you record any actions your users perform.

track method definition:

plainflow.track(event, [properties], [options], [callback]);

The track call has the following fields:

eventStringThe name of the event you’re tracking. You can read more about the track method and what event names we recommend.
properties optionalObjectA dictionary of propertiesfor the event. If the event was'Added to Cart', it might have properties like price and productType.
options optionalObjectA dictionary of options. Note: If you do not pass a properties object, pass an empty object (ie, ‘{}’) before options
callback optionalFunctionA function that is executed after a short timeout, giving the browser time to make outbound requests first.

The only required argument to track in plainflow.js is an event name string. You can read more about how we recommend naming your events.

Example track call:

plainflow.track('Article Completed', {
  title: 'How to Create a Tracking Plan',
  course: 'Intro to Analytics'
});

The only required argument to track in plainflow.js is an event name string. Read more about how we recommend naming your events.

Page

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

You may call it more than once if needed, (eg, on virtual page changes in a single page app).

A page call is included by default as the final line in the plainflow.js snippet. You may modify this page call within the guidelines below.

page method definition:

plainflow.page([category], [name], [properties], [options], [callback]);

The page call has the following fields:

category optionalStringThe category of the page. Useful for cases like ecommerce where many pages might live under a single category. Note: if you pass only one string to page it is assumed to be name. You must include a name to send a category.
name optionalStringThe name of the page.
properties optionalObjectA dictionary of properties of the page. Note:url, title, referrer and path are collected automatically! Additionally this defaults to a canonical url, if available, and falls back to document.location.href.
options optionalObjectA dictionary of options. Note: If you do not pass a properties object, pass an empty object (ie, ‘{}’) before options
callback optionalFunctionA function that is executed after a short timeout, giving the browser time to make outbound requests first.

Default Properties

A few properties are automatically added to each page call.

plainflow.page('Product');

We will translate that to the following without any extra work from you:

plainflow.page('Product', {
  title: 'Plainflow workflows',
  url: 'https://www.plainflow.com/workflows',
  path: '/workflows',
  referrer: 'https://www.plainflow.com/'
});

You can override these values. For example:

plainflow.page('Product', {
  title: 'Product workflows v2',
  path: '/workflows/view'
});

Will be translated to:

plainflow.page('Product', {
  title: 'Plainflow workflows v2',
  url: 'https://www.plainflow.com/workflows',
  path: '/workflows/view',
  referrer: 'https://www.plainflow.com/'
});

Alias

The alias method combines two previously unassociated user identities. Aliasing is generally handled automatically when you identify a user.

alias method definition:

plainflow.alias(userId, [previousId], [options], [callback]);

The alias call has the following fields:

userIdStringThe new user ID you want to associate with the user.
previousId optionalStringThe previous ID that the user was recognized by. This defaults to the currently identified user’s ID.
optionsoptionalObjectA dictionary of options. Note: If you do not pass a properties object, pass an empty object (ie, ‘{}’) before options
callback optionalFunctionA function that is executed after a short timeout, giving the browser time to make outbound requests first.

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

Ready

The ready method allows you to pass in a callback that will be called as soon as plainflow.js has completed initialization. It’s like jQuery’s ready method.

Code inside this function will only be executed after ready has been emitted.

ready method definition:

plainflow.ready(callback);

The ready method has the following fields:

| callback | Function | A function to be executed after plainflow.js has completed initialization. | | :— | :— | :— |

Querystring API

plainflow.js can trigger track and identify events based on the URL querystring. This is helpful for tracking email click throughs, social media clicks, and digital advertising as well as for cross-domain tracking.

Here are the query parameters to use:

paramdescriptiontriggers
pfl_uidThe userId to pass to an identify call.This will trigger an identify call.
pfl_eventThe event name to pass to a track call.This will trigger a track call.
pfl_aidThe anonymousId to set for the user.This will trigger an plainflow.user().anonymousId() call.
pfl_prop_<property>A property to pass to the track callThis won’t implicitly trigger an event and is dependent on you also passing pfl_event- this property will be included in the resulting track call
pfl_trait_<trait>A trait to pass to the identify callThis won’t implicitly trigger any call and is dependent on you also passing pfl_uid - this trait will be included in the resulting identify call

So for example, with this URL:

http://www.plainflow.com/?pfl_uid=123456789abcd&pfl_event=Clicked%20Email&pfl_aid=abc123&pfl_prop_emailCampaign=First+Touch&pfl_trait_name=John+Doe.

it would trigger the following events on the page:

plainflow.identify('123456789abcd', { name: 'John Doe' });
plainflow.track('Clicked Email', { 'emailCampaign': 'First Touch' });
plainflow.user().anonymousId('abc123');

You can pass up to one of each trigger parameter as shown in the example above.

User & Group Information

Once plainflow.js is loaded, executing the user or group method functions will return information about the currently identified user.

Note: To ensure these methods are available, wrap any reference to user() or group() in a ready function block.

Examples:

plainflow.ready(function() {

  var user = plainflow.user();
  var id = user.id();
  var traits = user.traits();

});
plainflow.ready(function() {

  var group = plainflow.group();
  var id = group.id();
  var traits = group.traits();

});

Clearing Traits

Passing an empty object to the traits object will clear all cached traits for a User or Group. Remember, traits are cached by default by identify and group methods. You can clear the traits object for the user or group by passing traits an empty object:

plainflow.user().traits({});
plainflow.group().traits({});

Reset / Logout

Calling reset will reset the id, including anonymousId, and clear traits for the currently identified user and group.

plainflow.reset();

Anonymous ID

plainflow.js generates a UUID and sets this as anonymousId for all new visitors to your site.

Example:

pfl_anonymous_id=%2239ee7ea5-b6d8-4174-b612-04e1ef3fa952

Retrieving the Anonymous ID

Retrieve the of the current user anonymousId:

plainflow.user().anonymousId();

Setting the Anonymous ID

Override the assigned anonymousId for the current user:

plainflow.user().anonymousId('YOUR-AN0N-UID123456');

Or in the options object of identify, page, or track calls, like this:

plainflow.identify('pfl9867t67ft', {
  name: 'Albert'
}, {
  anonymousId: 'YOUR-AN0N-UID123456'
});
plainflow.page({}, { anonymousId: 'YOUR-AN0N-UID123456' });
plainflow.track('Email Clicked', {
  callToAction: 'Signup'
}, {
  anonymousId: 'YOUR-AN0N-UID123456'
});

Refreshing the Anonymous ID

A user’s anonymousId will refresh on any of the following conditions:

  • A user clears their cache or cookies
  • plainflow.reset() is called during in the user’s browser session
  • plainflow.identify() is called with a userId that differs from the current userId

Debug

Calling the debug method will turn on debug mode, logging helpful messages to the console. You’ll have to refresh the page after invoking debug to see the messages.

Enable:

plainflow.debug();

Disable:

plainflow.debug(false);

trackLink is a helper method that attaches the track call as a handler to a link. With trackLink a small timeout (300 ms) is inserted to give the track call more time. This is useful when a page would redirect before the track method could complete all requests.

trackLink method definition:

plainflow.trackLink(element, event, [properties])
element(s)Element or ArrayDOM element to be bound with track method. You may pass an array of elements or jQuery objects. Note: This must be an element, not a CSS selector.
eventString or FunctionThe name of the event, passed to the track method. Or a function that returns a string to be used as the name of the track event.
properties optionalObject or FunctionA dictionary of properties to pass with the track method. Or a function that returns an object to be used as the properties of the event.

Example:

var link = document.getElementById('subscribe-link');

plainflow.trackLink(link, 'Clicked Subscribe Link', {
  plan: 'Pro'
});

Track Form

trackForm is a helper method that binds a track call to a form submission. With trackForm a small timeout (300 ms) is inserted to give the track call more time. Useful when a page would redirect before the track method can complete all requests.

plainflow.trackForm(form, event, [properties])
form(s) Element or ArrayElement or ArrayThe form element to track or an array of form elements or jQuery objects. Note: trackForm takes an element, not a CSS selector.
eventString or FunctionThe name of the event, passed to the trackmethod. Or a function that returns a string to be used as the name of the track event.
properties optionalObject or FunctionA dictionary of properties to pass with the track method. Or a function that returns an object to be used as the properties of the event.

Example:

var form = document.getElementById('signup-form');

plainflow.trackForm(form, 'Signed Up', {
  plan: 'Basic',
  revenue: 9.90
});

Extending Timeout

The timeout method will set the length (in milliseconds) of the callbacks and helper functions:

plainflow.timeout(500);

Set the timeout to 500ms. This is helpful if you have multiple scripts that need to fire in your callback or trackLink, trackForm helper function.

Performance

The plainflow.js library are loaded with the HTML script async tag. This also means that Plainflow methods are fired asynchronously, so you should adjust your code accordingly if you require that events be sent from the browser in a particular order.

Cross-Subdomain Analytics

Plainflow.js tracks across subdomains out of the box.

Anonymizing IP

We collect IP address for client-side events automatically.

Passing a value for options.context.ip will prevent our server from recording the IP address associated with the request.

Example:

plainflow.track("Live Chat Opened", {}, { context: { ip: "0.0.0.0" }});

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