plausible-tracker-node

A backend tracker to interact with Plausible Analytics for nodejs

• Plausible Analytics Tracker for Nodejs
  • Features
  • Installation
  • Usage
    • Tracking page views
    • Tracking custom events and goals
  • Reference documentation

Features

• Minimum features from the official script, but as an NPM module
• Track goals and custom events
• Provide manual values that will be bound to the event
• Full typescript support

Installation

To install, simply run:

npm install plausible-tracker-node

yarn add plausible-tracker-node

Usage

To begin tracking events, you must initialize the tracker:

import {Tracker} from 'plausible-tracker-node';

const tracker = Tracker({
  domain: 'my-app.com',
});

new Tracker(options) accepts some options that you may want to provide:

| Option | Type | Description | Default | | -------------- | -------- | ----------------------------------------------------------------- | ------------------------ | | domain | string | Your site's domain, as declared by you in Plausible's settings | url.hostname | | hashMode | bool | Enables tracking based on URL hash changes. | false | | trackLocalhost | bool | Enables tracking on localhost | false | | apiHost | string | Plausible's API host to use. Change this if you are self-hosting. | 'https://plausible.io' |

The object returned from Plausible() contains the functions that you'll use to track your events. These functions are:

• trackPageview(options?: TrackingOptions): Tracks a single page view.
• trackEvent(eventName: string, options?: TrackingOptions): Tracks custom events and goals

For the complete documentation on these functions and their parameters, check out the reference documentation.

Tracking page views

To track a page view, use the trackPageview function provided

import {Tracker} from 'plausible-tracker-node';

const tracker = new Tracker();

// Track a page view
tracker.trackPageview();

You may also override the values you provided when initializing the tracker by passing a similar object as the first parameter.

This object takes the same options as the initialization one, plus the following:

| Option | Type | Description | Default | | --------------- | ------------------ | ------------------------------------------- | ------------------- | | url | string | Current page's URL. | location.href | | referrer | string or null | Referrer's address | document.referrer | | deviceWidth | number | User's device width for device tracking. | window.innerWidth | | clientUserAgent | string | Client User Agent for unique user counting. | | | clientIp | `string` | Client IP address for unique user counting. | | | props | object | Properties to be bound to the event. | undefined |

import {Tracker} from 'plausible-tracker-node';

const tracker = new Tracker({
  // Track localhost by default
  trackLocalhost: true,
});

// Override it on this call and also set a custom url
tracker.trackPageview({
  trackLocalhost: false,
  url: 'https://my-app.com/my-url',
});

The second parameter is an object with some options similar to the ones provided by the official Plausible script.

import {Tracker} from 'plausible-tracker-node';

const tracker = new Tracker();

// And wait for sending the event
await tracker.trackPageviewAndWait({});

Tracking custom events and goals

To track goals, all you need to do is call trackEvent and give it the name of the goal/event as the first parameter:

import {Tracker} from 'plausible-tracker-node';

const tracker = new Tracker();

// Tracks the 'signup' goal
tracker.trackEvent('signup');

Custom props can be provided with props parameter:

// Tracks the 'download' goal and provides a 'method' property.
tracker.trackEvent('download', {props: {method: 'HTTP'}});

As with trackPageview, you may also provide override values.

import Plausible from 'plausible-tracker'

const {trackEvent} = Plausible({
  trackLocalhost: false,
})

// Tracks the 'signup' goal with a callback, props and a different referrer.
trackEvent('signup', {
  trackLocalhost: true
  props: {
    variation: 'button A'
  }
});

Reference documentation

For the full method and type documentation, check out the reference documentation.