swetrix 2.3.1 → 3.0.0

package/dist/swetrix.orig.js

@@ -68,9 +68,33 @@
     var getUTMSource = function () { return findInSearch(utmSourceRegex); };
     var getUTMMedium = function () { return findInSearch(utmMediumRegex); };
     var getUTMCampaign = function () { return findInSearch(utmCampaignRegex); };
-    var getPath = function () {
-        // TODO: Maybe we should also include such data as location.hash or location.search
-        return location.pathname || '';
+    /**
+     * Function used to track the current page (path) of the application.
+     * Will work in cases where the path looks like:
+     * - /path
+     * - /#/path
+     * - /path?search
+     * - /path?search#hash
+     * - /path#hash?search
+     *
+     * @param options - Options for the function.
+     * @param options.hash - Whether to trigger on hash change.
+     * @param options.search - Whether to trigger on search change.
+     * @returns The path of the current page.
+     */
+    var getPath = function (options) {
+        var result = location.pathname || '';
+        if (options.hash) {
+            var hashIndex = location.hash.indexOf('?');
+            var hashString = hashIndex > -1 ? location.hash.substring(0, hashIndex) : location.hash;
+            result += hashString;
+        }
+        if (options.search) {
+            var hashIndex = location.hash.indexOf('?');
+            var searchString = location.search || (hashIndex > -1 ? location.hash.substring(hashIndex) : '');
+            result += searchString;
+        }
+        return result;
     };
 
     var defaultPageActions = {
@@ -92,7 +116,7 @@
             if (!this.canTrack()) {
                 return;
             }
-            var data = __assign({ pid: this.projectID, pg: this.activePage, lc: getLocale(), tz: getTimezone(), ref: getReferrer(), so: getUTMSource(), me: getUTMMedium(), ca: getUTMCampaign() }, event);
+            var data = __assign(__assign({}, event), { pid: this.projectID, pg: this.activePage, lc: getLocale(), tz: getTimezone(), ref: getReferrer(), so: getUTMSource(), me: getUTMMedium(), ca: getUTMCampaign() });
             this.sendRequest('custom', data);
         };
         Lib.prototype.trackPageViews = function (options) {
@@ -103,15 +127,16 @@
                 return this.pageData.actions;
             }
             this.pageViewsOptions = options;
-            var hbInterval, interval;
+            var interval;
             if (!(options === null || options === void 0 ? void 0 : options.unique)) {
                 interval = setInterval(this.trackPathChange, 2000);
             }
-            if (!(options === null || options === void 0 ? void 0 : options.noHeartbeat)) {
-                setTimeout(this.heartbeat, 3000);
-                hbInterval = setInterval(this.heartbeat, 28000);
-            }
-            var path = getPath();
+            setTimeout(this.heartbeat, 3000);
+            var hbInterval = setInterval(this.heartbeat, 28000);
+            var path = getPath({
+                hash: options === null || options === void 0 ? void 0 : options.hash,
+                search: options === null || options === void 0 ? void 0 : options.search,
+            });
             this.pageData = {
                 path: path,
                 actions: {
@@ -136,23 +161,17 @@
             this.perfStatsCollected = true;
             return {
                 // Network
-                // @ts-ignore
-                dns: perf.domainLookupEnd - perf.domainLookupStart,
-                // @ts-ignore
-                tls: perf.secureConnectionStart ? perf.requestStart - perf.secureConnectionStart : 0,
-                // @ts-ignore
-                conn: perf.secureConnectionStart ? perf.secureConnectionStart - perf.connectStart : perf.connectEnd - perf.connectStart,
-                // @ts-ignore
-                response: perf.responseEnd - perf.responseStart,
+                dns: perf.domainLookupEnd - perf.domainLookupStart, // DNS Resolution
+                tls: perf.secureConnectionStart ? perf.requestStart - perf.secureConnectionStart : 0, // TLS Setup; checking if secureConnectionStart is not 0 (it's 0 for non-https websites)
+                conn: perf.secureConnectionStart
+                    ? perf.secureConnectionStart - perf.connectStart
+                    : perf.connectEnd - perf.connectStart, // Connection time
+                response: perf.responseEnd - perf.responseStart, // Response Time (Download)
                 // Frontend
-                // @ts-ignore
-                render: perf.domComplete - perf.domContentLoadedEventEnd,
-                // @ts-ignore
-                dom_load: perf.domContentLoadedEventEnd - perf.responseEnd,
-                // @ts-ignore
-                page_load: perf.loadEventStart,
+                render: perf.domComplete - perf.domContentLoadedEventEnd, // Browser rendering the HTML time
+                dom_load: perf.domContentLoadedEventEnd - perf.responseEnd, // DOM loading timing
+                page_load: perf.loadEventStart, // Page load time
                 // Backend
-                // @ts-ignore
                 ttfb: perf.responseStart - perf.requestStart,
             };
         };
@@ -166,40 +185,25 @@
             };
             this.sendRequest('hb', data);
         };
-        Lib.prototype.checkIgnore = function (path) {
-            var _a;
-            var ignore = (_a = this.pageViewsOptions) === null || _a === void 0 ? void 0 : _a.ignore;
-            if (Array.isArray(ignore)) {
-                for (var i = 0; i < ignore.length; ++i) {
-                    if (ignore[i] === path)
-                        return true;
-                    // @ts-ignore
-                    if (ignore[i] instanceof RegExp && ignore[i].test(path))
-                        return true;
-                }
-            }
-            return false;
-        };
         // Tracking path changes. If path changes -> calling this.trackPage method
         Lib.prototype.trackPathChange = function () {
+            var _a, _b;
             if (!this.pageData)
                 return;
-            var newPath = getPath();
+            var newPath = getPath({
+                hash: (_a = this.pageViewsOptions) === null || _a === void 0 ? void 0 : _a.hash,
+                search: (_b = this.pageViewsOptions) === null || _b === void 0 ? void 0 : _b.search,
+            });
             var path = this.pageData.path;
             if (path !== newPath) {
                 this.trackPage(newPath, false);
             }
         };
         Lib.prototype.getPreviousPage = function () {
-            var _a, _b;
             // Assuming that this function is called in trackPage and this.activePage is not overwritten by new value yet
             // That method of getting previous page works for SPA websites
             if (this.activePage) {
-                var shouldIgnore = this.checkIgnore(this.activePage);
-                if (shouldIgnore && ((_a = this.pageViewsOptions) === null || _a === void 0 ? void 0 : _a.doNotAnonymise)) {
-                    return null;
-                }
-                return shouldIgnore ? null : this.activePage;
+                return this.activePage;
             }
             // Checking if URL is supported by the browser (for example, IE11 does not support it)
             if (typeof URL === 'function') {
@@ -215,73 +219,60 @@
                     if (host !== refHost) {
                         return null;
                     }
-                    var shouldIgnore = this.checkIgnore(pathname);
-                    if (shouldIgnore && ((_b = this.pageViewsOptions) === null || _b === void 0 ? void 0 : _b.doNotAnonymise)) {
-                        return null;
-                    }
-                    return shouldIgnore ? null : pathname;
+                    return pathname;
                 }
-                catch (_c) {
+                catch (_a) {
                     return null;
                 }
             }
             return null;
         };
         Lib.prototype.trackPage = function (pg, unique) {
-            var _a, _b;
             if (unique === void 0) { unique = false; }
             if (!this.pageData)
                 return;
             this.pageData.path = pg;
-            var shouldIgnore = this.checkIgnore(pg);
-            if (shouldIgnore && ((_a = this.pageViewsOptions) === null || _a === void 0 ? void 0 : _a.doNotAnonymise))
-                return;
             var perf = this.getPerformanceStats();
-            var prev;
-            if (!((_b = this.pageViewsOptions) === null || _b === void 0 ? void 0 : _b.noUserFlow)) {
-                prev = this.getPreviousPage();
-            }
-            var data = {
+            var prev = this.getPreviousPage();
+            this.activePage = pg;
+            this.submitPageView(pg, prev, unique, perf, true);
+        };
+        Lib.prototype.submitPageView = function (pg, prev, unique, perf, evokeCallback) {
+            var _a;
+            var privateData = {
                 pid: this.projectID,
+                perf: perf,
+                unique: unique,
+            };
+            var pvPayload = {
                 lc: getLocale(),
                 tz: getTimezone(),
                 ref: getReferrer(),
                 so: getUTMSource(),
                 me: getUTMMedium(),
                 ca: getUTMCampaign(),
-                unique: unique,
-                pg: shouldIgnore ? null : pg,
-                perf: perf,
+                pg: pg,
                 prev: prev,
             };
-            this.activePage = pg;
-            this.sendRequest('', data);
-        };
-        Lib.prototype.debug = function (message) {
-            var _a;
-            if ((_a = this.options) === null || _a === void 0 ? void 0 : _a.debug) {
-                console.log('[Swetrix]', message);
+            if (evokeCallback && ((_a = this.pageViewsOptions) === null || _a === void 0 ? void 0 : _a.callback)) {
+                var callbackResult = this.pageViewsOptions.callback(pvPayload);
+                if (callbackResult === false) {
+                    return;
+                }
+                if (callbackResult && typeof callbackResult === 'object') {
+                    Object.assign(pvPayload, callbackResult);
+                }
             }
+            Object.assign(pvPayload, privateData);
+            this.sendRequest('', pvPayload);
         };
         Lib.prototype.canTrack = function () {
             var _a, _b, _c, _d;
-            if ((_a = this.options) === null || _a === void 0 ? void 0 : _a.disabled) {
-                this.debug('Tracking disabled: the \'disabled\' setting is set to true.');
-                return false;
-            }
-            if (!isInBrowser()) {
-                this.debug('Tracking disabled: script does not run in browser environment.');
-                return false;
-            }
-            if (((_b = this.options) === null || _b === void 0 ? void 0 : _b.respectDNT) && ((_c = window.navigator) === null || _c === void 0 ? void 0 : _c.doNotTrack) === '1') {
-                this.debug('Tracking disabled: respecting user\'s \'Do Not Track\' preference.');
-                return false;
-            }
-            if (!((_d = this.options) === null || _d === void 0 ? void 0 : _d.debug) && isLocalhost()) {
-                return false;
-            }
-            if (isAutomated()) {
-                this.debug('Tracking disabled: navigation is automated by WebDriver.');
+            if (((_a = this.options) === null || _a === void 0 ? void 0 : _a.disabled) ||
+                !isInBrowser() ||
+                (((_b = this.options) === null || _b === void 0 ? void 0 : _b.respectDNT) && ((_c = window.navigator) === null || _c === void 0 ? void 0 : _c.doNotTrack) === '1') ||
+                (!((_d = this.options) === null || _d === void 0 ? void 0 : _d.devMode) && isLocalhost()) ||
+                isAutomated()) {
                 return false;
             }
             return true;
@@ -349,9 +340,24 @@
             }
         });
     }
+    /**
+     * This function is used to manually track a page view event.
+     * It's useful if your application uses esoteric routing which is not supported by Swetrix by default.
+     *
+     * @param path Path of the page to track (this will be sent to the Swetrix API and displayed in the dashboard).
+     * @param prev Path of the previous page.
+     * @param unique If set to `true`, only 1 event with the same ID will be saved per user session.
+     * @returns void
+     */
+    function trackPageview(path, prev, unique) {
+        if (!exports.LIB_INSTANCE)
+            return;
+        exports.LIB_INSTANCE.submitPageView(path, prev || null, Boolean(unique), {});
+    }
 
     exports.init = init;
     exports.track = track;
+    exports.trackPageview = trackPageview;
     exports.trackViews = trackViews;
 
     Object.defineProperty(exports, '__esModule', { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swetrix",
-  "version": "2.3.1",
+  "version": "3.0.0",
   "description": "The JavaScript analytics client for Swetrix Analytics",
   "main": "dist/swetrix.cjs.js",
   "module": "dist/swetrix.es5.js",
@@ -32,13 +32,13 @@
   "bugs": {
     "url": "https://github.com/Swetrix/swetrix-js/issues"
   },
-  "homepage": "https://swetrix.com/docs",
+  "homepage": "https://docs.swetrix.com",
   "dependencies": {
-    "@types/node": "^20.8.6",
+    "@types/node": "^20.11.8",
     "tslib": "^2.6.2"
   },
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^25.0.5",
+    "@rollup/plugin-commonjs": "^25.0.7",
     "@rollup/plugin-node-resolve": "^15.2.3",
     "rimraf": "^4.4.1",
     "rollup": "^2.79.1",
@@ -46,6 +46,6 @@
     "rollup-plugin-sourcemaps": "^0.6.3",
     "rollup-plugin-typescript2": "^0.36.0",
     "rollup-plugin-uglify": "^6.0.4",
-    "typescript": "^5.2.2"
+    "typescript": "^5.3.3"
   }
 }

package/src/Lib.ts

@@ -1,13 +1,21 @@
 import {
-  isInBrowser, isLocalhost, isAutomated, getLocale, getTimezone, getReferrer,
-  getUTMCampaign, getUTMMedium, getUTMSource, getPath,
+  isInBrowser,
+  isLocalhost,
+  isAutomated,
+  getLocale,
+  getTimezone,
+  getReferrer,
+  getUTMCampaign,
+  getUTMMedium,
+  getUTMSource,
+  getPath,
 } from './utils'
 
 export interface LibOptions {
   /**
-   * When set to `true`, all tracking logs will be printed to console and localhost events will be sent to server.
+   * When set to `true`, localhost events will be sent to server.
    */
-  debug?: boolean
+  devMode?: boolean
 
   /**
    * When set to `true`, the tracking library won't send any data to server.
@@ -37,6 +45,29 @@ export interface TrackEventOptions {
   }
 }
 
+// Partial user-editable pageview payload
+export interface IPageViewPayload {
+  lc: string | undefined
+  tz: string | undefined
+  ref: string | undefined
+  so: string | undefined
+  me: string | undefined
+  ca: string | undefined
+  pg: string
+  prev: string | null | undefined
+}
+
+interface IPerfPayload {
+  dns: number
+  tls: number
+  conn: number
+  response: number
+  render: number
+  dom_load: number
+  page_load: number
+  ttfb: number
+}
+
 /**
  * The object returned by `trackPageViews()`, used to stop tracking pages.
  */
@@ -60,20 +91,28 @@ export interface PageViewsOptions {
    */
   unique?: boolean
 
-  /** A list of Regular Expressions or string pathes to ignore. */
-  ignore?: Array<string | RegExp>
-
-  /** Do not send paths from ignore list to API. If set to `false`, the page view information will be sent to the Swetrix API, but the page will be displayed as a 'Redacted page' in the dashboard. */
-  doNotAnonymise?: boolean
-
-  /** Do not send Heartbeat requests to the server. */
-  noHeartbeat?: boolean
-
   /** Send Heartbeat requests when the website tab is not active in the browser. */
   heartbeatOnBackground?: boolean
 
-  /** Disable user-flow */
-  noUserFlow?: boolean
+  /**
+   * Set to `true` to enable hash-based routing.
+   * For example if you have pages like /#/path or want to track pages like /path#hash
+   */
+  hash?: boolean
+
+  /**
+   * Set to `true` to enable search-based routing.
+   * For example if you have pages like /path?search
+   */
+  search?: boolean
+
+  /**
+   * Callback to edit / prevent sending pageviews.
+   *
+   * @param payload - The pageview payload.
+   * @returns The edited payload or `false` to prevent sending the pageview. If `true` is returned, the payload will be sent as-is.
+   */
+  callback?: (payload: IPageViewPayload) => IPageViewPayload | boolean
 }
 
 export const defaultPageActions = {
@@ -99,6 +138,7 @@ export class Lib {
     }
 
     const data = {
+      ...event,
       pid: this.projectID,
       pg: this.activePage,
       lc: getLocale(),
@@ -107,7 +147,6 @@ export class Lib {
       so: getUTMSource(),
       me: getUTMMedium(),
       ca: getUTMCampaign(),
-      ...event,
     }
     this.sendRequest('custom', data)
   }
@@ -122,17 +161,19 @@ export class Lib {
     }
 
     this.pageViewsOptions = options
-    let hbInterval: NodeJS.Timeout, interval: NodeJS.Timeout
+    let interval: NodeJS.Timeout
+
     if (!options?.unique) {
       interval = setInterval(this.trackPathChange, 2000)
     }
 
-    if (!options?.noHeartbeat) {
-      setTimeout(this.heartbeat, 3000)
-      hbInterval = setInterval(this.heartbeat, 28000)
-    }
+    setTimeout(this.heartbeat, 3000)
+    const hbInterval = setInterval(this.heartbeat, 28000)
 
-    const path = getPath()
+    const path = getPath({
+      hash: options?.hash,
+      search: options?.search,
+    })
 
     this.pageData = {
       path,
@@ -148,12 +189,12 @@ export class Lib {
     return this.pageData.actions
   }
 
-  getPerformanceStats(): object {
+  getPerformanceStats(): IPerfPayload | {} {
     if (!this.canTrack() || this.perfStatsCollected || !window.performance?.getEntriesByType) {
       return {}
     }
 
-    const perf = window.performance.getEntriesByType('navigation')[0]
+    const perf = window.performance.getEntriesByType('navigation')[0] as PerformanceNavigationTiming
 
     if (!perf) {
       return {}
@@ -163,25 +204,19 @@ export class Lib {
 
     return {
       // Network
-      // @ts-ignore
       dns: perf.domainLookupEnd - perf.domainLookupStart, // DNS Resolution
-      // @ts-ignore
       tls: perf.secureConnectionStart ? perf.requestStart - perf.secureConnectionStart : 0, // TLS Setup; checking if secureConnectionStart is not 0 (it's 0 for non-https websites)
-      // @ts-ignore
-      conn: perf.secureConnectionStart ? perf.secureConnectionStart - perf.connectStart : perf.connectEnd - perf.connectStart, // Connection time
-      // @ts-ignore
+      conn: perf.secureConnectionStart
+        ? perf.secureConnectionStart - perf.connectStart
+        : perf.connectEnd - perf.connectStart, // Connection time
       response: perf.responseEnd - perf.responseStart, // Response Time (Download)
 
       // Frontend
-      // @ts-ignore
       render: perf.domComplete - perf.domContentLoadedEventEnd, // Browser rendering the HTML time
-      // @ts-ignore
       dom_load: perf.domContentLoadedEventEnd - perf.responseEnd, // DOM loading timing
-      // @ts-ignore
       page_load: perf.loadEventStart, // Page load time
 
       // Backend
-      // @ts-ignore
       ttfb: perf.responseStart - perf.requestStart,
     }
   }
@@ -198,23 +233,13 @@ export class Lib {
     this.sendRequest('hb', data)
   }
 
-  private checkIgnore(path: string): boolean {
-    const ignore = this.pageViewsOptions?.ignore
-
-    if (Array.isArray(ignore)) {
-      for (let i = 0; i < ignore.length; ++i) {
-        if (ignore[i] === path) return true
-        // @ts-ignore
-        if (ignore[i] instanceof RegExp && ignore[i].test(path)) return true
-      }
-    }
-    return false
-  }
-
   // Tracking path changes. If path changes -> calling this.trackPage method
   private trackPathChange(): void {
     if (!this.pageData) return
-    const newPath = getPath()
+    const newPath = getPath({
+      hash: this.pageViewsOptions?.hash,
+      search: this.pageViewsOptions?.search,
+    })
     const { path } = this.pageData
 
     if (path !== newPath) {
@@ -226,13 +251,7 @@ export class Lib {
     // Assuming that this function is called in trackPage and this.activePage is not overwritten by new value yet
     // That method of getting previous page works for SPA websites
     if (this.activePage) {
-      const shouldIgnore = this.checkIgnore(this.activePage)
-
-      if (shouldIgnore && this.pageViewsOptions?.doNotAnonymise) {
-        return null
-      }
-
-      return shouldIgnore ? null : this.activePage
+      return this.activePage
     }
 
     // Checking if URL is supported by the browser (for example, IE11 does not support it)
@@ -254,13 +273,7 @@ export class Lib {
           return null
         }
 
-        const shouldIgnore = this.checkIgnore(pathname)
-
-        if (shouldIgnore && this.pageViewsOptions?.doNotAnonymise) {
-          return null
-        }
-
-        return shouldIgnore ? null : pathname
+        return pathname
       } catch {
         return null
       }
@@ -273,64 +286,62 @@ export class Lib {
     if (!this.pageData) return
     this.pageData.path = pg
 
-    const shouldIgnore = this.checkIgnore(pg)
-
-    if (shouldIgnore && this.pageViewsOptions?.doNotAnonymise) return
-
     const perf = this.getPerformanceStats()
 
-    let prev
+    const prev = this.getPreviousPage()
 
-    if (!this.pageViewsOptions?.noUserFlow) {
-      prev = this.getPreviousPage()
-    }
+    this.activePage = pg
+    this.submitPageView(pg, prev, unique, perf, true)
+  }
 
-    const data = {
+  submitPageView(
+    pg: string,
+    prev: string | null | undefined,
+    unique: boolean,
+    perf: IPerfPayload | {},
+    evokeCallback?: boolean,
+  ): void {
+    const privateData = {
       pid: this.projectID,
+      perf,
+      unique,
+    }
+    const pvPayload = {
       lc: getLocale(),
       tz: getTimezone(),
       ref: getReferrer(),
       so: getUTMSource(),
       me: getUTMMedium(),
       ca: getUTMCampaign(),
-      unique,
-      pg: shouldIgnore ? null : pg,
-      perf,
+      pg,
       prev,
     }
 
-    this.activePage = pg
-    this.sendRequest('', data)
-  }
-
-  private debug(message: string): void {
-    if (this.options?.debug) {
-      console.log('[Swetrix]', message)
-    }
-  }
+    if (evokeCallback && this.pageViewsOptions?.callback) {
+      const callbackResult = this.pageViewsOptions.callback(pvPayload)
 
-  private canTrack(): boolean {
-    if (this.options?.disabled) {
-      this.debug('Tracking disabled: the \'disabled\' setting is set to true.')
-      return false
-    }
+      if (callbackResult === false) {
+        return
+      }
 
-    if (!isInBrowser()) {
-      this.debug('Tracking disabled: script does not run in browser environment.')
-      return false
+      if (callbackResult && typeof callbackResult === 'object') {
+        Object.assign(pvPayload, callbackResult)
+      }
     }
 
-    if (this.options?.respectDNT && window.navigator?.doNotTrack === '1') {
-      this.debug('Tracking disabled: respecting user\'s \'Do Not Track\' preference.')
-      return false
-    }
+    Object.assign(pvPayload, privateData)
 
-    if (!this.options?.debug && isLocalhost()) {
-      return false
-    }
+    this.sendRequest('', pvPayload)
+  }
 
-    if (isAutomated()) {
-      this.debug('Tracking disabled: navigation is automated by WebDriver.')
+  private canTrack(): boolean {
+    if (
+      this.options?.disabled ||
+      !isInBrowser() ||
+      (this.options?.respectDNT && window.navigator?.doNotTrack === '1') ||
+      (!this.options?.devMode && isLocalhost()) ||
+      isAutomated()
+    ) {
       return false
     }
 

package/src/index.ts

@@ -1,6 +1,4 @@
-import {
-  Lib, LibOptions, TrackEventOptions, PageViewsOptions, PageActions, defaultPageActions,
-} from './Lib'
+import { Lib, LibOptions, TrackEventOptions, PageViewsOptions, PageActions, defaultPageActions } from './Lib'
 
 export let LIB_INSTANCE: Lib | null = null
 
@@ -58,3 +56,18 @@ export function trackViews(options?: PageViewsOptions): Promise<PageActions> {
     }
   })
 }
+
+/**
+ * This function is used to manually track a page view event.
+ * It's useful if your application uses esoteric routing which is not supported by Swetrix by default.
+ *
+ * @param path Path of the page to track (this will be sent to the Swetrix API and displayed in the dashboard).
+ * @param prev Path of the previous page.
+ * @param unique If set to `true`, only 1 event with the same ID will be saved per user session.
+ * @returns void
+ */
+export function trackPageview(path: string, prev?: string, unique?: boolean): void {
+  if (!LIB_INSTANCE) return
+
+  LIB_INSTANCE.submitPageView(path, prev || null, Boolean(unique), {})
+}