Plausible Analytics Tracker
Frontend library to interact with Plausible Analytics.
Features
- Less than 1kb!
- Same features as the official script, but as an NPM module
- Automatically track page views in your SPA apps
- 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 yarn add plausible-tracker
Usage
To begin tracking events, you must initialize the tracker:
Plausible()
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 | location.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()
: Tracks a single page view.trackEvent()
: Tracks custom events and goalsenableAutoPageviews()
: Enables automatic page view tracking for SPAs
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
// Track a page viewtrackPageview
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 |
// Override it on this call and also set a custom urltrackPageview
The second parameter is an object with some options similar to the ones provided by the official Plausible script.
// And override it on this calltrackPageview,
Automatically tracking page views
If your app is a SPA that uses JS-based routing, you'll need to use browser events to manually track page views. A built-in function enableAutoPageviews
enables automatic tracking for you so you don't need to write custom logic.
// This tracks the current page view and all future ones as wellenableAutoPageviews
If your app uses URL hashes to represent pages, set hashMode
to true
:
// Hash changes will also trigger page viewsenableAutoPageviews
The way it works is by overriding history.pushState
and attaching event listeners to popstate
and hashchange
(only if you set hashMode
to true
). If your frontend framework uses other methods to manage navigation, you might want to write your own logic using trackPageview
to manually trigger page views.
Cleaning up the event listeners
When you call enableAutoPageviews()
, it adds some event listeners and overrides history.pushState
. To remove them and restore history.pushState
, call the cleanup function returned by enableAutoPageviews()
:
// ... // Remove event listeners and restore history.pushStatecleanup
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:
// Tracks the 'signup' goaltrackEvent'signup'
Custom props can be provided using the second parameter:
// Tracks the 'Download' goal and provides a 'method' property.trackEvent'signup',
As with trackPageview
, you may also provide override values but now through the third parameter:
// Tracks the 'signup' goal with a callback, props and a different referrer.trackEvent 'signup', , ;
Outbound link click tracking
You can also track all clicks to outbound links using enableAutoOutboundTracking
.
For details on how to setup the tracking, visit the docs.
This function adds a click
event listener to all a
tags on the page and reports them to Plausible. It also creates a MutationObserver that efficiently tracks node mutations, so dynamically-added links are also tracked.
// Track all existing and future outbound linksenableAutoOutboundTracking
Cleaning up the event listeners
When you call enableAutoOutboundTracking()
, it adds some event listeners and initializes a MutationObserver
. To remove them, call the cleanup function returned by enableAutoOutboundTracking()
:
// ... // Remove event listeners and disconnect the MutationObservercleanup
Reference documentation
For the full method and type documentation, check out the reference documentation.