Script options

Most options can be switched on in Site settings → General → Tracking and are delivered with your site's script automatically. You can also pass them in code to plausible.init(); values you pass there override the dashboard settings.

<script>
  window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};
  plausible.init({
    outboundLinks: true,
    fileDownloads: { fileExtensions: ['pdf', 'zip'] },
    customProperties: { plan: 'pro' },
  })
</script>

Options for plausible.init()

Option	Default	Description
outboundLinks	from settings	Send Outbound Link: Click with a url property when a visitor clicks a link to another host.
fileDownloads	from settings	true or { fileExtensions: [...] }. Sends File Download with the file url (query string removed).
formSubmissions	from settings	Send Form: Submission with a path property when a valid form is submitted.
hashBasedRouting	from settings	Include the #hash in page paths and record a pageview on hashchange.
taggedEvents	from settings	Turn on CSS class tagging.
autoCapturePageviews	true	Set to false to send pageviews yourself (see manual pageviews).
captureOnLocalhost	false	Record events from localhost, 127.* and file: pages.
customProperties	none	An object, or a function (eventName) => object, merged into the properties of every event.
include / exclude	none	Arrays of path patterns; only track pages that match include, never track pages that match exclude. See Excluding traffic.
transformRequest	none	A function that receives the event payload and returns a modified payload, or a falsy value to drop the event.
logging	false	Log ignored events to the console with the reason.
bindToWindow	true	Set to false to avoid exposing window.plausible after initialisation.
domain, endpoint	your site	Override the site domain or the URL events are sent to (for example, a proxy).

The default file extensions are pdf, xlsx, docx, txt, rtf, csv, exe, key, pps, ppt, pptx, 7z, pkg, rar, gz, zip, avi, mov, mp4, mpeg, wmv, midi, mp3, wav, wma, dmg.

Sending custom events

plausible('Signup')
plausible('Download', { props: { format: 'pdf' } })
plausible('Purchase', { revenue: { amount: 49.5, currency: 'GBP' } })

The second argument accepts:

Key	Description
props	Custom properties for this event.
revenue	{ amount, currency } for revenue goals.
interactive	Set to false for events that shouldn't count as engagement (they won't stop a visit being a bounce).
url	Record the event against a different URL than the current page.
callback	Called after sending with { status }, { error } or { ignored: true }.

To count an event as a conversion, add a goal for it.

Tagged events

With tagged events on, you can track clicks without writing JavaScript by adding CSS classes. The class plausible-event-name=<Event> sets the event name, and plausible-event-<property>=<value> adds properties. Use + for spaces.

<a href="/signup" class="button plausible-event-name=Signup+Click plausible-event-position=hero">Get started</a>

This sends Signup Click with position: hero (and the link's url). Classes work on links, buttons and other elements (the script checks the clicked element and up to four parents), and on <form> elements, where the event is sent on submit.

Manual pageviews

Set autoCapturePageviews: false (or turn on Manual pageviews) and send pageviews yourself — useful to strip IDs from URLs:

plausible('pageview', { url: location.origin + '/users/:id' })

404 pages

PlainAnalytics doesn't detect error pages by itself. Add this to your 404 template and create a custom event goal named 404:

<script>plausible('404', { props: { path: document.location.pathname } })</script>

Engagement

The script measures how far visitors scroll and how long a page is visible and focused, and sends this once when they leave the page. This powers scroll depth and time on page. Engagement data doesn't count towards your pageview usage.

Legacy script URLs

If you're migrating, https://plainwebanalytics.com/js/script.js (and /js/plausible.js) also work with a data-domain attribute. Features are chosen with filename extensions, for example script.outbound-links.file-downloads.js:

<script defer data-domain="example.com" src="https://plainwebanalytics.com/js/script.hash.outbound-links.js"></script>

Supported extensions: hash, outbound-links, file-downloads, tagged-events, pageview-props, manual, local, exclusions, revenue, compat and 404. Use data-api to send events to a different endpoint. New installations should use the site-specific script instead.