Skip to content

📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!

Returning PageActions for trackViews & improved the documentation

Blue Mouseedf311be9446
diff --git a/src/Lib.ts b/src/Lib.ts
index 17a8a90e4..3af1b50eb 100644
--- a/src/Lib.ts
+++ b/src/Lib.ts
@@ -4,53 +4,71 @@ import {
} 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`, all tracking logs will be printed to console and localhost events will be sent to server.
+ */
debug?: boolean
- // When set to `true`, the tracking library won't send any data to server.
- // Useful for development purposes when this value is set based on `.env` var.
+ /**
+ * When set to `true`, the tracking library won't send any data to server.
+ * Useful for development purposes when this value is set based on `.env` var.
+ */
disabled?: boolean
- // By setting this flag to `true`, we will not collect ANY kind of data about the user
- // with the DNT setting.
+ /**
+ * By setting this flag to `true`, we will not collect ANY kind of data about the user with the DNT setting.
+ */
respectDNT?: boolean
- // Set a custom URL of the API server (for selfhosted variants of Swetrix)
+ /** Set a custom URL of the API server (for selfhosted variants of Swetrix). */
apiURL?: string
}
export interface TrackEventOptions {
- // The event name
+ /** The custom event name. */
ev: string
- // If true, only 1 event with the same ID will be saved per user session
+ /** If set to `true`, only 1 event with the same ID will be saved per user session. */
unique?: boolean
}
+/**
+ * The object returned by `trackPageViews()`, used to stop tracking pages.
+ */
+export interface PageActions {
+ /** Stops the tracking of pages. */
+ stop: () => void
+}
+
export interface PageData {
- // Current URL path
+ /** Current URL path. */
path: string
- // Object with actions related to tracking page views which are abailable to end user
- actions: object
+ /** The object returned by `trackPageViews()`, used to stop tracking pages. */
+ actions: PageActions
}
export interface PageViewsOptions {
- // If true, only unique events will be saved
- // This param is useful when tracking single-page landing websites
+ /**
+ * If set to `true`, only unique events will be saved.
+ * This param is useful when tracking single-page landing websites.
+ */
unique?: boolean
- // A list of Regular Expressions or string pathes to ignore
- ignore?: Array<any>
+ /** A list of Regular Expressions or string pathes to ignore. */
+ ignore?: Array<string | RegExp>
- // Do not send Heartbeat requests to the server
+ /** Do not send Heartbeat requests to the server. */
noHeartbeat?: boolean
- // Send Heartbeat requests when the website tab is not active in the browser
+ /** Send Heartbeat requests when the website tab is not active in the browser. */
heartbeatOnBackground?: boolean
}
+export const defaultPageActions = {
+ stop() {},
+}
+
const DEFAULT_API_HOST = 'https://api.swetrix.com/log'
export class Lib {
@@ -74,9 +92,9 @@ export class Lib {
this.sendRequest('custom', data)
}
- trackPageViews(options?: PageViewsOptions): void | object {
+ trackPageViews(options?: PageViewsOptions): PageActions {
if (!this.canTrack()) {
- return
+ return defaultPageActions
}
if (this.pageData) {
@@ -128,6 +146,7 @@ export class Lib {
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
}
}
diff --git a/src/index.ts b/src/index.ts
index 7be38303b..13cddd933 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,9 +1,16 @@
-import { Lib, LibOptions, TrackEventOptions, PageViewsOptions } from './Lib'
+import {
+ Lib, LibOptions, TrackEventOptions, PageViewsOptions, PageActions, defaultPageActions,
+} from './Lib'
export let LIB_INSTANCE: Lib | null = null
-// Initialise the tracking library instance (other methods won't work if the library
-// is not initialised)
+/**
+ * Initialise the tracking library instance (other methods won't work if the library is not initialised).
+ *
+ * @param {string} pid The Project ID to link the instance of Swetrix.js to.
+ * @param {LibOptions} options Options related to the tracking.
+ * @returns {Lib} Instance of the Swetrix.js.
+ */
export function init (pid: string, options?: LibOptions): Lib {
if (!LIB_INSTANCE) {
LIB_INSTANCE = new Lib(pid, options)
@@ -12,15 +19,29 @@ export function init (pid: string, options?: LibOptions): Lib {
return LIB_INSTANCE
}
-// Tracks custom events
+/**
+ * With this function you are able to track any custom events you want.
+ * You should never send any identifiable data (like User ID, email, session cookie, etc.) as an event name.
+ * The total number of track calls and their conversion rate will be saved.
+ *
+ * @param {TrackEventOptions} event The options related to the custom event.
+ */
export function track (event: TrackEventOptions): void {
if (!LIB_INSTANCE) return
LIB_INSTANCE.track(event)
}
-export function trackViews (options?: PageViewsOptions): void {
- if (!LIB_INSTANCE) return
+/**
+ * With this function you are able to track any custom events you want.
+ * You should never send any identifiable data (like User ID, email, session cookie, etc.) as an event name.
+ * The total number of track calls and their conversion rate will be saved.
+ *
+ * @param {PageViewsOptions} options The options related to the custom event.
+ * @returns {PageActions} The actions related to the tracking. Used to stop tracking pages.
+ */
+export function trackViews (options?: PageViewsOptions): PageActions {
+ if (!LIB_INSTANCE) return defaultPageActions
- LIB_INSTANCE.trackPageViews(options)
-}
\ No newline at end of file
+ return LIB_INSTANCE.trackPageViews(options)
+}