Documentation

Track without being tracked on Nuxt with Ackee analytics.

• Add Ackee to your Nuxt app in seconds
• Ask for user consent easily
• Automatic script loading
• Automatic page tracking
• Access to tracker with $ackee

Check Release Notes

Ackee?

Ackee analytics is a self-hosted, Node.js based analytics tool that has an incentive on privacy.

You can set up your own Ackee instance pretty easily on Heroku, Netlify, Vercel, and many more. MongoDB Atlas can also provide you with a cloud-based Mongo database.

This module allows you to plug easily your Nuxt website to a domain on your Ackee installation!

Setup

Add @nuxtjs/ackee dependency to your project:

yarn add --dev @nuxtjs/ackee

npm install --save-dev @nuxtjs/ackee

Then add @nuxtjs/ackee to the buildModule section of nuxt.config.js and configure your Ackee server and domainId:

{  buildModules: [    '@nuxtjs/ackee'  ],  ackee: {    server: 'https://example.com',    domainId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'    /* see configuration for more */  }}

Voilà! Your Nuxt application is ready to report to your Ackee domain~

Usage

This module injects $ackee into your application. It contains an ackee-tracker instance (but not only, see asking for consent). You can use it to create and update new records, actions, and more.

Sending Events

<template>  <form @submit="onSubmit"><!-- ... --></form></template><script>export default {  methods: {    onSubmit(e) {      this.$ackee.action(        'ffffffff-gggg-hhhh-iiii-jjjjjjjjjjjj', // actionId        {          key: 'Contact Form Submit',          value: 1        }      )    }  }}</script>

Asking for Consent

The detailed option allows you to gather personal data from your visitors. Ackee recommends asking for user consent before enabling this option. To get started, set the detailed option in your Ackee configuration:

ackee: {  // do not gather detailed data unless user gives permission  detailed: 'opt-in'}

An opt-out mode exists, working the other way around. Consider it if you were using detailed: true, it's better than nothing~

See all available values.

From now on, a new object will be available at the key details in the injected $ackee object with the following methods and reactive properties:

• optIn(): opt-in current user from sharing detailed data;
• optOut(): opt-out current user from sharing detailed data;
• value: can be used to know if Ackee is allowed to send data;
• preference: contains the user's preference if any;
• unknown: since user opt status is detected on client-side we cannot know it when on server side. Use this property to prevent showing your banner there.

Example:

<!-- assuming `detailed: 'opt-in'` --><template>  <div v-if="!$ackee.details.unknown && !$ackee.details.preference">    Allow website to gather data for improvement? (language, browser, screen    width, etc.)    <button @click="$ackee.details.optIn">Sure!</button>    <button @click="$ackee.details.optOut">No thank you!</button>  </div></template>

Configuration

You can configure @nuxtjs/ackee with the ackee property in your nuxt.config.js or directly when registering the module in the buildModules array by using the array syntax.

export default {  ackee: {    /* configuration */  }}

export default {  buildModules: {    ['@nuxtjs/ackee', {      /* configuration */    }]  }}

Properties

server

• Type: String
• required

An URL that points to your Ackee installation. The server property must not end with a slash.

ackee: {  // Nuxt.js private Ackee server example  server: 'https://ackee.nuxtjs.com'}

domainId

• Type: String
• required

Id of the desired domain to target.

ackee: {  // example domain id  domainId: 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee'}

detailed

• Type: Boolean|String
• Default: false

Enable or disable tracking of personal data. Possible values are:

• false, never collect detailed data;
• true, always collect detailed data;
• 'opt-in', do not gather detailed data unless user gives permission;
• 'opt-out', gather detailed data unless user ask not to.

ackee: {  // tells Ackee to gather detailed data only with user's permission  detailed: 'opt-in'}

See Ackee's recommendations regarding this feature.

ignoreLocalhost

• Type: Boolean
• Default: true

Enable or disable tracking when on localhost.

ackee: {  // also tracks when on localhost  ignoreLocalhost: false}

ignoreOwnVisits

• Type: Boolean
• Default: true

Enable or disable the tracking of your own visits.

ackee: {  // also tracks your own visits  ignoreOwnVisits: false}

storageKey

• Type: String
• Default: nuxt-ackee

When using 'opt-in' or 'opt-out' with the detailed option, used to determine the local storage key used to save user's preference.

ackee: {  // store user's preference at `custom-key` inside their local storage  storageKey: 'custom-key'}

Defaults

Default configuration only expects you to provide your Ackee server and domain ID.

export default {  ackee: {    server: '',    domainId: '',    detailed: false,    ignoreLocalhost: true,    ignoreOwnVisits: true,    storageKey: 'nuxt-ackee'  }}

$ackee object

This module globally injects a $ackee object, meaning that you can access it anywhere using this.$ackee. For plugins, asyncData, nuxtServerInit and middlewares, you can access it from context.$ackee.

Methods

record(), updateRecord(), action(), updateAction()

Those methods are directly forwarded from ackee-tracker instance API.

details.optIn()

Opt-in current user from sharing detailed data.

details.optOut()

Opt-out current user from sharing detailed data.

Properties

details.value

• Type: Boolean
• Value: true when Ackee is allowed to send detailed data.

details.preference

• Type: String
• Values: null when no preference has been set, 'opted-in', 'opted-out'

details.unknown

• Type: Boolean
• Value: true when opt status is not yet detected, before client-side.

Contributing

You're welcome to contribute to this module!

1. Clone this repository
2. Install dependencies using yarn install or npm install
3. Start development server using yarn dev or npm run dev

License

MIT License

Thanks to Sergey Bedritsky for the initial implementation and transfer to the community of nuxt-ackee.