wideangle/wideangle-nuxt
3
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Compare commits

base: wideangle:main
Branches Tags
wideangle:main
wideangle:feature/upgrade-to-nuxt-37-plus
wideangle:2.0.0
wideangle:1.2.2
wideangle:1.2.1
wideangle:1.2.0
wideangle:1.1.0
wideangle:1.0.3
wideangle:1.0.2
wideangle:1.0.1
wideangle:1.0.0
wideangle:0.0.1
..
compare: wideangle:1.0.3
Branches Tags
wideangle:main
wideangle:feature/upgrade-to-nuxt-37-plus
wideangle:2.0.0
wideangle:1.2.2
wideangle:1.2.1
wideangle:1.2.0
wideangle:1.1.0
wideangle:1.0.3
wideangle:1.0.2
wideangle:1.0.1
wideangle:1.0.0
wideangle:0.0.1

No commits in common. "main" and "1.0.3" have entirely different histories.
main ... 1.0.3

16 changed files with 7162 additions and 15363 deletions
Download patch file Download diff file Expand all files Collapse all files

113
README.md
View file

@ -6,7 +6,7 @@
[![Nuxt][nuxt-src]][nuxt-href] [![Nuxt][nuxt-src]][nuxt-href]
[![Wide Angle][wideangle-src]][wideangle-href] [![Wide Angle][wideangle-src]][wideangle-href]
![Wide Angle Analytics Large Logo](assets/full_logo_color_light_transparent.png) ![Wide Angle Analytics Large Logo](https://github.com/inputobjects/wideangle-nuxt/assets/4896588/7efee4f1-d9e1-4b54-a5cd-257d13494f41)
# Wide Angle Analytics module for Nuxt # Wide Angle Analytics module for Nuxt
@ -16,17 +16,15 @@ Enable **privacy-friendly** web analytics in your [Nuxt 3.x](https://nuxt.com/)
# How to get started # How to get started
You can enable Wide Angle Analytics in your Nuxt projects in just a few steps. No complex configuration needed, as our sane defaults provide you with a reliable and privacy-centric deployment out of the box. 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 the [Wide Angle](https://wideangle.co) website and create an account. You can enjoy a free 14-day trail. No Credit Card is required. [Learn more.](https://wideangle.co/documentation/create-account) 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 a new site](https://wideangle.co/documentation/create-and-configure-site) and activate it. 2. [Create new Site](https://wideangle.co/documentation/create-and-configure-site) and activate it.
3. Install the `wideangle-vuejs` plugin in your Vue application. 3. Install `wideangle-vuejs` plugin in your Vue application.
```bash ```npm install wideangle-nuxt```
npx nuxi@latest module add wideangle
```
4. Enable and configure the module. 4. Enable and configure module.
```javascript ```javascript
export default defineNuxtConfig({ export default defineNuxtConfig({
@ -44,21 +42,20 @@ export default defineNuxtConfig({
# Configuring Wide Angle Analytics plugin # Configuring Wide Angle Analytics plugin
The Wide Angle Analytics plugin must be initialized with a configuration object as there are required settings without defaults. The Wide Angle Analytics plugin must be initialized with configuration object as there are required settings without defaults.
option|description|required|default|example option|description|required|default|example
------|-----------|--------|-------|------- ------|-----------|--------|-------|-------
siteId| The Site ID from the Wide Angle Site settings| :white_check_mark: | _none_ | 8D27G3B9ACA01F4241 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 | :x: | stats.wideangle.co | your.domain.com domain| Domain hosting the script, can be found in Wide Angle Analytics Site settings | :x: | stats.wideangle.co | your.domain.com
fingerprint | Should script use browser fingerprinting; this might require collecting consent depending on the applicable laws | :x: | false | true fingerprint | Should script use browser fingerprinting; this might require collecting consent depeing on the applicable laws | :x: | false | true
suppressDnt | Should script ingore Do Not Track browser setting. If not enabled, no events will be sent if user's browser has DNT enabled | :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']` 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/.*', ]` excludePaths | An array of URL paths that should not trigger default events such as page view, page leave | :x: | `[]` | `['^/wp-admin/.*', ]`
ignoreHash | If enabled, a change in the URL fragment will not trigger page view event | :x: | false | true ignoreHash | If enabled, change in the URL fragment will not trigger page view event | :x: | false | true
consentMarker | Name of cookie (with or without) which presence is treated as implied consent; when not defined, consent is not determined by cookie | :x: | n/a | `WAA_CONSENT=true`
You can find more details about these settings in the [Wide Angle Analytics documentation](https://wideangle.co/documentation/configure-site). You will find more details about these settings in [Wide Angle Analytics documentation](https://wideangle.co/documentation/configure-site).
Example: Example:
@ -73,11 +70,10 @@ export default defineNuxtConfig({
siteId: "8D27G3B9ACA01F4241", siteId: "8D27G3B9ACA01F4241",
domain: "your.domain.com", domain: "your.domain.com",
fingerprint: false, fingerprint: false,
suppressDnt: true, supressDnt: true,
includeParams: ['q', 'customerId'], includeParams: ['q', 'customerId'],
excludePaths: ['^/admin.*'], excludePaths: ['^/admin.*'],
ignoreHash: true, ignoreHash: true
consentMarker: `WAA_CONSENT=true`
} }
} }
} }
@ -87,21 +83,12 @@ export default defineNuxtConfig({
# Usage # Usage
The Wide Angle Analytics provides a composable which can be used in your component. The Wide Angle Analytics provides an instance of `waa` which can be then injected to your component.
```javascript ```javascript
<template> import { useWideAngle } from '#imports'
<button @click="sendEvent">Send Event</button>
</template>
<script setup>
import { useWideAngle } from '#imports';
const sendEvent = () => {
useWideAngle().dispatchEvent('basket-open', {'page': 'catalogue'}, {'item-price': 599.00, 'basket-total': 1299.00});
}
</script>
useWideAngle('purchase', {'basket_value': '45.00'})
``` ```
You will find a fully functional example in this [repository](playground/app.vue). You will find a fully functional example in this [repository](playground/app.vue).
@ -118,7 +105,7 @@ Wide Angle supports three specialized events:
* downloads * downloads
* custom actions * custom actions
Site has to have these events enabled in the Wide Angle Analytics configuration prior to usage. Otherwise the tracker script will not send these events. Consult the [official documentation](https://wideangle.co/documentation/tracking-custom-actions) regarding how to enable event handling. 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 ### Tracking Clicks
@ -132,7 +119,7 @@ Depending on the configured mode, the **Download Event** will fire automatically
### Tracking Custom Actions ### Tracking Custom Actions
Custom actions are the most flexible and can be triggered directly from Vue components. As such, their usage is not limitted due to the Shadow DOM. 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: Example:
@ -142,74 +129,20 @@ Example:
</template> </template>
<script setup> <script setup>
import { useWideAngle } from '#imports' import { useWaaEvent } from '#imports'
const sendEvent = async () => { const sendEvent = async () => {
const params = { const params = {
session: 'cjhw92nf9aq', session: 'cjhw92nf9aq',
cohort: 'c1233' cohort: 'c1233'
} }
useWideAngle().dispatchEvent('interest', params); useWaaEvent('interest', params);
} }
</script> </script>
``` ```
### Module Assets ### Module Assets
You can find a high-resolution Wide Angle Analytics logo and icon on our [media page](https://wideangle.co/media). You can find high-resolution Wide Angle Analytics logo and icon on our [media page](https://wideangle.co/media).
# Recording consent
The Wide Angle Analytics, thanks to is privacy-first, anonymous approach to web traffic analytics does not requires consent by default.
However, we do offer multiple tools that support collecting consent should it be required in your use case.
## Opt-Out by default
If the visitors browsers has `DoNotTrack` setting enabled in the browser, it will be understood as opt-out and not tracking events will be issued.
You website can't overwrite this behaviour by specifying `suppressDnt` setting.
```javascript
wideangle: {
siteId: "8D27G3B9ACA01F4241",
suppressDnt: true
}
```
## Opt-In or Opt-Out based on Cookie
Wide Angle can be configure to handle presence of a cookie, or a cookie with specific value, as an implicit consent. Lack of the cookie will be handled as implicit opt-out.
Example configuration with cookie marker, expecting cookie name `WAA_CONSENT` with value `true`:
```javascript
wideangle: {
siteId: "8D27G3B9ACA01F4241",
consentMarker: "WAA_CONSENT=true"
}
```
## Programmatic consent
The Wide Angle serving offers two additional methods, which allow for recording tracking consent:
- `recordConsent(subjectId: String): void`, and
- `revokeConsent()`
Calling above methods on `waa` service will overwrite other consent mechanism (ie. DoNotTrack, and cookie marker).
Example usage:
```vue
<script setup>
import { useWideAngle } from '#imports'
useWideAngle().recordConsent('FHJ44111');
</script>
```
<!-- Badges --> <!-- Badges -->

BIN
assets/full_logo_color_light_transparent.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 173 KiB

20
eslint.config.mjs
View file

@ -1,20 +0,0 @@
// @ts-check
import { createConfigForNuxt } from '@nuxt/eslint-config/flat'
// Run `npx @eslint/config-inspector` to inspect the resolved config interactively
export default createConfigForNuxt({
features: {
// Rules for module authors
tooling: true,
// Rules for formatting
stylistic: true,
},
dirs: {
src: [
'./playground',
],
},
})
.append(
// your custom flat config here...
)

22079
package-lock.json generated
View file

File diff suppressed because it is too large Load diff

46
package.json
View file

@ -1,12 +1,8 @@
{ {
"name": "wideangle-nuxt", "name": "wideangle-nuxt",
"version": "2.0.0", "version": "1.0.3",
"description": "Wide Angle Analytics module for Nuxt", "description": "Wide Angle Analytics module for Nuxt",
"homepage": "https://wideangle.co", "repository": "inputobjects/wideangle-nuxt",
"repository": {
"type": "git",
"url": "https://cloud.inputobjects.eu/forge/wideangle/wideangle-nuxt.git"
},
"author": "Wide Angle Analytics <developers@wideangle.co>", "author": "Wide Angle Analytics <developers@wideangle.co>",
"license": "Apache-2.0", "license": "Apache-2.0",
"type": "module", "type": "module",
@ -17,9 +13,7 @@
"vuejs", "vuejs",
"plugin", "plugin",
"vuejs plugin", "vuejs plugin",
"nuxt module", "nuxt module"
"privacy",
"privacy web analytics"
], ],
"exports": { "exports": {
".": { ".": {
@ -34,29 +28,29 @@
"dist" "dist"
], ],
"scripts": { "scripts": {
"prepack": "nuxt-module-build build", "prepack": "nuxt-module-build",
"dev": "nuxi dev playground", "dev": "nuxi dev playground",
"dev:build": "nuxi build playground", "dev:build": "nuxi build playground",
"dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare && nuxi prepare playground", "dev:prepare": "nuxt-module-build --stub && nuxi prepare playground",
"release": "npm run prepack && changelogen --release && npm publish", "release": "npm run lint && npm run test && npm run prepack && changelogen --release && npm publish && git push --follow-tags",
"lint": "eslint .", "lint": "eslint .",
"lint:fix": "eslint . --fix" "test": "vitest run",
"test:watch": "vitest watch"
}, },
"dependencies": { "dependencies": {
"@nuxt/kit": "^3.15.3", "@nuxt/kit": "^3.4.3",
"wideangle-vuejs": "2.0.0", "wideangle-vuejs": "1.0.0",
"defu": "^6.1.4" "defu": "^6.1.2"
}, },
"devDependencies": { "devDependencies": {
"@nuxt/devtools": "latest", "@nuxt/eslint-config": "^0.1.1",
"@nuxt/eslint-config": "^0.7.5", "@nuxt/module-builder": "^0.3.0",
"@nuxt/module-builder": "^0.8.4", "@nuxt/schema": "^3.4.3",
"@nuxt/schema": "^3.15.3", "@nuxt/test-utils": "^3.4.3",
"@types/node": "latest", "@types/node": "^18",
"changelogen": "^0.5.7", "changelogen": "^0.5.3",
"eslint": "^9.19.0", "eslint": "^8.39.0",
"nuxt": "^3.13.2", "nuxt": "^3.4.3",
"typescript": "~5.7.2", "vitest": "^0.30.1"
"vue-tsc": "^2.2.0"
} }
} }

36
playground/app.vue Normal file
View file

@ -0,0 +1,36 @@
<template>
<main>
<h1>Nuxt Application</h1>
<button @click="trackClick">
Track Click
</button>
</main>
</template>
<script setup lang="ts">
import { useWaaEvent } from "#imports";
function trackClick() {
useWaaEvent("foo", {"name": "bar"});
}
</script>
<style>
main {
font-family: 'Lucida Sans', 'Lucida Sans Regular', 'Lucida Grande', 'Lucida Sans Unicode', Geneva, Verdana, sans-serif;
font-size: 2rem;
display: flex;
flex-direction: column;
max-width: 300px;
gap: 2rem;
align-items: center;
margin: 0 auto;
text-align: center;
}
button {
padding: 1rem;
}
</style>

11
playground/components/sample-tracker.vue
View file

@ -1,11 +0,0 @@
<template>
<button @click="sendEvent">Send Event</button>
</template>
<script setup>
import { useWideAngle } from '#imports';
const sendEvent = () => {
useWideAngle().dispatchEvent('foo', {'param1': 'bar'}, {'value1': 123});
}
</script>

14
playground/nuxt.config.ts
View file

@ -1,17 +1,13 @@
// https://nuxt.com/docs/api/configuration/nuxt-config
export default defineNuxtConfig({ export default defineNuxtConfig({
devtools: { enabled: true }, modules: ['../src/module'],
compatibilityDate: "2025-01-28",
modules: ['wideangle-nuxt'],
// ssr: false,
runtimeConfig: { runtimeConfig: {
public: { public: {
wideangle: { wideangle: {
siteId: "8D27G3B9ACA01F4241", siteId: "8D27G3B9ACA01F4241",
domain: "events.wideangle.test", domain: "wideangle.local:3000",
fingerprint: false, fingerprint: true,
suppressDnt: true supressDnt: true
} }
} }
} }
}) });

4
playground/package.json Normal file
View file

@ -0,0 +1,4 @@
{
"private": true,
"name": "wideangle-playground"
}

7
playground/pages/index.vue
View file

@ -1,7 +0,0 @@
<template>
<div>
<h1>Wide Angle Analytics Playground</h1>
<sample-tracker/>
</div>
</template>

46
src/module.ts
View file

@ -1,5 +1,6 @@
import { defineNuxtModule, addPlugin, addImportsDir, createResolver, useLogger } from '@nuxt/kit' import { defineNuxtModule, addPlugin, addImports, createResolver, useLogger } from '@nuxt/kit'
import { defu } from 'defu' import { defu } from 'defu'
import { fileURLToPath } from 'url'
const logger = useLogger('nuxt:wideangle') const logger = useLogger('nuxt:wideangle')
@ -7,11 +8,10 @@ export interface ModuleOptions {
siteId?: string siteId?: string
domain: string domain: string
fingerprint: boolean fingerprint: boolean
suppressDnt: boolean supressDnt: boolean
includeParams: string[] includeParams: string[]
excludePaths: string[] excludePaths: string[]
ignoreHash: boolean ignoreHash: boolean
consentMarker?: string
} }
export default defineNuxtModule<ModuleOptions>({ export default defineNuxtModule<ModuleOptions>({
@ -19,29 +19,39 @@ export default defineNuxtModule<ModuleOptions>({
name: 'wideangle', name: 'wideangle',
configKey: 'wideangle', configKey: 'wideangle',
compatibility: { compatibility: {
nuxt: '>=3', nuxt: '^3'
}, }
}, },
defaults: { defaults: {
domain: 'stats.wideangle.co', domain: "stats.wideangle.co",
fingerprint: false, fingerprint: false,
suppressDnt: false, supressDnt: false,
includeParams: [], includeParams: [],
excludePaths: [], excludePaths: [],
ignoreHash: false, ignoreHash: false
consentMarker: undefined,
}, },
setup (options, nuxt) { setup (options, nuxt) {
const resolver = createResolver(import.meta.url) const runtimeDir = fileURLToPath(new URL('./runtime', import.meta.url))
nuxt.options.build.transpile.push(resolver.resolve('./runtime'))
nuxt.options.runtimeConfig.public.wideangle = defu( nuxt.options.runtimeConfig.public.wideangle = defu(
nuxt.options.runtimeConfig.public.wideangle ||= {}, nuxt.options.runtimeConfig.public.wideangle,
{ ...options }) options,
logger.info('Adding Wide Angle Analytics (useWideAngle) import') )
addImportsDir(resolver.resolve('./runtime/composables'))
logger.info('Adding Wide Angle Analytics runtime plugin') nuxt.options.build.transpile.push(runtimeDir);
addPlugin(resolver.resolve('./runtime/plugin.client')) const resolver = createResolver(import.meta.url);
},
logger.info('Adding Wide Angle Analytics runtime plugin');
addImports({
name: "useWaaEvent",
as: "useWaaEvent",
from: resolver.resolve('./runtime/composables/useWaaEvent')
});
addPlugin({
src: resolver.resolve('./runtime/plugin.client')
});
}
}) })

10
src/runtime/composables/useWaaEvent.ts Normal file
View file

@ -0,0 +1,10 @@
import { useNuxtApp } from '#imports';
export function useWaaEvent (name: string, params?: Record<string, any>) {
const waa = useNuxtApp().$waa
if(waa && waa.value) {
waa.value.dispatchEvent(name, params);
} else {
console.debug("[WAA] Wide Angle Analytics is not yest initialized");
}
}

27
src/runtime/composables/useWideAngle.ts
View file

@ -1,27 +0,0 @@
import {useNuxtApp} from '#imports'
import type {WideAngleApi} from "~/src/types";
class NoOpWideAngleAnalyticsApi implements WideAngleApi {
dispatchEvent(name: string, params: any, values: any): void {
console.debug(`[WideAngleApi#dispatchEvent] Defaulting to NoOp Wide Angle call with name "${name}", params: ${JSON.stringify(params)}, values: ${JSON.stringify(params)}`);
}
recordConsent(subjectsId: string): void {
console.debug(`[WideAngleApi#recordConsent] Defaulting to NoOp Wide Angle call with ${subjectsId}`);
}
revokeConsent() {
console.debug(`[WideAngleApi#revokeConsent] Defaulting to NoOp Wide Angle call`);
}
}
const noOpWideAngleApi = new NoOpWideAngleAnalyticsApi();
export function useWideAngle() {
const { $waa } = useNuxtApp()
if ($waa) {
return $waa.value;
} else {
return noOpWideAngleApi;
}
}

40
src/runtime/plugin.client.ts
View file

@ -1,36 +1,30 @@
import { type Ref, ref} from 'vue' import { defineNuxtPlugin, useRuntimeConfig } from '#imports';
import { initWideAngle } from 'wideangle-vuejs' import { ref } from 'vue';
import { defineNuxtPlugin, type NuxtApp } from '#app' import { initWideAngle } from 'wideangle-vuejs';
import { useRuntimeConfig } from "#imports";
import type { WideAngleApi } from "~/src/types";
export default defineNuxtPlugin(async (_nuxtApp) => { export default defineNuxtPlugin(() => {
if(process.server) {
if (import.meta.server) { console.warn("[WAA] Plugin will not be enabled on server side.");
console.warn('[WAA] Plugin will not be enabled on server side.') return;
return
} }
const { wideangle: options } = useRuntimeConfig().public const { wideangle: options } = useRuntimeConfig().public
console.debug(`[WAA] Initializing Wide Angle Analytics with: ${JSON.stringify(options)}`) console.debug(`[WAA] Initializing Wide Angle Analytics with: ${JSON.stringify(options)}`);
if(options.siteId == null) { if(options.siteId == null) {
throw new Error('[WAA] Wide Angle Analytics requires the site ID.') throw new Error("[WAA] Wide Angle Analytics requires the site ID.");
} }
const waa = ref() const waa = ref()
initWideAngle(options) initWideAngle(options)
.then((waaInstance) => { .then(waaInstance => {
waa.value = waaInstance waa.value = waaInstance;
console.debug('[WAA] Wide Angle Analytics instance available') console.debug("[WAA] Wide Angle Analytics instance available");
}).catch((e) => { }).catch(e => { console.error("[WAA] Failed to load Wide Angle Plugin", e)});
console.error('[WAA] Failed to load Wide Angle Plugin', e)
})
return { return {
provide: { provide: {
waa: waa as Ref<WideAngleApi>, waa
}, }
} }
}) })

5
src/types.ts
View file

@ -1,5 +0,0 @@
export interface WideAngleApi {
dispatchEvent(name: string, params: any, values: any) : void;
recordConsent(subjectsId: string) : void;
revokeConsent() : void;
}

7
tsconfig.json
View file

@ -1,8 +1,3 @@
{ {
"extends": "./.nuxt/tsconfig.json", "extends": "./playground/.nuxt/tsconfig.json"
"exclude": [
"dist",
"node_modules",
"playground",
]
} }