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:
import Plausible from 'plausible-tracker'
const plausible = Plausible({
domain: 'my-app.com'
})
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 goals -
enableAutoPageviews()
: 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
import Plausible from 'plausible-tracker'
const { trackPageview } = Plausible()
// Track a page view
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 |
import Plausible from 'plausible-tracker'
const { trackPageview } = Plausible({
// Track localhost by default
trackLocalhost: true,
})
// Override it on this call and also set a custom url
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 Plausible from 'plausible-tracker'
const { trackPageview } = Plausible()
// And override it on this call
trackPageview({}, { callback: () => console.log("Done!") })
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.
import Plausible from 'plausible-tracker'
const { enableAutoPageviews } = Plausible()
// This tracks the current page view and all future ones as well
enableAutoPageviews()
If your app uses URL hashes to represent pages, set hashMode
to true
:
import Plausible from 'plausible-tracker'
const { enableAutoPageviews } = Plausible({
hashMode: true
})
// Hash changes will also trigger page views
enableAutoPageviews()
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()
:
import Plausible from 'plausible-tracker'
const { enableAutoPageviews } = Plausible()
const cleanup = enableAutoPageviews()
// ...
// Remove event listeners and restore history.pushState
cleanup()
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 Plausible from 'plausible-tracker'
const { trackEvent } = Plausible()
// Tracks the 'signup' goal
trackEvent('signup')
Custom props can be provided using the second parameter:
// Tracks the 'download' goal and provides a 'method' property.
trackEvent('download', { props: { method: 'HTTP' } })
As with trackPageview
, you may also provide override values but now through the third parameter:
import Plausible from 'plausible-tracker'
const { trackEvent } = Plausible({
trackLocalhost: false,
})
// Tracks the 'signup' goal with a callback, props and a different referrer.
trackEvent(
'signup',
{
callback: () => console.log('done'),
props: {
variation: 'button A'
}
},
{ trackLocalhost: true }
);
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.
import Plausible from 'plausible-tracker'
const { enableAutoOutboundTracking } = Plausible()
// Track all existing and future outbound links
enableAutoOutboundTracking()
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()
:
import Plausible from 'plausible-tracker'
const { enableAutoOutboundTracking } = Plausible()
const cleanup = enableAutoOutboundTracking()
// ...
// Remove event listeners and disconnect the MutationObserver
cleanup()
Opt out and exclude yourself from the analytics
Since plausible-tracker is bundled with your application code, using an ad-blocker to exclude your visits isn't an option. Fortunately Plausible has an alternative for this scenario: plausible-tracker will not send events if localStorage.plausible_ignore
is set to "true"
.
More information about this method can be found in the Plausible documentation.
Reference documentation
For the full method and type documentation, check out the reference documentation.