Carbon.Plausible Package for Neos CMS

Easily integrate Plausible Analytics into your Neos site.

Introduction

Plausible is a lightweight and open-source website analytics tool. It doesn't use cookies and is fully compliant with GDPR, CCPA, and PECR. This plugin is meant to remove all friction from adding the Plausible Analytics tracking script code to your Neos site. All you need to do is add the tracking code generated by Plausible to your Neos Settings.yaml file or the site settings in the Neos UI.

Features

• Multi-site compatibility
• Neos UI integration for embedded statistics and browser tracking opt-out
• Site-specific tracking code and shared link configuration
• Can be enabled or disabled globally
• Proxies the JavaScript and event API requests from Plausible
• Automatically tracks 404 responses as custom events

Multi-site compatibility

If you run a multi-site setup, we got you covered! You can set different trackings for the sites based on the root node name.

Neos UI integration

The package integrates directly into the Neos UI instead of adding a separate backend module:

• If a sharedLink is configured for the current site, a Plausible button on the Neos start page opens the embedded statistics in a dialog.
• The Plausible section in the site settings allows editors to configure a site-specific tracking code and shared link.
• The same section contains a button to enable or disable tracking for the current browser.

Site-specific values configured in the Neos UI take precedence over the values from Settings.yaml.

NodeType mixins for disable tracking on a document or set custom events

This package contains two mixins:

• Carbon.Plausible:Mixin.CustomEvent: This allows you to set custom events to a document via the inspector. Of course, you can do this also directly in your JavaScript or Fusion
• Carbon.Plausible:Mixin.DoNotTrack: This allows you to disable the tracking for a specific document

Opt out and exclude your visits from the analytics

By default, Plausible Analytics tracks every visitor to your website. When you're working on your site, you might not want to record your own visits and page views. To prevent counting your visits, you can set a special localStorage flag in the browser. Here's how.

• Go to your-domain.tld/~pls/disable-tracking. This sets the flag and redirects the visitor to the homepage. Great for people without access to the Neos UI.
• As an editor, use the button in the Plausible section of the site settings.
• Add the component Carbon.Plausible:Component.Toggle to a document and click the button.
• You can do this also by yourself by following the excluding guide on plausible.io

Installation

Run the following command in your site package

composer require --no-update carbon/plausible

Then run composer update in your project root.

Configuration

Single-site setup

If you have a single-site setup, configure the integration under Carbon.Plausible.default in your Settings.yaml:

Carbon:
  Plausible:
    default:
      trackingCode: https://plausible.io/js/pa-XXXXXXXX.js
      sharedLink: https://plausible.io/share/example.com?auth=abcdefghijklmnopqrstu

The tracking code can be the complete snippet generated by Plausible, its external <script> tag, or just the script URL. The sharedLink is optional and enables the statistics button in the Neos UI.

The following global settings are available under Carbon.Plausible:

Key	Default	Type	Description
enable	true	bool	Enables or disables the Plausible integration.
renderInlineScriptTag	true	bool	Renders the inline initialization script. Disable it if you initialize Plausible in your own templates.
set404Event	true	bool	Sends a 404 custom event for HTTP status codes from 400 to 499.
default.trackingCode	null	string	The tracking code, external script tag, or script URL generated by Plausible.
default.sharedLink	null	string	A public or private shared link used to display embedded statistics on the Neos start page.

Multi-site setup

If you run multiple sites in one Neos installation, configure them under Carbon.Plausible.sites in your Settings.yaml. Values from Carbon.Plausible.default are used as fallbacks.

Example:

Carbon:
  Plausible:
    sites:
      myfirstsite:
        trackingCode: https://plausible.io/js/pa-XXXXXXXX.js
        sharedLink: https://plausible.io/share/domain.com?auth=abcdefghijklmnopqrstu
      mysecondsite:
        trackingCode: https://plausible.io/js/pa-YYYYYYYY.js

The key of the site (e.g. myfirstsite) is the root node name found under Administration » Sites Management.

Fusion Components

Carbon.Plausible:Component.TrackingCode

The main Fusion component is Carbon.Plausible:Component.TrackingCode. This component gets included into Neos.Neos:Page under the path plausibleTrackingCode. To send a custom event for a specific document prototype, configure eventName and optionally eventJSON:

prototype(Vendor.Site:Document.Signup) < prototype(Neos.Neos:Page) {
  plausibleTrackingCode {
    eventName = 'Signup'
    eventJSON = '{props:{plan:"Business"}}'
    }
}

Carbon.Plausible:Component.Toggle

Carbon.Plausible:Component.Toggle is a small component to let the user if he wants to opt-out from tracking.