📈 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!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
Automatic referrer detection from the query string
Blue Moused7938add4ee3
diff --git a/backend/apps/cloud/src/analytics/dto/events.dto.ts b/backend/apps/cloud/src/analytics/dto/events.dto.tsindex 21fd04dc8..9d17a5547 100644--- a/backend/apps/cloud/src/analytics/dto/events.dto.ts+++ b/backend/apps/cloud/src/analytics/dto/events.dto.ts@@ -171,6 +171,17 @@ export class EventsDto {})co?: string+ @ApiProperty({+ example: 'fbclid=AbCdEf123&utm_source=newsletter',+ description:+ 'Raw URL query string of the landing page (without leading ?). Used server-side to recover traffic source from ad/social click IDs when the browser stripped the referrer.',+ maxLength: 2048,+ })+ @IsOptional()+ @IsString()+ @MaxLength(2048)+ qs?: string+@ApiProperty({example: {affiliate: 'Yes',diff --git a/backend/apps/cloud/src/analytics/dto/pageviews.dto.ts b/backend/apps/cloud/src/analytics/dto/pageviews.dto.tsindex 854907131..c4031b947 100644--- a/backend/apps/cloud/src/analytics/dto/pageviews.dto.ts+++ b/backend/apps/cloud/src/analytics/dto/pageviews.dto.ts@@ -96,6 +96,17 @@ export class PageviewsDto {})co?: string+ @ApiProperty({+ example: 'fbclid=AbCdEf123&utm_source=newsletter',+ description:+ 'Raw URL query string of the landing page (without leading ?). Used server-side to recover traffic source from ad/social click IDs when the browser stripped the referrer.',+ maxLength: 2048,+ })+ @IsOptional()+ @IsString()+ @MaxLength(2048)+ qs?: string+@ApiProperty({example: false,description: 'If true, only unique events will be saved',diff --git a/backend/apps/cloud/src/analytics/utils/clickIdSources.ts b/backend/apps/cloud/src/analytics/utils/clickIdSources.tsindex 6b267e99c..6e1345400 100644--- a/backend/apps/cloud/src/analytics/utils/clickIdSources.ts+++ b/backend/apps/cloud/src/analytics/utils/clickIdSources.ts@@ -116,23 +116,35 @@ const CLICK_ID_MAP: Record<string, ClickIdMapping> = {const CLICK_ID_KEYS = Object.keys(CLICK_ID_MAP)/**- * Pulls the URL search string out of a `pg` value the tracker sent.- *- * The tracker only includes the search part when the user enables- * `search: true` in `trackPageViews`. When it is included the value- * looks like `/path?foo=bar&fbclid=abc` (or `/path#hash?foo=bar`).+ * Pulls the URL search string out of a `pg` value when the tracker+ * included it (i.e. when the user enabled `search: true` in+ * `trackPageViews`). Returns the part after `?`, with any trailing+ * `#hash` fragment stripped. This is a fallback for tracker versions+ * that don't yet send the dedicated `qs` field.*/-const extractSearchString = (pg: string | null | undefined): string => {+const extractSearchFromPg = (pg: string | null | undefined): string => {if (!pg) return ''const qIdx = pg.indexOf('?')if (qIdx === -1) return ''let search = pg.slice(qIdx + 1)- // Strip a trailing hash fragment if present (`?a=b#hash`)const hashIdx = search.indexOf('#')if (hashIdx !== -1) search = search.slice(0, hashIdx)return search}+/**+ * Normalises a query string the tracker sent in the `qs` field. We+ * accept it with or without a leading `?` and strip a trailing+ * `#hash` defensively.+ */+const normaliseQs = (qs: string | null | undefined): string => {+ if (!qs) return ''+ let result = qs.startsWith('?') ? qs.slice(1) : qs+ const hashIdx = result.indexOf('#')+ if (hashIdx !== -1) result = result.slice(0, hashIdx)+ return result+}+/*** Returns the first click-ID mapping found in the given query string,* iterating in `CLICK_ID_MAP` priority order so that paid-search IDs@@ -161,6 +173,13 @@ interface TrafficSourceFields {te?: string | nullco?: string | nullpg?: string | null+ /**+ * Raw URL query string (without leading `?`) the tracker captured+ * from the landing page. Preferred over `pg` because `pg` only+ * contains the search part when the site explicitly opts into+ * `search: true` in `trackPageViews`.+ */+ qs?: string | null}/**@@ -176,7 +195,7 @@ export const enrichTrafficSource = <T extends TrafficSourceFields>(): T => {if (!payload) return payload- const search = extractSearchString(payload.pg)+ const search = normaliseQs(payload.qs) || extractSearchFromPg(payload.pg)const mapping = findClickIdMapping(search)if (mapping) {if (!payload.so) payload.so = mapping.sourcediff --git a/backend/apps/community/src/analytics/dto/events.dto.ts b/backend/apps/community/src/analytics/dto/events.dto.tsindex 21fd04dc8..9d17a5547 100644--- a/backend/apps/community/src/analytics/dto/events.dto.ts+++ b/backend/apps/community/src/analytics/dto/events.dto.ts@@ -171,6 +171,17 @@ export class EventsDto {})co?: string+ @ApiProperty({+ example: 'fbclid=AbCdEf123&utm_source=newsletter',+ description:+ 'Raw URL query string of the landing page (without leading ?). Used server-side to recover traffic source from ad/social click IDs when the browser stripped the referrer.',+ maxLength: 2048,+ })+ @IsOptional()+ @IsString()+ @MaxLength(2048)+ qs?: string+@ApiProperty({example: {affiliate: 'Yes',diff --git a/backend/apps/community/src/analytics/dto/pageviews.dto.ts b/backend/apps/community/src/analytics/dto/pageviews.dto.tsindex 854907131..c4031b947 100644--- a/backend/apps/community/src/analytics/dto/pageviews.dto.ts+++ b/backend/apps/community/src/analytics/dto/pageviews.dto.ts@@ -96,6 +96,17 @@ export class PageviewsDto {})co?: string+ @ApiProperty({+ example: 'fbclid=AbCdEf123&utm_source=newsletter',+ description:+ 'Raw URL query string of the landing page (without leading ?). Used server-side to recover traffic source from ad/social click IDs when the browser stripped the referrer.',+ maxLength: 2048,+ })+ @IsOptional()+ @IsString()+ @MaxLength(2048)+ qs?: string+@ApiProperty({example: false,description: 'If true, only unique events will be saved',diff --git a/backend/apps/community/src/analytics/utils/clickIdSources.ts b/backend/apps/community/src/analytics/utils/clickIdSources.tsindex 6b267e99c..6e1345400 100644--- a/backend/apps/community/src/analytics/utils/clickIdSources.ts+++ b/backend/apps/community/src/analytics/utils/clickIdSources.ts@@ -116,23 +116,35 @@ const CLICK_ID_MAP: Record<string, ClickIdMapping> = {const CLICK_ID_KEYS = Object.keys(CLICK_ID_MAP)/**- * Pulls the URL search string out of a `pg` value the tracker sent.- *- * The tracker only includes the search part when the user enables- * `search: true` in `trackPageViews`. When it is included the value- * looks like `/path?foo=bar&fbclid=abc` (or `/path#hash?foo=bar`).+ * Pulls the URL search string out of a `pg` value when the tracker+ * included it (i.e. when the user enabled `search: true` in+ * `trackPageViews`). Returns the part after `?`, with any trailing+ * `#hash` fragment stripped. This is a fallback for tracker versions+ * that don't yet send the dedicated `qs` field.*/-const extractSearchString = (pg: string | null | undefined): string => {+const extractSearchFromPg = (pg: string | null | undefined): string => {if (!pg) return ''const qIdx = pg.indexOf('?')if (qIdx === -1) return ''let search = pg.slice(qIdx + 1)- // Strip a trailing hash fragment if present (`?a=b#hash`)const hashIdx = search.indexOf('#')if (hashIdx !== -1) search = search.slice(0, hashIdx)return search}+/**+ * Normalises a query string the tracker sent in the `qs` field. We+ * accept it with or without a leading `?` and strip a trailing+ * `#hash` defensively.+ */+const normaliseQs = (qs: string | null | undefined): string => {+ if (!qs) return ''+ let result = qs.startsWith('?') ? qs.slice(1) : qs+ const hashIdx = result.indexOf('#')+ if (hashIdx !== -1) result = result.slice(0, hashIdx)+ return result+}+/*** Returns the first click-ID mapping found in the given query string,* iterating in `CLICK_ID_MAP` priority order so that paid-search IDs@@ -161,6 +173,13 @@ interface TrafficSourceFields {te?: string | nullco?: string | nullpg?: string | null+ /**+ * Raw URL query string (without leading `?`) the tracker captured+ * from the landing page. Preferred over `pg` because `pg` only+ * contains the search part when the site explicitly opts into+ * `search: true` in `trackPageViews`.+ */+ qs?: string | null}/**@@ -176,7 +195,7 @@ export const enrichTrafficSource = <T extends TrafficSourceFields>(): T => {if (!payload) return payload- const search = extractSearchString(payload.pg)+ const search = normaliseQs(payload.qs) || extractSearchFromPg(payload.pg)const mapping = findClickIdMapping(search)if (mapping) {if (!payload.so) payload.so = mapping.sourcediff --git a/docs/content/docs/traffic-sources.mdx b/docs/content/docs/traffic-sources.mdxindex d501274f7..7a9efe5c6 100644--- a/docs/content/docs/traffic-sources.mdx+++ b/docs/content/docs/traffic-sources.mdx@@ -91,9 +91,11 @@ You don't need to do anything for these — they're handled in our backend:and override any click‑ID inference.<Callout type="info">- For Swetrix to see click IDs on internal pageviews of single-page apps, enable `search: true` in- `trackViews()`. Without it, only the initial landing pageview will include the URL search string.- See the [script reference](/swetrix-js-reference#trackviews).+ Click‑ID detection works automatically on every pageview, including internal navigation in+ single-page apps. The tracker captures the URL query string on each pageview and forwards it to+ our backend, where the click ID is matched against our map and discarded — only the inferred+ `source` / `medium` is stored. Make sure you're on a recent version of the `swetrix` script if+ you're not seeing this behaviour.</Callout>## What you can do as a site ownerdiff --git a/packages/tracker-js/package-lock.json b/packages/tracker-js/package-lock.jsonindex f02e0a76b..c3902b056 100644--- a/packages/tracker-js/package-lock.json+++ b/packages/tracker-js/package-lock.json@@ -1,12 +1,12 @@{"name": "swetrix",- "version": "3.7.2",+ "version": "4.2.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "swetrix",- "version": "3.7.2",+ "version": "4.2.0","license": "MIT","devDependencies": {"@rollup/plugin-commonjs": "^28.0.3",diff --git a/packages/tracker-js/package.json b/packages/tracker-js/package.jsonindex 12914435f..28a4234c9 100644--- a/packages/tracker-js/package.json+++ b/packages/tracker-js/package.json@@ -1,13 +1,39 @@{"name": "swetrix",- "version": "4.1.0",+ "version": "4.2.0","description": "The JavaScript analytics client for Swetrix Analytics",+ "keywords": [+ "analytics",+ "metrics",+ "monitoring",+ "privacy",+ "swetrix"+ ],+ "homepage": "https://docs.swetrix.com",+ "bugs": {+ "url": "https://github.com/Swetrix/swetrix-js/issues"+ },+ "license": "MIT",+ "author": "Andrii Romasiun, Swetrix Ltd. <[email protected]>",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/Swetrix/swetrix-js.git"+ },+ "funding": "https://github.com/sponsors/Swetrix","type": "module","main": "dist/swetrix.cjs.js","module": "dist/swetrix.es5.js","browser": "dist/swetrix.js",- "esnext": "dist/esnext/index.js","typings": "dist/esnext/index.d.ts",+ "esnext": "dist/esnext/index.js",+ "exports": {+ ".": {+ "import": "./dist/esnext/index.js",+ "require": "./dist/swetrix.cjs.js",+ "types": "./dist/esnext/index.d.ts",+ "default": "./dist/swetrix.js"+ }+ },"scripts": {"prebuild": "rimraf dist","prepublish": "npm run build",@@ -18,32 +44,6 @@"test:watch": "jest --watch","test:coverage": "jest --coverage"},- "exports": {- ".": {- "import": "./dist/esnext/index.js",- "require": "./dist/swetrix.cjs.js",- "types": "./dist/esnext/index.d.ts",- "default": "./dist/swetrix.js"- }- },- "keywords": [- "swetrix",- "analytics",- "monitoring",- "metrics",- "privacy"- ],- "repository": {- "type": "git",- "url": "git+https://github.com/Swetrix/swetrix-js.git"- },- "author": "Andrii Romasiun, Swetrix Ltd. <[email protected]>",- "funding": "https://github.com/sponsors/Swetrix",- "license": "MIT",- "bugs": {- "url": "https://github.com/Swetrix/swetrix-js/issues"- },- "homepage": "https://docs.swetrix.com","devDependencies": {"@rollup/plugin-commonjs": "^28.0.3","@rollup/plugin-node-resolve": "^16.0.1",@@ -55,8 +55,8 @@"jest-environment-jsdom": "^29.7.0","rimraf": "^6.0.1","rollup": "^4.41.0",- "tslib": "^2.6.3","ts-jest": "^29.3.4",+ "tslib": "^2.6.3","typescript": "^5.8.3"},"devEngines": {diff --git a/packages/tracker-js/src/Lib.ts b/packages/tracker-js/src/Lib.tsindex db6fd649b..7d78eb013 100644--- a/packages/tracker-js/src/Lib.ts+++ b/packages/tracker-js/src/Lib.ts@@ -5,6 +5,7 @@ import {getLocale,getTimezone,getReferrer,+ getQueryString,getUTMCampaign,getUTMMedium,getUTMSource,@@ -68,6 +69,13 @@ export interface IPageViewPayload {co?: stringpg?: string | null+ /**+ * Raw URL query string of the landing page (without the leading `?`).+ * Used server-side to recover the traffic source from ad/social click+ * IDs (gclid, fbclid, etc.) when the browser stripped the referrer.+ */+ qs?: string+/** Pageview-related metadata object with string values. */meta?: {[key: string]: string | number | boolean | null | undefined@@ -346,6 +354,7 @@ export class Lib {ca: getUTMCampaign(),te: getUTMTerm(),co: getUTMContent(),+ qs: getQueryString(),profileId: event.profileId ?? this.options?.profileId,}await this.sendRequest('custom', data)@@ -767,6 +776,7 @@ export class Lib {ca: getUTMCampaign(),te: getUTMTerm(),co: getUTMContent(),+ qs: getQueryString(),profileId: this.options?.profileId,...payload,}diff --git a/packages/tracker-js/src/utils.ts b/packages/tracker-js/src/utils.tsindex 4202daf16..2481da58a 100644--- a/packages/tracker-js/src/utils.ts+++ b/packages/tracker-js/src/utils.ts@@ -48,6 +48,28 @@ export const getReferrer = (): string | undefined => {return document.referrer || undefined}+/**+ * Returns the URL query string (without the leading `?`) of the current+ * page, or `undefined` if there is none.+ *+ * Falls back to a query string embedded in `location.hash` (e.g. when a+ * hash router uses `/#/path?foo=bar`) so we still capture click IDs in+ * SPA hash-routed setups.+ */+export const getQueryString = (): string | undefined => {+ if (location.search && location.search.length > 1) {+ return location.search.slice(1)+ }++ const hashIndex = location.hash.indexOf('?')+ if (hashIndex > -1) {+ const hashQuery = location.hash.slice(hashIndex + 1)+ if (hashQuery) return hashQuery+ }++ return undefined+}+export const getUTMSource = () => findInSearch(utmSourceRegex)export const getUTMMedium = () => findInSearch(utmMediumRegex) || getGclid()diff --git a/packages/tracker-js/tests/utils.test.ts b/packages/tracker-js/tests/utils.test.tsindex 2698aae0c..7eac87317 100644--- a/packages/tracker-js/tests/utils.test.ts+++ b/packages/tracker-js/tests/utils.test.ts@@ -116,6 +116,41 @@ describe('Utility Functions', () => {expect(utils.getReferrer()).toBeUndefined()})+ test('getQueryString should return the URL query string without the leading ?', () => {+ Object.defineProperty(window, 'location', {+ value: {+ pathname: '/landing',+ hash: '',+ search: '?fbclid=AbCdEf123&utm_source=newsletter',+ },+ writable: true,+ })+ expect(utils.getQueryString()).toBe(+ 'fbclid=AbCdEf123&utm_source=newsletter',+ )++ Object.defineProperty(window, 'location', {+ value: {+ pathname: '/landing',+ hash: '',+ search: '',+ },+ writable: true,+ })+ expect(utils.getQueryString()).toBeUndefined()++ // Hash-routed SPAs sometimes carry the query string after the `#`.+ Object.defineProperty(window, 'location', {+ value: {+ pathname: '/',+ hash: '#/landing?gclid=xyz',+ search: '',+ },+ writable: true,+ })+ expect(utils.getQueryString()).toBe('gclid=xyz')+ })+test('getPath should handle different URL formats', () => {// ArrangeObject.defineProperty(window, 'location', {diff --git a/packages/tracker-node/package-lock.json b/packages/tracker-node/package-lock.jsonindex 4f165a7af..d3feaac43 100644--- a/packages/tracker-node/package-lock.json+++ b/packages/tracker-node/package-lock.json@@ -1,12 +1,12 @@{"name": "@swetrix/node",- "version": "3.1.0",+ "version": "3.2.0","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "@swetrix/node",- "version": "3.1.0",+ "version": "3.2.0","license": "MIT","devDependencies": {"@rollup/plugin-commonjs": "^29.0.0",diff --git a/packages/tracker-node/package.json b/packages/tracker-node/package.jsonindex 578d61b52..c528669a3 100644--- a/packages/tracker-node/package.json+++ b/packages/tracker-node/package.json@@ -1,12 +1,30 @@{"name": "@swetrix/node",- "version": "3.1.0",+ "version": "3.2.0","description": "Swetrix NodeJS server-side tracking module",+ "keywords": [+ "analytics",+ "metrics",+ "monitoring",+ "privacy",+ "swetrix"+ ],+ "homepage": "https://docs.swetrix.com",+ "bugs": {+ "url": "https://github.com/Swetrix/swetrix-node/issues"+ },+ "license": "MIT",+ "author": "Andrii R. <[email protected]>",+ "repository": {+ "type": "git",+ "url": "git+https://github.com/Swetrix/swetrix-node.git"+ },+ "funding": "https://ko-fi.com/andriir","type": "module","main": "dist/swetrix.cjs","module": "dist/swetrix.es5.js",- "esnext": "dist/esnext/index.js","typings": "dist/esnext/index.d.ts",+ "esnext": "dist/esnext/index.js","exports": {".": {"types": "./dist/esnext/index.d.ts",@@ -21,34 +39,16 @@"start": "rollup -c -w","tsc": "tsc -p tsconfig.esnext.json"},- "keywords": [- "swetrix",- "analytics",- "monitoring",- "metrics",- "privacy"- ],- "repository": {- "type": "git",- "url": "git+https://github.com/Swetrix/swetrix-node.git"- },- "author": "Andrii R. <[email protected]>",- "funding": "https://ko-fi.com/andriir",- "license": "MIT",- "bugs": {- "url": "https://github.com/Swetrix/swetrix-node/issues"- },- "homepage": "https://docs.swetrix.com","devDependencies": {- "@types/node": "^25.0.3",- "node-fetch": "^3.3.2",- "tslib": "^2.8.1","@rollup/plugin-commonjs": "^29.0.0","@rollup/plugin-node-resolve": "^16.0.3","@rollup/plugin-typescript": "^12.3.0",+ "@types/node": "^25.0.3","@types/node-fetch": "^2.6.13",+ "node-fetch": "^3.3.2","rimraf": "^6.1.2","rollup": "^4.54.0",+ "tslib": "^2.8.1","typescript": "^5.9.3"}}diff --git a/packages/tracker-node/src/index.ts b/packages/tracker-node/src/index.tsindex 2a90a3c6c..5cd73fee4 100644--- a/packages/tracker-node/src/index.ts+++ b/packages/tracker-node/src/index.ts@@ -61,6 +61,14 @@ export interface TrackEventOptions {/** A campaign of the event (e.g. utm_campaign GET parameter) */ca?: string+ /**+ * Raw URL query string of the landing page (without the leading `?`).+ * Used server-side to recover the traffic source from ad/social click+ * IDs (gclid, fbclid, msclkid, ttclid, etc.) when the browser stripped+ * the referrer. UTM parameters always take precedence over click IDs.+ */+ qs?: string+/** Event-related metadata object with string values. */meta?: {[key: string]: string | number | boolean | null | undefined@@ -120,6 +128,14 @@ export interface TrackPageViewOptions {/** A campaign of the pageview (e.g. utm_campaign GET parameter) */ca?: string+ /**+ * Raw URL query string of the landing page (without the leading `?`).+ * Used server-side to recover the traffic source from ad/social click+ * IDs (gclid, fbclid, msclkid, ttclid, etc.) when the browser stripped+ * the referrer. UTM parameters always take precedence over click IDs.+ */+ qs?: string+/** If set to true, only unique visits will be saved */unique?: boolean