tracker/npm_package/README.md
Add Plausible Analytics to your website.
Important: This library only works in browser environments. When using server-side rendering (SSR), the
initandtrackfunctions will not work as they rely on browser APIs. Make sure to only initialize and track events on the client side.
With npm:
npm install @plausible-analytics/tracker
To begin tracking events, you must initialize the tracker:
import { init } from '@plausible-analytics/tracker'
init({
domain: 'my-app.com'
})
See also plausible.d.ts for typescript types.
| Option | Description | Default |
|---|---|---|
domain | Required Your site's domain, as declared by you in Plausible's settings. | |
endpoint | The URL of the Plausible API endpoint. See proxying guide at https://plausible.io/docs/proxy/introduction | "https://plausible.io/api/event" |
autoCapturePageviews | Whether to automatically capture pageviews. | true |
hashBasedRouting | Whether the page uses hash based routing. Read more at https://plausible.io/docs/hash-based-routing | false |
outboundLinks | Whether to track outbound link clicks. | false |
fileDownloads | Whether to track file downloads. | false |
formSubmissions | Whether to track form submissions. | false |
captureOnLocalhost | Whether to capture events on localhost. | false |
logging | Whether to log on ignored events. | true |
customProperties | Object or function that returns custom properties for a given event. | {} |
transformRequest | Function that allows transforming or ignoring requests | |
bindToWindow | Binds track to window.plausible which is used by Plausible installation verification tool to detect whether Plausible has been installed correctly. If bindToWindow is set to false, the installation verification tool won't be able to automatically detect it on your site. | true |
customPropertiesTo track a custom property with every page view, you can use the customProperties configuration option:
init({
domain: 'my-app.com',
customProperties: { content_category: 'news' }
})
customProperties can also be a dynamic function:
init({
domain: 'my-app.com',
customProperties: (eventName) => ({ title: document.title })
})
To track a custom event, call track and give it the name of the event. Custom properties can be passed as a second argument:
import { track } from '@plausible-analytics/tracker'
track('signup', { props: { tier: 'startup' } })
To mark an event as non-interactive so it would not be counted towards bounce rate calculations, set interactive option:
track('autoplay', { interactive: false })
To track an event with revenue information, do:
import { track } from '@plausible-analytics/tracker'
track('Purchase', { revenue: { amount: 15.99, currency: 'USD' } })
More information can be found in ecommerce revenue tracking docs
When calling track, you can pass in a custom callback.
import { track } from '@plausible-analytics/tracker'
track('some-event', {
callback: (result) => {
if (result?.status) {
console.debug('Request to plausible done. Status:', result.status)
} else if (result?.error) {
console.log('Error handling request:', result.error)
} else {
console.log('Request was ignored')
}
}
})
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.