Embedding the script

Each page that is expected to be included in the usages statistics requires to load the Offen Fair Web Analytics script. The script needs to be configured with the Account ID you want to use for that page.

The script is served from https://<your-installation-domain>/script.js and can be included in any portion of your document, for example as portion of the document’s <head>:

<script async src="https://<your-installation-domain>/script.js" data-account-id="<your-account-id>"></script>

Your Account ID and the entire snippet can be found when you log in to the Auditorium and select the account you want use.

Using Offen Fair Web Analytics with a Content-Security-Policy
Setting X-Frame-Options
Triggering pageviews using the JavaScript API

Using Offen Fair Web Analytics with a Content-Security-Policy

If you serve your site with a Content-Security-Policy, there are a few things to consider when adding the Offen Fair Web Analytics script:

`script-src`

As the Offen Fair Web Analytics script is served from a different subdomain, you need to allow the domain as a script-src, i.e. script-src 'self' https://offen.mysite.org.

`frame-src`

Offen Fair Web Analytics isolates all handling of usage data in an iframe element so it can leverage the Same-Origin Policy to protect data from unwanted access from 3rd parties. Your Content-Security-Policy therefore needs to specify a frame-src like frame-src 'self' https://offen.mysite.org

`style-src`

When displaying the consent banner, Offen Fair Web Analytics injects an inline stylesheet to position the banner element on the site. This means you need to allow unsafe-inline styles in your Content-Security-Policy: style-src 'self' 'unsafe-inline'

Minimal example

A minimal Content-Security-Policy to use Offen Fair Web Analytics on your site could look like:

Content-Security-Policy: default-src 'self'; script-src 'self' offen.mysite.org; frame-src 'self' offen.mysite.org; style-src 'self' 'unsafe-inline'

Setting X-Frame-Options

Offen Fair Web Analytics relies heavily on the security and isolation features provided by running sensitive parts in an iframe so there is no way to “unbox” it in any way. If you want or need to use X-Frame-Options on a page that uses Offen Fair Web Analytics, you need to specifically allow the domain you are serving it from:

X-Frame-Options: allow-from https://offen.example.com/

Triggering pageviews using the JavaScript API

When embedded as shown above, Offen Fair Web Analytics will automatically acquire a user consent decision and collect pageviews in case consent is given. If you need more fine-grained control (e.g. in the context of a user sign-up flow or similar) you can use the JavaScript API exposed by the Offen Fair Web Analytics script instead.

This API is not exposed by default. Embed the script passing a data-use-api attribute and not using async or defer:

<script src="https://<your-installation-domain>/script.js" data-account-id="<your-account-id>" data-use-api></script>

Offen Fair Web Analytics now exposes two methods on window.__offen__:

`window.offen.pageview([options], callback)`

When consuming the API, you can trigger a pageview event yourself by calling the pageview method. It takes an optional options argument and an optional callback that will be invoked on success. In case the user has denied consent and no data is collected, the callback will be called as well. It receives an error argument that is null in case no error occured.

options is an object with one or more of the following boolean properties:

skipConsent: when given, Offen Fair Web Analytics does not try to acquire a user consent decision in case it has not been made yet. This means data will only be collected in case the user has previously opted in. All other cases (no consent decision yet, consent denied) result in no pageview being collected.
subsequent: when given, Offen Fair Web Analytics will not collect a page load time to associate with the page view. This can be used for example in single page applications where a client-side navigation does not trigger an actual pageload.

`window.offen.acquireConsent(callback)`

In case you want to trigger a consent decision without triggering a pageview, you can call this method. When a callback function is given it will be called with a single error argument. There is no way of telling the outcome of the consent decision (i.e. if the user has allowed or denied the collection of usage data), the error being null just tells you a decision happened and is persisted.

window.__offen__.acquireConsent(function (err)  {
  if (err) {
    // an error occured acquiring the consent decision
    return
  }
  // a consent decision has been made
})

Heads Up

This API is currently under development and considered experimental. It does not come with any stability guarantees. In case you are using it check the changelog on your next upgrade. If you have any ideas about how to define this further, we are happy to learn about your feedback.

Embedding the script

Table of contents

Using Offen Fair Web Analytics with a Content-Security-Policy

script-src

frame-src

style-src