@pageviews/tracker 0.1.0 → 0.2.3

package/README.md

@@ -0,0 +1,145 @@
+# @pageviews/tracker
+
+The official JavaScript SDK for [Pageviews.ai](https://pageviews.ai) — a lightweight, cookie-free analytics platform built for privacy.
+
+Use this package to add analytics to React, Vue, Next.js, or any other JavaScript framework with full programmatic control over pageview and event tracking.
+
+> For simple script tag installation (no build step), see the [Script Tag guide](https://pageviews.ai/docs) instead.
+
+## Features
+
+- Cookie-free and GDPR-compliant — no consent banner required
+- Automatic pageview tracking for SPAs (React Router, Vue Router, Next.js App Router)
+- Custom event tracking with properties and revenue data
+- Engagement tracking — active time and scroll depth per page
+- Auto-tracking for outbound links, file downloads, and form submissions
+- Realtime User Explorer via `identify()`
+- Full TypeScript support
+
+## Installation
+
+```bash
+npm install @pageviews/tracker
+```
+
+## Quick Start
+
+```js
+import { init, track, identify } from '@pageviews/tracker'
+
+// Initialize once at your app's entry point
+await init({ siteId: 'your-site-id' })
+
+// Track custom events
+track('signup', { props: { plan: 'pro' } })
+
+// Identify a logged-in user for the Realtime User Explorer
+identify({ userId: 'user-123' })
+```
+
+Your site ID is available in the Pageviews dashboard under **Settings → Tracking**.
+
+## Framework Examples
+
+### Next.js (App Router)
+
+```tsx
+// app/providers.tsx
+'use client'
+
+import { useEffect } from 'react'
+import { init, destroy } from '@pageviews/tracker'
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  useEffect(() => {
+    init({ siteId: 'your-site-id' })
+    return () => destroy()
+  }, [])
+
+  return <>{children}</>
+}
+```
+
+### React
+
+```jsx
+// Entry point or layout component
+import { useEffect } from 'react'
+import { init, destroy } from '@pageviews/tracker'
+
+export function AnalyticsProvider({ children, siteId }) {
+  useEffect(() => {
+    init({ siteId })
+    return () => destroy()
+  }, [siteId])
+
+  return children
+}
+```
+
+### Vue
+
+```js
+// main.js
+import { init } from '@pageviews/tracker'
+
+init({ siteId: 'your-site-id' })
+```
+
+## API
+
+### `init(options): Promise<void>`
+
+Initializes the tracker. Call once at your app's entry point.
+
+```ts
+await init({
+  siteId: 'your-site-id',   // required — from your Pageviews dashboard
+  endpoint?: string,         // optional — custom ingest URL (self-hosted / proxy)
+  configEndpoint?: string,   // optional — custom config URL
+})
+```
+
+On init, site configuration (routing mode, auto-tracking rules, scroll goals) is fetched from the Pageviews API and cached in `localStorage` for 1 hour.
+
+### `track(eventName, options?): void`
+
+Sends a custom event.
+
+```ts
+track('purchase', {
+  props: { plan: 'pro', annual: true },
+  revenue: { amount: 49, currency: 'USD' },
+  callback: (result) => console.log(result),
+})
+```
+
+### `identify(data): void`
+
+Associates a user identifier with the current session. Appears in the Realtime User Explorer in the dashboard. **Not persisted to the database** — stored in memory only for the duration of the session.
+
+```ts
+identify({ userId: 'user-123' })
+```
+
+### `destroy(): void`
+
+Stops all tracking and resets state. Useful for SPA cleanup or testing. `init()` can be called again after `destroy()`.
+
+## Privacy
+
+- No cookies or persistent browser identifiers set
+- Query parameters containing potential PII are stripped from URLs before sending — only UTM parameters and `ref` are kept
+- Referrer query strings are stripped entirely — only the domain and path are sent
+- IP addresses are hashed server-side with a daily-rotating salt and never stored in raw form
+- No cross-site tracking
+
+## Full Documentation
+
+For configuration options, advanced usage, and the script tag installation method, see the full docs:
+
+**[pageviews.ai/docs/npm-module-at-pageviewstracker](https://pageviews.ai/docs/npm-module-at-pageviewstracker)**
+
+## License
+
+MIT

package/dist/module/index.cjs

@@ -35,6 +35,35 @@ function sendBeaconEvent(endpoint, payload, siteId) {
 }
 
 // src/core/utils.ts
+const ALLOWED_QUERY_PARAMS = new Set([
+    'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'ref',
+]);
+function sanitizeUrl(url) {
+    try {
+        const u = new URL(url);
+        const toDelete = [];
+        u.searchParams.forEach((_, key) => {
+            if (!ALLOWED_QUERY_PARAMS.has(key))
+                toDelete.push(key);
+        });
+        toDelete.forEach(key => u.searchParams.delete(key));
+        return u.toString();
+    }
+    catch (_a) {
+        return url;
+    }
+}
+function sanitizeReferrer(referrer) {
+    if (!referrer)
+        return referrer;
+    try {
+        const u = new URL(referrer);
+        return u.origin + u.pathname;
+    }
+    catch (_a) {
+        return referrer;
+    }
+}
 function getScreenSize() {
     return `${window.innerWidth}x${window.innerHeight}`;
 }
@@ -75,8 +104,8 @@ function createTracker(config) {
         const payload = {
             n: 'pageview',
             d: config.site,
-            u: url || location.href,
-            r: document.referrer || null,
+            u: sanitizeUrl(url || location.href),
+            r: sanitizeReferrer(document.referrer) || null,
             s: getScreenSize(),
         };
         if (config.hashRouting)
@@ -87,8 +116,8 @@ function createTracker(config) {
         const payload = {
             n: eventName,
             d: config.site,
-            u: (options === null || options === void 0 ? void 0 : options.url) || location.href,
-            r: document.referrer || null,
+            u: sanitizeUrl((options === null || options === void 0 ? void 0 : options.url) || location.href),
+            r: sanitizeReferrer(document.referrer) || null,
             s: getScreenSize(),
         };
         if (options === null || options === void 0 ? void 0 : options.props) {
@@ -113,7 +142,7 @@ function createTracker(config) {
         const payload = {
             n: 'identify',
             d: config.site,
-            u: location.href,
+            u: sanitizeUrl(location.href),
             r: null,
             s: getScreenSize(),
             uid: data.userId,
@@ -284,7 +313,7 @@ function startEventTracking(trackFn, config) {
             return;
         }
         if (config.outboundLinks && isOutbound(link)) {
-            trackFn('Outbound Link: Click', { props: { url: href } });
+            trackFn('Outbound Link: Click', { props: { url: cleanUrl } });
         }
     };
     document.addEventListener('click', clickHandler);
@@ -352,7 +381,7 @@ function setupTracking(config, tracker) {
     stopEngagement();
     startEngagement();
     let isFirstPageview = true;
-    let currentUrl = location.href;
+    let currentUrl = sanitizeUrl(location.href);
     startNavTracking(() => {
         // Send engagement for previous page (skip on first pageview)
         if (!isFirstPageview) {
@@ -371,7 +400,7 @@ function setupTracking(config, tracker) {
             resetEngagement();
         }
         isFirstPageview = false;
-        currentUrl = location.href;
+        currentUrl = sanitizeUrl(location.href);
         tracker.trackPageview();
         stopScrollGoals();
         if (config.scrollTargets.length > 0) {

package/dist/module/index.mjs

@@ -33,6 +33,35 @@ function sendBeaconEvent(endpoint, payload, siteId) {
 }
 
 // src/core/utils.ts
+const ALLOWED_QUERY_PARAMS = new Set([
+    'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'ref',
+]);
+function sanitizeUrl(url) {
+    try {
+        const u = new URL(url);
+        const toDelete = [];
+        u.searchParams.forEach((_, key) => {
+            if (!ALLOWED_QUERY_PARAMS.has(key))
+                toDelete.push(key);
+        });
+        toDelete.forEach(key => u.searchParams.delete(key));
+        return u.toString();
+    }
+    catch (_a) {
+        return url;
+    }
+}
+function sanitizeReferrer(referrer) {
+    if (!referrer)
+        return referrer;
+    try {
+        const u = new URL(referrer);
+        return u.origin + u.pathname;
+    }
+    catch (_a) {
+        return referrer;
+    }
+}
 function getScreenSize() {
     return `${window.innerWidth}x${window.innerHeight}`;
 }
@@ -73,8 +102,8 @@ function createTracker(config) {
         const payload = {
             n: 'pageview',
             d: config.site,
-            u: url || location.href,
-            r: document.referrer || null,
+            u: sanitizeUrl(url || location.href),
+            r: sanitizeReferrer(document.referrer) || null,
             s: getScreenSize(),
         };
         if (config.hashRouting)
@@ -85,8 +114,8 @@ function createTracker(config) {
         const payload = {
             n: eventName,
             d: config.site,
-            u: (options === null || options === void 0 ? void 0 : options.url) || location.href,
-            r: document.referrer || null,
+            u: sanitizeUrl((options === null || options === void 0 ? void 0 : options.url) || location.href),
+            r: sanitizeReferrer(document.referrer) || null,
             s: getScreenSize(),
         };
         if (options === null || options === void 0 ? void 0 : options.props) {
@@ -111,7 +140,7 @@ function createTracker(config) {
         const payload = {
             n: 'identify',
             d: config.site,
-            u: location.href,
+            u: sanitizeUrl(location.href),
             r: null,
             s: getScreenSize(),
             uid: data.userId,
@@ -282,7 +311,7 @@ function startEventTracking(trackFn, config) {
             return;
         }
         if (config.outboundLinks && isOutbound(link)) {
-            trackFn('Outbound Link: Click', { props: { url: href } });
+            trackFn('Outbound Link: Click', { props: { url: cleanUrl } });
         }
     };
     document.addEventListener('click', clickHandler);
@@ -350,7 +379,7 @@ function setupTracking(config, tracker) {
     stopEngagement();
     startEngagement();
     let isFirstPageview = true;
-    let currentUrl = location.href;
+    let currentUrl = sanitizeUrl(location.href);
     startNavTracking(() => {
         // Send engagement for previous page (skip on first pageview)
         if (!isFirstPageview) {
@@ -369,7 +398,7 @@ function setupTracking(config, tracker) {
             resetEngagement();
         }
         isFirstPageview = false;
-        currentUrl = location.href;
+        currentUrl = sanitizeUrl(location.href);
         tracker.trackPageview();
         stopScrollGoals();
         if (config.scrollTargets.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pageviews/tracker",
-  "version": "0.1.0",
+  "version": "0.2.3",
   "description": "Lightweight, cookie-free analytics tracker for PageViews.ai",
   "author": "Pageviews <hello@pageviews.ai>",
   "homepage": "https://pageviews.ai",
@@ -28,7 +28,7 @@
     }
   },
   "files": [
-    "dist"
+    "dist/module"
   ],
   "scripts": {
     "build": "rollup -c",

package/dist/tracker.js

@@ -1 +0,0 @@
-!function(){"use strict";function t(t,e,n,i){if("undefined"==typeof fetch)return;const o={"Content-Type":"text/plain"};i&&(o["X-Site-ID"]=i),fetch(t,{method:"POST",headers:o,keepalive:!0,body:JSON.stringify(e)}).then(t=>{n&&n({status:t.status})}).catch(t=>{n&&n({error:t})})}function e(){return`${window.innerWidth}x${window.innerHeight}`}let n=null,i=0,o=0,r=!1,s=0,c=!1,a=0;function l(){const t=document.body||{},e=document.documentElement||{};return Math.max(t.scrollHeight||0,t.offsetHeight||0,e.scrollHeight||0,e.offsetHeight||0)}function u(){a=l()}function d(){"hidden"===document.visibilityState?r&&(o+=Date.now()-i,r=!1):"visible"===document.visibilityState&&(i=Date.now(),r=!0)}function v(){c||(c=!0,requestAnimationFrame(()=>{const t=function(){if(0===a)return 0;const t=window.innerHeight||0;if(a<=t)return 100;const e=window.scrollY||document.documentElement.scrollTop||0;return Math.round((e+t)/a*100)}();t>s&&(s=t),c=!1}))}function m(){document.removeEventListener("visibilitychange",d),document.removeEventListener("scroll",v),window.removeEventListener("resize",u)}function f(){const t=r?Date.now()-i:0;return{activeTime:o+t,maxScrollDepth:s}}const h=["pdf","xlsx","docx","txt","rtf","csv","exe","key","pps","ppt","pptx","7z","pkg","rar","gz","zip","avi","mov","mp4","mpeg","wmv","midi","mp3","wav","wma","dmg"];let p=null,g=null;function w(){p&&(document.removeEventListener("click",p),p=null),g&&(document.removeEventListener("submit",g,!0),g=null)}let y=null;function b(){y&&(document.removeEventListener("scroll",y),y=null)}function E(c,E){m(),m(),i=Date.now(),o=0,s=0,r=!0,a=l(),document.addEventListener("visibilitychange",d),document.addEventListener("scroll",v,{passive:!0}),window.addEventListener("resize",u,{passive:!0});let L=!0,S=location.href;!function(t,e){let i=location.pathname;const o=()=>{(e||location.pathname!==i)&&(i=location.pathname,t())};if(t(),e)window.addEventListener("hashchange",o),n=()=>window.removeEventListener("hashchange",o);else{const e=history.pushState;history.pushState=function(...t){e.apply(this,t),o()};const r=()=>{i=location.pathname,t()};window.addEventListener("popstate",r),n=()=>{history.pushState=e,window.removeEventListener("popstate",r)}}const r=e=>{e.persisted&&t()};window.addEventListener("pageshow",r);const s=n;n=()=>{null==s||s(),window.removeEventListener("pageshow",r)}}(()=>{if(!L){const n=f();n.activeTime>=1e3&&t(c.endpoint,{n:"engagement",d:c.site,u:S,r:null,s:e(),sd:n.maxScrollDepth,e:n.activeTime},void 0,c.siteId),i=Date.now(),o=0,s=0,r=!0}L=!1,S=location.href,E.trackPageview(),b(),c.scrollTargets.length>0&&function(t,e,n){const i=e.filter(t=>t.path===n);if(0===i.length)return;const o=new Set;let r=!1;y=()=>{r||(r=!0,requestAnimationFrame(()=>{var e;const n=Math.max(document.documentElement.scrollHeight||0,(null===(e=document.body)||void 0===e?void 0:e.scrollHeight)||0),s=window.innerHeight||0,c=window.scrollY||0,a=n<=s?100:Math.round((c+s)/n*100);for(const e of i)!o.has(e.goalName)&&a>=e.threshold&&(o.add(e.goalName),t(e.goalName));r=!1}))},document.addEventListener("scroll",y,{passive:!0})}(t=>E.track(t),c.scrollTargets,location.pathname)},c.hashRouting),function(t,e){w(),p=n=>{const i=function(t){let e=t;for(;e&&"A"!==e.tagName;)e=e.parentElement;return e}(n.target);if(!i||!i.href)return;const o=i.href,r=o.split("?")[0];e.fileDownloads&&function(t){var e;const n=null===(e=t.split("?")[0].split(".").pop())||void 0===e?void 0:e.toLowerCase();return!!n&&h.includes(n)}(o)?t("File Download",{props:{url:r}}):e.outboundLinks&&function(t){return""!==t.host&&t.host!==location.host}(i)&&t("Outbound Link: Click",{props:{url:o}})},document.addEventListener("click",p),e.formSubmissions&&(g=e=>{const n=e.target;(n.hasAttribute("novalidate")||n.checkValidity())&&t("Form Submission")},document.addEventListener("submit",g,!0))}((t,e)=>E.track(t,e),{outboundLinks:c.outboundLinks,fileDownloads:c.fileDownloads,formSubmissions:c.formSubmissions});const k=()=>{if("hidden"===document.visibilityState){const n=f();n.activeTime>=1e3&&function(e,n,i){const o=JSON.stringify(n);if("undefined"!=typeof navigator&&navigator.sendBeacon){const t=new Blob([o],{type:"text/plain"});if(navigator.sendBeacon(e,t))return}t(e,n,void 0,i)}(c.endpoint,{n:"engagement",d:c.site,u:S,r:null,s:e(),sd:n.maxScrollDepth,e:n.activeTime},c.siteId)}};return document.addEventListener("visibilitychange",k),()=>{null==n||n(),n=null,m(),w(),b(),document.removeEventListener("visibilitychange",k)}}!function(){var n;const i=document.currentScript;if(!i)return;const o="undefined"!=typeof __PAGEVIEWS_CONFIG__?__PAGEVIEWS_CONFIG__:null;if(!o)return;const r=i.getAttribute("data-api")||void 0,s=function(t,e){return e||"https://data.pageviews.ai/api/event"}(i.src,r),c=Object.assign(Object.assign({},o),{endpoint:s}),{tracker:a}=function(n){const i=function(n){const i="localhost"===(o=location.hostname)||/^127(\.[0-9]+){0,2}\.[0-9]+$/.test(o)||"[::1]"===o||function(){try{return"true"===window.localStorage.getItem("pageviews_ignore")}catch(t){return!1}}()||function(){const t=window,e=navigator;return!!(t._phantom||t.__nightmare||e.webdriver||t.Cypress||t.__puppeteer_evaluation_script__||t.__playwright)}();var o;function r(e,o){i?null==o||o():t(n.endpoint,e,o,n.siteId)}return{trackPageview:function(t){const i={n:"pageview",d:n.site,u:t||location.href,r:document.referrer||null,s:e()};n.hashRouting&&(i.h=!0),r(i)},track:function(t,i){const o={n:t,d:n.site,u:(null==i?void 0:i.url)||location.href,r:document.referrer||null,s:e()};if(null==i?void 0:i.props){const t={};for(const[e,n]of Object.entries(i.props))t[e]=String(n);o.p=t}if(null==i?void 0:i.revenue){const{amount:t,currency:e}=i.revenue;t>0&&t<=1e9&&e&&(o.rv={a:t,c:e})}n.hashRouting&&(o.h=!0),r(o,null==i?void 0:i.callback)},identify:function(t){r({n:"identify",d:n.site,u:location.href,r:null,s:e(),uid:t.userId})}}}(n);let o=null;if("prerender"===document.visibilityState){const t=()=>{"visible"===document.visibilityState&&(document.removeEventListener("visibilitychange",t),o=E(n,i))};return document.addEventListener("visibilitychange",t),{tracker:i,destroy:()=>{document.removeEventListener("visibilitychange",t),null==o||o()}}}return o=E(n,i),{tracker:i,destroy:()=>{null==o||o()}}}(c),l=i.getAttribute("data-user-id");l&&a.identify({userId:l});const u=(t,...e)=>{"track"===t?a.track(e[0],e[1]):"identify"===t&&a.identify(e[0])},d=null===(n=window.pageviews)||void 0===n?void 0:n.q;Array.isArray(d)&&d.forEach(t=>u(t[0],...t.slice(1))),window.pageviews=u}()}();