Nocturnal Parakeet Monitor

    plausible-tracker
    TypeScript icon, indicating that this package has built-in type declarations

    0.3.8 • Public • Published

    Plausible Analytics Tracker

    NPM Bundle

    Build Status codecov Netlify Status

    dependencies Status devDependencies Status

    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:

    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.

    Keywords

    none

    Install

    npm i plausible-tracker

    DownloadsWeekly Downloads

    22,619

    Version

    0.3.8

    License

    MIT

    Unpacked Size

    153 kB

    Total Files

    27

    Last publish

    Collaborators

    • maronato
    • markosaric
    • ukutaht