diff --git a/README.md b/README.md index 29a6e90..e0f4a71 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,136 @@ [![License][license-src]][license-href] [![Nuxt][nuxt-src]][nuxt-href] +# Wide Angle Analytics module for Nuxt + +Enable **privacy-friendly** web analytics in your [Nuxt 3.x](https://nuxt.com/) application with our official plugin. + +[Wide Angle Analytics](https://wideangle.co) is powerful, strictly-GDPR compliant Google Analytics alternative. + +# How to get started + +You can enable Wide Angle Analytics in your Nuxt projects in just few steps. No complex configuration needed as our sane defaults give you reliable and privacy centric deployment out of the box. + +1. Go to [Wide Angle](https://wideangle.co) website, create an account. You can create free 14-day trail. No Credit Card is required. [Learn more.](https://wideangle.co/documentation/create-account) +2. [Create new Site](https://wideangle.co/documentation/create-and-configure-site) and activate it. +3. Install `wideangle-vuejs` plugin in your Vue application. + +```npm install wideangle-nuxt``` + +4. Enable and configure module. + +```javascript +export default defineNuxtConfig({ + modules: ['wideangle-nuxt'], + + wideangle: { + siteId: "8D27G3B9ACA01F4241" + } +}) +``` + +# Configuring Wide Angle Analytics plugin + +The Wide Angle Analytics plugin must be initialized with configuration object as there are required settings without defaults. + + +option|description|required|default|example +------|-----------|--------|-------|------- +siteId| The Site ID from Wide Angle Site settings| :white_check_mark: | _none_ | 8D27G3B9ACA01F4241 +domain| Domain hosting the script, can be found in Wide Angle Analytics Site settings | :white_check_mark: | _none_ | stats.wideangle.co +fingerprint | Should script use browser fingerprinting; this might require collecting consent depeing on the applicable laws | :x: | false | true +supressDnt | Should script ingore Do Not Track browser setting. If not enabled, not events will be sent if user's browser has DNT enabled | :x: | false | true +includeParams | An array of query parameters that can be passed as part of tracking event. By default only `utm_*` and `ref` parameters are passed in the event | :x: | `[]` | `['sessionId', 'offset']` +excludePaths | An array of URL paths that should not trigger default events such as page view, page leave | :x: | `[]` | `['^/wp-admin/.*', ]` +ignoreHash | If enabled, change in the URL fragment will not trigger page view event | :x: | false | true + +You will find more details about these settings in [Wide Angle Analytics documentation](https://wideangle.co/documentation/configure-site). + + +Example: + +```javascript +export default defineNuxtConfig({ + modules: ['wideangle-nuxt'], + + wideangle: { + siteId: "8D27G3B9ACA01F4241", + domain: "your.domain.com", + fingerprint: false, + supressDnt: true, + includeParams: ['q', 'customerId'], + excludePaths: ['^/admin.*'], + ignoreHash: true + }u +}) +``` + + +# Usage + +The Wide Angle Analytics provides an instance of `waa` which can be then injected to your component. + +```javascript +import { useWideAngle } from '#imports' + +useWideAngle('purchase', {'basket_value': '45.00'}) +``` + +You will find a fully functional example in this [repository](playground/app.vue). + + +## Tracking Pageviews + +No action necessary. The tracker script automatically issues **Page View** and **Page Leave** events. + +## Tracking Events + +Wide Angle supports three specialized events: +* clicks +* downloads +* custom actions + +Site has to have these event enable in Wide Angle Analytics configuration prior to usage. Otherwise the tracker script will not sent these events. Consult [official documentation](https://wideangle.co/documentation/tracking-custom-actions) regarding how to enable event handling. + +### Tracking Clicks + +Currently **Click Events** are [emitted automatically](https://wideangle.co/documentation/tracking-click-events) based on element data attributes. + +### Tracking Downloads + +Depending on the configured mode, the **Download Event** will fire automatically when either: +* a file with recognized extension is being downloaded, or +* when a link is marked with `data-waa-name` attribute. + +### Tracking Custom Actions + +Custom action are the most flexible and can be triggered directly from Vue components. As such their usage is not limitted due to Shadow DOM. + +Example: + +```vue + + + +``` + +### Module Assets + +#### Icon + +#### Full Logo + diff --git a/package-lock.json b/package-lock.json index 478447a..2c1dde1 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,16 +1,16 @@ { "name": "wideangle", - "version": "1.0.0", + "version": "0.0.1", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "wideangle", - "version": "1.0.0", - "license": "MIT", + "version": "0.0.1", + "license": "Apache-2.0", "dependencies": { "@nuxt/kit": "^3.4.3", - "wideangle-vuejs": "^0.0.2" + "wideangle-vuejs": "file:../../wideangle-vuejs/" }, "devDependencies": { "@nuxt/eslint-config": "^0.1.1", @@ -24,6 +24,13 @@ "vitest": "^0.30.1" } }, + "../../wideangle-vuejs": { + "version": "0.0.3", + "license": "Apache-2.0", + "devDependencies": { + "typescript": "^5.0.4" + } + }, "node_modules/@ampproject/remapping": { "version": "2.2.1", "resolved": "https://registry.npmjs.org/@ampproject/remapping/-/remapping-2.2.1.tgz", @@ -9424,9 +9431,8 @@ } }, "node_modules/wideangle-vuejs": { - "version": "0.0.2", - "resolved": "https://registry.npmjs.org/wideangle-vuejs/-/wideangle-vuejs-0.0.2.tgz", - "integrity": "sha512-5eGr1lB5MTOghX/j2rxbyf+osdEGnq3vlaLNZJM6yzxA4dP7GlRLYSa0I3Od7kKdMMcX6N8f7ADcVl6kMNMktw==" + "resolved": "../../wideangle-vuejs", + "link": true }, "node_modules/word-wrap": { "version": "1.2.3", @@ -16246,9 +16252,10 @@ } }, "wideangle-vuejs": { - "version": "0.0.2", - "resolved": "https://registry.npmjs.org/wideangle-vuejs/-/wideangle-vuejs-0.0.2.tgz", - "integrity": "sha512-5eGr1lB5MTOghX/j2rxbyf+osdEGnq3vlaLNZJM6yzxA4dP7GlRLYSa0I3Od7kKdMMcX6N8f7ADcVl6kMNMktw==" + "version": "file:../../wideangle-vuejs", + "requires": { + "typescript": "^5.0.4" + } }, "word-wrap": { "version": "1.2.3", diff --git a/package.json b/package.json index 32e45bf..6789b09 100644 --- a/package.json +++ b/package.json @@ -1,5 +1,5 @@ { - "name": "wideangle", + "name": "wideangle-nuxt", "version": "0.0.1", "description": "Wide Angle Analytics module for Nuxt", "repository": "inputobjects/wideangle-nuxt", @@ -12,7 +12,8 @@ "vue.js", "vuejs", "plugin", - "vuejs plugin" + "vuejs plugin", + "nuxt module" ], "exports": { ".": { @@ -38,7 +39,7 @@ }, "dependencies": { "@nuxt/kit": "^3.4.3", - "wideangle-vuejs": "^0.0.2" + "wideangle-vuejs": "1.0.0" }, "devDependencies": { "@nuxt/eslint-config": "^0.1.1", diff --git a/playground/app.vue b/playground/app.vue index 58db5ce..877ee48 100644 --- a/playground/app.vue +++ b/playground/app.vue @@ -1,8 +1,34 @@ - + + diff --git a/playground/nuxt.config.ts b/playground/nuxt.config.ts index 6bf7ad5..c049275 100644 --- a/playground/nuxt.config.ts +++ b/playground/nuxt.config.ts @@ -1,4 +1,10 @@ export default defineNuxtConfig({ modules: ['../src/module'], - myModule: {} + + wideangle: { + siteId: "8D27G3B9ACA01F4241", + domain: "wideangle.local:3000", + fingerprint: true, + supressDnt: true + } }) diff --git a/src/module.ts b/src/module.ts index 695e6a3..b88afa7 100644 --- a/src/module.ts +++ b/src/module.ts @@ -1,19 +1,53 @@ -import { defineNuxtModule, addPlugin, createResolver } from '@nuxt/kit' +import { defineNuxtModule, addPlugin, addImports, createResolver, useLogger } from '@nuxt/kit' +import { defu } from 'defu' +import { fileURLToPath } from 'url' -// Module options TypeScript interface definition -export interface ModuleOptions {} +const logger = useLogger('nuxt:wideangle') + +export interface ModuleOptions { + siteId?: string + domain?: string + fingerprint?: boolean + supressDnt?: boolean + includeParams?: string[] + excludePaths?: string[] + ignoreHash?: boolean +} export default defineNuxtModule({ meta: { name: 'wideangle', - configKey: 'myModule' + configKey: 'wideangle', + compatibility: { + nuxt: '^3' + } + }, + defaults: { + domain: "stats.wideangle.co", + fingerprint: false, + supressDnt: false, + includeParams: [], + excludePaths: [], + ignoreHash: false }, - // Default configuration options of the Nuxt module - defaults: {}, setup (options, nuxt) { + const runtimeDir = fileURLToPath(new URL('./runtime', import.meta.url)) + nuxt.options.build.transpile.push(runtimeDir) + + logger.info(`Module options: ${JSON.stringify(options)}`); const resolver = createResolver(import.meta.url) - // Do not add the extension since the `.ts` will be transpiled to `.mjs` after `npm run prepack` - addPlugin(resolver.resolve('./runtime/plugin')) + nuxt.options.runtimeConfig.public.wideangle = defu(nuxt.options.runtimeConfig.public.wideangle, options); + + addImports({ + name: "useWaaEvent", + as: "useWaaEvent", + from: resolver.resolve('./runtime/composables/useWaaEvent') + }); + + addPlugin({ + src: resolver.resolve('./runtime/plugin.client') + }); + } }) diff --git a/src/runtime/composables/useWaaEvent.ts b/src/runtime/composables/useWaaEvent.ts new file mode 100644 index 0000000..e885057 --- /dev/null +++ b/src/runtime/composables/useWaaEvent.ts @@ -0,0 +1,10 @@ +import { useNuxtApp } from '#imports'; + +export function useWaaEvent (name: string, params?: Record) { + const waa = useNuxtApp().$waa + if(waa && waa.value) { + waa.value.dispatchEvent(name, params); + } else { + console.debug("[WAA] Wide Angle Analytics is not yest initialized"); + } +} diff --git a/src/runtime/plugin.client.ts b/src/runtime/plugin.client.ts new file mode 100644 index 0000000..5fefc3f --- /dev/null +++ b/src/runtime/plugin.client.ts @@ -0,0 +1,30 @@ +import { defineNuxtPlugin, useRuntimeConfig } from '#imports'; +import { ref } from 'vue'; +import { initWideAngle } from 'wideangle-vuejs'; + +export default defineNuxtPlugin((nuxtApp) => { + if(process.server) { + console.warn("[WAA] Plugin will not be enabled on server side."); + return; + } + + const { wideangle: options } = useRuntimeConfig().public + console.debug(`[WAA] Initializing Wide Angle Analytics with: ${JSON.stringify(options)}`); + if(options.siteId == null) { + throw new Error("[WAA] Wide Angle Analytics requires the site ID."); + } + const waa = ref() + initWideAngle(options) + .then(waaInstance => { + waa.value = waaInstance; + console.debug("[WAA] Wide Angle Analytics instance available"); + }).catch(e => { console.error("[WAA] Failed to load Wide Angle Plugin", e)}); + + return { + provide: { + waa + } + } +}) + + diff --git a/src/runtime/plugin.ts b/src/runtime/plugin.ts deleted file mode 100644 index e7b9dde..0000000 --- a/src/runtime/plugin.ts +++ /dev/null @@ -1,5 +0,0 @@ -import { defineNuxtPlugin } from '#app' - -export default defineNuxtPlugin((nuxtApp) => { - console.log('Plugin injected by wideangle!') -}) diff --git a/test/basic.test.ts b/test/basic.test.ts deleted file mode 100644 index c4735db..0000000 --- a/test/basic.test.ts +++ /dev/null @@ -1,15 +0,0 @@ -import { describe, it, expect } from 'vitest' -import { fileURLToPath } from 'node:url' -import { setup, $fetch } from '@nuxt/test-utils' - -describe('ssr', async () => { - await setup({ - rootDir: fileURLToPath(new URL('./fixtures/basic', import.meta.url)), - }) - - it('renders the index page', async () => { - // Get response to a server-rendered page with `$fetch`. - const html = await $fetch('/') - expect(html).toContain('
basic
') - }) -}) diff --git a/test/fixtures/basic/app.vue b/test/fixtures/basic/app.vue deleted file mode 100644 index 29a9c81..0000000 --- a/test/fixtures/basic/app.vue +++ /dev/null @@ -1,6 +0,0 @@ - - - diff --git a/test/fixtures/basic/nuxt.config.ts b/test/fixtures/basic/nuxt.config.ts deleted file mode 100644 index 1bc2f7c..0000000 --- a/test/fixtures/basic/nuxt.config.ts +++ /dev/null @@ -1,7 +0,0 @@ -import MyModule from '../../../src/module' - -export default defineNuxtConfig({ - modules: [ - MyModule - ] -}) diff --git a/test/fixtures/basic/package.json b/test/fixtures/basic/package.json deleted file mode 100644 index decd433..0000000 --- a/test/fixtures/basic/package.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "private": true, - "name": "basic", - "type": "module" -}