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!

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.ts
index 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.ts
index 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.ts
index 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 | null
co?: string | null
pg?: 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.source
diff --git a/backend/apps/community/src/analytics/dto/events.dto.ts b/backend/apps/community/src/analytics/dto/events.dto.ts
index 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.ts
index 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.ts
index 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 | null
co?: string | null
pg?: 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.source
diff --git a/docs/content/docs/traffic-sources.mdx b/docs/content/docs/traffic-sources.mdx
index 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 owner
diff --git a/packages/tracker-js/package-lock.json b/packages/tracker-js/package-lock.json
index 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.json
index 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.ts
index 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?: string
pg?: 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.ts
index 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.ts
index 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', () => {
// Arrange
Object.defineProperty(window, 'location', {
diff --git a/packages/tracker-node/package-lock.json b/packages/tracker-node/package-lock.json
index 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.json
index 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.ts
index 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