General
Install script
Script settings
Features
Integrations
Explained
Legal
Affiliate program
API
Events
Account

Create plugin for Simple Analytics edit

Download PDF

To create a plugin for Simple Analytics, we have a few requirements that need to work within that plugin. The goal of the plugin is to make it as easy as possible to implement Simple Analytics.

There are two types of plugins:

Framework plugins

A few examples: React, Vue, Gridsome, and Gatsby.

The settings below should be changeable via the plugin settings. Usually, as a settings object passed to the plugin. These settings will be passed to the <script>-tag. For example:

<script data-mode="hash" data-collect-dnt="true" src="..." />

Settings that require an array will be passed like this in the plugin settings:

{
  ignorePages: ["/search/*", "/account/*", "/vouchers"];
}

But end up in the HTML script like this:

<script data-ignore-pages="/search/*,/account/*,/vouchers" src="..." />

Custom settings

Custom settings should be specified like this: customSettings: { collectDarkMode: true, ... } which will be send to the script as data-collect-dark-mode="true".

Framework plugin checklist

  • All settings below are changeable via the options object of the plugin
  • The plugin should collect page views without specifying any settings/options
  • enabled setting should allow async function that returns true or false
  • Allow custom settings (key, value)
  • Embed script is added to the body of the page (with the changed settings)
  • Events script is added to the head of the page
  • Expose framework event function that can be used on all pages
  • Embed script URL changes when auto collect events is turned on
  • Auto deploy via GitHub Actions (if possible/needed)
  • Add automated evens script when automated events are enabled

System plugins

A few examples: WordPress, Drupal, Google Tag Manager, and Cloudflare.

The settings below should be changable via the UI of the plugin. All changed settings need to be passed to the <script>-tag. For example:

<script data-mode="hash" data-collect-dnt="true" src="..." />

Settings that require an array would preferably have an UI element that adds items to a list. But in the script will be passed like this:

<script data-ignore-pages="/search/*,/account/*,/vouchers" src="..." />

Hide admins

If possible, do not collect data from admins. Let’s say you are an admin and logged in to Drupal. If the plugin can detect it’s an admin to the current site, do not collect data for that user. Make this optional in the UI.

Scripts

We have two scripts that need to be embedded into the page: Embed script (to collect data), Events script (to queue events before the Embed script is loaded).

Embed script

The following HTML should be added to the <body> of the page:

<script async defer src="https://scripts.simpleanalyticscdn.com/latest.js"></script>
<noscript><img src="https://queue.simpleanalyticscdn.com/noscript.gif" alt="" referrerpolicy="no-referrer-when-downgrade" /></noscript>

If that is not possible, add only the <script>-tag in the <head> of the page and ignore the <noscript> part.

Events script

Place this <script>-tag in the <head> of the page:

<script>window.sa_event=window.sa_event||function(){var a=[].slice.call(arguments);window.sa_event.q?window.sa_event.q.push(a):window.sa_event.q=[a]};</script>

UI

In the UI of the System plugin, we need to be able to change all settings. See here an example for the Drupal module:

Settings Advanced settings Events
full size full size full size

System plugin checklist

  • All settings below are changable via the UI of the plugin
  • Settings are hidden by default (if possible)
  • Add ignore admins feature (if possible)
  • Allow custom settings (key, value)
  • Embed script is added to the body of the page (with the changed settings)
  • Events script is added to the head of the page
  • Auto deploy via GitHub Actions (if possible/needed)
  • Add automated evens script when automated events are enabled

Collapse settings

To keep the plugin understandable and straightforward, hide as many settings as possible.

For example, collapse an advanced settings block and let users click on it to unfold. Or add a checkbox with advanced settings, which is off by default, and when a user clicks on it, open advanced settings. The same goes for events. There are quite some settings related to events. Just hide them behind a toggle (checkbox or <details>-tag).

Settings

For both System plugins and Framework plugins, the following settings need to be changeable:

Advanced settings

Setting Description Type Default Required Example
custom domain Custom domain string undefined no simple.example.com
data-mode Change mode string undefined no hash
data-collect-dnt Collect DoNotTrack visits boolean false no true
data-ignore-pages Ignore pages array undefined no /search/*,/account/*,/vouchers
data-auto-collect page views Auto collect boolean true no false
data-onload callback Onload function string undefined no onloadCallback()
data-hostname Overwrite hostname string undefined no otherdomain.com
data-sa-global Override global string sa_event no ba_event
enabled Enable the script boolean true no false

Event settings

Setting Description Type Default Required Example
data-collect Auto collect downloads array undefined no outbound,emails,downloads
data-extensions Download file extensions array pdf,csv,docx,xlsx,zip if “auto collect downloads” is true pdf,txt
data-use-title Use titles of page boolean false no true
data-full-urls Use full URLs boolean false no true
data-sa-global Override global string sa_event no ba_event

System plugins specific settings

Setting Description Type Default Required Example
ignore admins Ignore admin boolean true no false

Custom settings

The plugin should allow custom settings as well. In the future we will add more settings to our script. To be able to use those settings we want users to be able to add such a setting. For example a new setting could be named collect-dark-mode with the value true. In the plugin it should be possible to pass this value for that so it ends up in the script like this:

<script data-collect-dark-mode="true" src="..." />

Scripts

The scripts should be loaded into the HTML of the page.

<script async defer src="https://scripts.simpleanalyticscdn.com/latest.js"></script>
<noscript><img src="https://queue.simpleanalyticscdn.com/noscript.gif" alt="" referrerpolicy="no-referrer-when-downgrade" /></noscript>

Or in case when a custom domain is enabled:

<script async defer src="https://custom.domain/latest.js"></script>
<noscript><img src="https://custom.domain/noscript.gif" alt="" referrerpolicy="no-referrer-when-downgrade" /></noscript>

When automated events are enabled that script is included.