Wide Angle plugin with working sample

.gitignore

@@ -0,0 +1,28 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+.DS_Store
+dist
+dist-ssr
+coverage
+*.local
+
+/cypress/videos/
+/cypress/screenshots/
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

README.md

@@ -29,16 +29,99 @@ app.use(WideAnglePlugin)
 
 # Configuring Wide Angle Analytics plugin
 
-:construction_worker:  * TODO*
+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 | 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 | 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| `[]` | `['sessionId', 'offset']`
+excludePaths | An array of URL paths that should not trigger default events such as page view, page leave | `[]` | `['^/wp-admin/.*', ]`
+ignoreHash | If enabled, change in the URL fragment will not trigger page view event | false | true
+
+You will find more details about these settings in [Wide Angle Analytics documentation](https://wideangle.co/documentation/configure-site).
+
+
+Example:
+
+```javascript 
+import WideAngle from 'wideangle-vue'
+
+const app = createApp(App);
+
+app.use(WideAngle, {
+  siteId: "8D27G3B9ACA01F4241",
+  domain: "stats.example.com",
+  fingerprint: true,
+  supressDnt: true
+});
+```
+
 
 # Usage 
 
+The Wide Angle Analytics provides an instance of `waa` which can be then injected to your component. 
+
+```javascript
+import { inject } from 'vue'
+const waa = inject('waa');
+```
+
+You will find a fully functional example in this [repositry](sample/vue-sample).
+
+
 ## 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. 
+
+| :warning:  The tracker script does not listen to events inside shadow DOM. This is know limitation to be addressed in near term. |
+|--------------------------------------------------------------------------------------------------------------------------------------------|
+
 ### 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-nama` attribute.
+
+| :warning:  Currently the tracker script does not listen to events inside shadow DOM. This is know limitation to be addressed in near term. |
+|--------------------------------------------------------------------------------------------------------------------------------------------|
+
 ### 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
+<template>
+  <button @click="sendEvent()">Send Event</button>    
+</template>
+
+<script setup>
+import { inject } from 'vue'
+const waa = inject('waa');
+const sendEvent = async () => {
+  const params = {
+    session: 'cjhw92nf9aq',
+    cohort: 'c1233'
+  }  
+  waa.dispatchEvent('interest', params);  
+}
+</script>
+```

index.js

@@ -1,7 +1,9 @@
-
+import { initWideAngle } from "./src";
 
 export default {
-    install: (app, options) => {
-        
-    }
-}
+  install: (app, options) => {
+    initWideAngle(options)
+      .then(waa => { app.provide('waa', waa); })
+      .catch(e => { console.error("Failed to load Wide Angle Plugin", e)});
+  }
+}

sample/vue-sample/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["Vue.volar", "Vue.vscode-typescript-vue-plugin"]
+}

sample/vue-sample/README.md

@@ -0,0 +1,29 @@
+# vue-sample
+
+This template should help get you started developing with Vue 3 in Vite.
+
+## Recommended IDE Setup
+
+[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur) + [TypeScript Vue Plugin (Volar)](https://marketplace.visualstudio.com/items?itemName=Vue.vscode-typescript-vue-plugin).
+
+## Customize configuration
+
+See [Vite Configuration Reference](https://vitejs.dev/config/).
+
+## Project Setup
+
+```sh
+npm install
+```
+
+### Compile and Hot-Reload for Development
+
+```sh
+npm run dev
+```
+
+### Compile and Minify for Production
+
+```sh
+npm run build
+```

sample/vue-sample/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <link rel="icon" href="/favicon.ico">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Vite App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.js"></script>
+  </body>
+</html>

sample/vue-sample/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "vue-sample",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "vue": "^3.2.47",
+    "vue-router": "^4.1.6",
+    "wideangle-vue": "file:../../"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^4.0.0",
+    "vite": "^4.1.4"
+  }
+}

sample/vue-sample/src/App.vue

@@ -0,0 +1,32 @@
+<script setup>
+import { RouterLink, RouterView } from 'vue-router'
+</script>
+
+<template>
+  <div class="container">
+    <header>
+      <div class="wrapper">
+        <nav>
+          <RouterLink to="/">Home</RouterLink>
+          <RouterLink to="/sample">Sample</RouterLink>
+        </nav>
+      </div>
+    </header>
+
+    <RouterView />
+  </div>
+</template>
+
+
+<style scoped>
+nav {
+  display: flex;
+  flex-direction: row;
+  gap: 1rem;
+}
+.container {
+  display: flex;
+  flex-direction: column;
+  gap: 2rem;
+}
+</style>

sample/vue-sample/src/assets/main.css

@@ -0,0 +1,3 @@
+body {
+  font-size: 1.5rem;
+}

sample/vue-sample/src/main.js

@@ -0,0 +1,17 @@
+import { createApp } from 'vue'
+import App from './App.vue'
+import router from './router'
+import WideAngle from 'wideangle-vue'
+
+import './assets/main.css'
+
+const app = createApp(App)
+
+app.use(router)
+app.use(WideAngle, {
+  siteId: "8D27G3B9ACA01F4241",
+  domain: "wideangle.local:3000",
+  fingerprint: true,
+  supressDnt: true
+})
+app.mount('#app')

sample/vue-sample/src/router/index.js

@@ -0,0 +1,20 @@
+import { createRouter, createWebHistory } from 'vue-router'
+import HomeView from '../views/HomeView.vue'
+
+const router = createRouter({
+  history: createWebHistory(import.meta.env.BASE_URL),
+  routes: [
+    {
+      path: '/',
+      name: 'home',
+      component: HomeView
+    },
+    {
+      path: '/sample',
+      name: 'sample',
+      component: () => import('../views/SampleView.vue')
+    }
+  ]
+})
+
+export default router

sample/vue-sample/src/views/HomeView.vue

@@ -0,0 +1,6 @@
+<template>
+  <main>
+    <h1>Welcome screen</h1>
+    <p>Go to <RouterLink to="/sample">SAMPLE</RouterLink> for Custom Action demostration</p>
+  </main>
+</template>

sample/vue-sample/src/views/SampleView.vue

@@ -0,0 +1,34 @@
+<template>
+  <main>
+    <p>I am sample</p>
+    <button @click="sendEvent()">Send Event</button>
+    {{  status }}
+  </main>
+</template>
+
+<script setup>
+import { inject, ref } from 'vue'
+const waa = inject('waa');
+const status = ref('idle');
+
+const sendEvent = async () => {
+  const params = {
+    session: 'cjhw92nf9aq',
+    cohort: 'c1233'
+  }
+  console.log(`Sending event: ${JSON.stringify(params)}`);
+  status.value = 'pending...'
+  await waa.dispatchEvent('interest', params);
+  status.value = 'sent'
+}
+</script>
+
+
+<style scoped>
+main {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  max-width: 300px;
+}
+</style>

sample/vue-sample/vite.config.js

@@ -0,0 +1,13 @@
+import { fileURLToPath, URL } from 'node:url'
+
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+
+export default defineConfig({
+  plugins: [vue()],
+  resolve: {
+    alias: {
+      '@': fileURLToPath(new URL('./src', import.meta.url))
+    }
+  }
+})

src/index.js

@@ -1,3 +1,3 @@
-import WideAngle from './wideangle.js';
+import { initWideAngle } from './wideangle.js';
 
-export default WideAngle;
+export { initWideAngle };

src/wideangle.js

@@ -1 +1,31 @@
-export default {}
+function getScriptLink(settings) {
+  return `https://${settings.domain}/script/${settings.siteId}.js`;
+}
+
+function loadScript(settings) {
+  return new Promise(function(resolve, failure) {
+    const script = document.createElement('script');
+    script.src = getScriptLink(settings);
+    script.dataset.waaLateInit = true;
+    script.async = true;
+    script.onload = resolve;
+    script.onerror = failure;
+    document.head.appendChild(script);
+  });
+}
+
+async function initWideAngle(settings) {
+  if(document === undefined) {
+    throw Error("Wide Angle Analytics Plugin can be only used in the Browser");
+  }
+  try {
+    await loadScript(settings);
+    return waaCreate(settings);
+  } catch (e) {
+    console.error(`Failed to load Wide Angle script from ${getScriptLink(settings)}`)
+    throw e;
+  }
+}
+
+
+export { initWideAngle }