Umami Analytics Integration Plugin

For users that value privacy for both themselves and their users, Umami Analytics is a stellar choice; since it is self-hosted you have full control of the data collected, it doesn't make use of cookies, and it anonymizes all of its tracking data, making it fully GDPR-compliant. Despite this, it still provides the analytics essentials, including tracking pageviews, country of origin and devices used by your site visitors, so it's a valuable tool for fine-tuning your website to improve the site experience and track how your content is performing.

This plugin allows you to easily connect your Publii site to your Umami installation without needing to manually enter tracking markers or other elements. It also provides multiple additional functions to give you full control of your analytics content.

Setting-Up Umami and Generating a Data Website ID

Umami is self-hosted; this means that the tracking data that is collected via the tracking scripts that this plugin applies will not be sent to a third-party. Instead, you will need to setup Umami on a server. This could potentially be setup on the same server that you are using for Publii, or on a separate server; you will simply need to ensure that the Data Host option in the plugin options is pointed to your Umami script (the plugin options will be covered later in this guide).

The second required option for this plugin to work is the Data Website ID. This is a unique tracking code that is generated by your Umami installation once you have added a website to the admin panel.

For information on how to setup your Umami installation, visit the Install section of Umami's documentation.

You can also learn how to generate your tracking code to be added to the Data Website ID option in the plugin via the Collect Data section of Umami's documentation.

Installing the Plugin

The Umami Analytics plugin is not included in the standard Publii installation; in order to get access to the plugin, it will first need to be downloaded via the Publii Plugin Marketplace, then installed through the Publii app. To do so, follow these steps:

Open Publii’s App Menu by clicking on the three dots icon in the top-right of the app UI; this icon is always visible except when creating or editing a new post, tag or menu.
In the menu that appears, click on Plugins. This will take you to the Plugins page where you can see any plugins that you have installed.
Click on the Get More Plugins box to open your browser at the Publii Plugins Marketplace, which displays all the currently available plugins.
Click on the Umami Analytics box to open the description page. From here, you can click the Download button under the description to download the zipped install package.
Once the download has finished, in the Plugins screen of the Publii app, click on the Install Plugin button at the top of the page. This will open your file explorer; browse to the folder where you downloaded the plugin file, and select it. Publii will automatically install the plugin and add it to the list of available plugins in both the Plugins and Tools & Plugins pages in Publii.

Activating the Plugin

The plugin can be enabled by clicking the switcher button in the Umami Analytics box of the Tools & Plugins section of the Publii app. If the switcher changes from grey to blue. then the plugin is enabled. You will need to enter both your Data Website ID (that is, the tracking code generated by Umami) and the Data host (the URL to your Umami installation) before the plugin can function correctly; to do this, open the Plugin Options screen by clicking anywhere in the Umami Analytics box anywhere except on the switcher button; this will open the Plugin options screen, where you can add the necessary information. For the other options contained in this section, more details may be found in the next section of this guide.

Umami Analytics Plugin Options

This plugin includes a set of options that allows you to fine-tune the way that Umami collects data on your site, as well as some additional options for testing. The available options are:

Configuration

Data Website ID (required) - One of the required options; this is the tracking code that can be generated after adding a site to your Umami admin panel; it is used to tell Umami that the site belongs to you. The tracking code should look something like this: "4fb7fa4c-5b46-438d-94b3-3a8fb9bc2e8b"
Data Host (required) - This field tells the plugin where to send the data i.e. where your Umami installation is. Enter the full URL to your Umami installation's umami.js file in this field.
Output Code in Preview Mode - If enabled, the Umami tracking script will be included when generating a preview of your site; this is useful for debugging, but should usually be turned off as it may skew the data collected by Umami regarding your site traffic.

Advanced Options

Auto Track - When this option is enabled, the Umami tracking code will automatically be added to your Publii site's pages for all events; pageviews, country of origin etc...Disable this option if you wish to manually set the tracking markers on each post individually.
Do Not Track - When enabled, the Umami tracking script will not send data to the server if the user has set their preference to "Do not track".
Cache - If enabled, some data relating to the function of the tracking script will be cached to increase website performance; useful if you have a lot of traffic from repeat site visitors.
Data Host URL - By default, data collected will be sent by Umami to the script location (the URL entered in this "Data host" option). If you wish to override this setting and send the data to an alternative URL, you can enter it here.
Domains - If this field is left blank, the Umami tracker will run on all domains that it is added to; that is, any server where you upload the Publii site files. By entering specific domains in this field, you can limit the tracker to working only when it is on the specified domains; useful if you are running a staging/development environment.

Cookie Banner Integration

Cookie Banner Integration - Enabling this option will add an option to the built-in Publii cookie banner for users to consent to cookies from Umami. Note that Umami doesn't use cookies by default, so this option is not necessary if you are using a standard version of Umami.
Cookie Group ID - This option only becomes available when the Cookie Banner Integration option is enabled. Here, you can specify the cookie group that the Umami cookies should be added to, e.g. 'analitics'. Make sure to add (if it doesn't exist) the group name to the GDPR section of the site settings. You can find instructions on how to do this in the GDPR section of this documentation.