π 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
feat: Page title tracking
Blue Moused9814ca9f65a
diff --git a/backend/apps/cloud/src/analytics/analytics.controller.ts b/backend/apps/cloud/src/analytics/analytics.controller.tsindex 868c87b34..2008159ba 100644--- a/backend/apps/cloud/src/analytics/analytics.controller.ts+++ b/backend/apps/cloud/src/analytics/analytics.controller.ts@@ -2082,6 +2082,7 @@ export class AnalyticsController {pid: logDTO.pid,host: this.analyticsService.getHostFromOrigin(headers.origin),pg: logDTO.pg,+ title: logDTO.title,dv: deviceType,br: browserName,brv: browserVersion,diff --git a/backend/apps/cloud/src/analytics/dto/pageviews.dto.ts b/backend/apps/cloud/src/analytics/dto/pageviews.dto.tsindex e63d1afc4..9ba8c0836 100644--- a/backend/apps/cloud/src/analytics/dto/pageviews.dto.ts+++ b/backend/apps/cloud/src/analytics/dto/pageviews.dto.ts@@ -56,6 +56,18 @@ export class PageviewsDto {@IsString()pg?: string+ @ApiProperty({+ example: 'Pricing | Swetrix',+ required: false,+ nullable: true,+ description: 'Page title at the time of the pageview',+ maxLength: 2048,+ })+ @IsOptional()+ @IsString()+ @MaxLength(2048)+ title?: string | null+@ApiProperty({example: 'en-GB',description: "User's locale",diff --git a/backend/apps/cloud/src/analytics/utils/transformers.ts b/backend/apps/cloud/src/analytics/utils/transformers.tsindex e192424b0..bd1ef1e99 100644--- a/backend/apps/cloud/src/analytics/utils/transformers.ts+++ b/backend/apps/cloud/src/analytics/utils/transformers.ts@@ -55,6 +55,7 @@ interface CommonOptions {interface PageviewOptions extends CommonOptions {type: 'pageview'+ title?: string | null}interface CustomEventOptions extends CommonOptions {@@ -147,6 +148,7 @@ export const eventTransformer = (opts: EventTransformerOptions) => {return {type: 'pageview' as const,...buildCommon(opts),+ title: opts.title || null,created,}}diff --git a/backend/apps/cloud/src/analytics/v2/__tests__/page-titles.spec.ts b/backend/apps/cloud/src/analytics/v2/__tests__/page-titles.spec.tsnew file mode 100644index 000000000..00d593d3e--- /dev/null+++ b/backend/apps/cloud/src/analytics/v2/__tests__/page-titles.spec.ts@@ -0,0 +1,86 @@+import { plainToInstance } from 'class-transformer'+import { validate } from 'class-validator'++import { AnalyticsService, DataType } from '../../analytics.service'+import { PageviewsDto } from '../../dto/pageviews.dto'+import { eventTransformer } from '../../utils/transformers'+import { buildBreakdownQuery } from '../query/breakdown-query.builder'+import { parseV2Filters, toV1FiltersJson } from '../query/filters.translator'+import { getBreakdownDimension, parseMetricsParam } from '../registry'+import { V2_VIEW_FILTER_DIMENSIONS } from '../../../common/constants'++const pid = 'testproject1'++describe('Page titles', () => {+ it.each([undefined, null, '', 'Pricing β ζ₯ζ¬θͺ', 'a'.repeat(2048)])(+ 'accepts an optional title and preserves it for storage (case %#)',+ async (title) => {+ const dto = plainToInstance(PageviewsDto, { pid, pg: '/pricing', title })+ expect(await validate(dto, { whitelist: true })).toEqual([])+ expect(+ eventTransformer({+ type: 'pageview',+ pid: dto.pid,+ pg: dto.pg,+ title: dto.title,+ }),+ ).toMatchObject({+ pg: '/pricing',+ title: title || null,+ })+ },+ )++ it.each([42, {}, ['Pricing'], 'a'.repeat(2049)])(+ 'rejects invalid titles (case %#)',+ async (title) => {+ const errors = await validate(+ plainToInstance(PageviewsDto, { pid, title }),+ )+ expect(errors.some((error) => error.property === 'title')).toBe(true)+ },+ )++ it('groups traffic by title while excluding historical rows without titles', () => {+ const query = buildBreakdownQuery({+ dataType: 'traffic',+ dimension: getBreakdownDimension('title', 'traffic'),+ metrics: parseMetricsParam('visitors,pageviews', 'traffic'),+ subQuery:+ "FROM events WHERE pid = {pid:FixedString(12)} AND type = 'pageview'",+ ctx: { customEVFilterApplied: false },+ sort: { field: 'visitors', direction: 'desc' },+ })+ expect(query).toContain('title AS value')+ expect(query).toContain('AND title IS NOT NULL')+ expect(query).toContain('GROUP BY value')+ expect(query).toContain('count(DISTINCT psid) AS visitors')+ expect(query).toContain('count(*) AS pageviews')+ })++ it.each([+ ['is', 'title ='],+ ['is_not', 'NOT title ='],+ ['contains', 'title ILIKE'],+ ['contains_not', 'NOT title ILIKE'],+ ])('compiles the %s title filter with a bound value', (operator, sql) => {+ const value = "Pricing's <Plans> β ζ₯ζ¬θͺ"+ const filters = parseV2Filters(+ JSON.stringify([{ dimension: 'title', operator, value }]),+ )+ const service = Object.create(+ AnalyticsService.prototype,+ ) as AnalyticsService+ const [query, params] = service.getFiltersQuery(+ toV1FiltersJson(filters, 'traffic'),+ DataType.ANALYTICS,+ )+ expect(query).toContain(sql)+ expect(query).not.toContain(value)+ expect(Object.values(params)).toContain(value)+ })++ it('allows title filters in saved views', () => {+ expect(V2_VIEW_FILTER_DIMENSIONS).toContain('title')+ })+})diff --git a/backend/apps/cloud/src/analytics/v2/registry/dimensions.ts b/backend/apps/cloud/src/analytics/v2/registry/dimensions.tsindex 22858d453..75bd85cab 100644--- a/backend/apps/cloud/src/analytics/v2/registry/dimensions.ts+++ b/backend/apps/cloud/src/analytics/v2/registry/dimensions.ts@@ -40,6 +40,13 @@ export const V2_DIMENSIONS: V2DimensionDef[] = [types: GEO_TYPES,description: 'Page path',},+ {+ api: 'title',+ column: 'title',+ types: ['traffic'],+ excludeNull: true,+ description: 'Page title',+ },{api: 'host',column: 'host',diff --git a/backend/apps/cloud/src/common/constants.ts b/backend/apps/cloud/src/common/constants.tsindex 1849c8f3a..199d34ece 100644--- a/backend/apps/cloud/src/common/constants.ts+++ b/backend/apps/cloud/src/common/constants.ts@@ -88,6 +88,7 @@ const TRAFFIC_COLUMNS = ['ctp','host','pg',+ 'title','lc','br','brv',@@ -111,6 +112,7 @@ const V2_VIEW_FILTER_DIMENSIONS = ['region','city','page',+ 'title','host','locale','browser',diff --git a/backend/apps/cloud/src/demo-data/demo-data.service.ts b/backend/apps/cloud/src/demo-data/demo-data.service.tsindex 64b362708..03b353f57 100644--- a/backend/apps/cloud/src/demo-data/demo-data.service.ts+++ b/backend/apps/cloud/src/demo-data/demo-data.service.ts@@ -44,6 +44,25 @@ const BACKFILL_DAYS = 90const BASE_SESSIONS_PER_HOUR = 16const DEMO_HOST = 'swetrix.com'+const DEMO_PAGE_TITLES: Record<string, string> = {+ '/': 'Privacy-friendly web analytics | Swetrix',+ '/pricing': 'Pricing | Swetrix',+ '/docs': 'Documentation | Swetrix',+ '/open-source': 'Open-source analytics | Swetrix',+ '/alternatives/google-analytics': 'Google Analytics alternative | Swetrix',+ '/features/errors': 'Error tracking | Swetrix',+ '/features/session-replays': 'Session replays | Swetrix',+ '/blog/privacy-friendly-analytics':+ 'Privacy-friendly analytics | Swetrix Blog',+ '/blog/cookieless-tracking': 'Cookieless tracking | Swetrix Blog',+ '/blog/session-replay-privacy': 'Session replay privacy | Swetrix Blog',+ '/signup': 'Create an account | Swetrix',+ '/dashboard': 'Dashboard | Swetrix',+ '/checkout': 'Checkout | Swetrix',+ '/thank-you': 'Thank you | Swetrix',+ '/settings/billing': 'Billing settings | Swetrix',+}+type DemoRandom = () => numberinterface Weighted<T> {@@ -1822,6 +1841,7 @@ export class DemoDataService implements OnModuleInit {...eventTransformer({type: 'pageview',...this.commonEvent(session, page),+ title: DEMO_PAGE_TITLES[page],}),created: this.format(created),}diff --git a/backend/apps/community/src/analytics/analytics.controller.ts b/backend/apps/community/src/analytics/analytics.controller.tsindex 823c40a9f..4d3d63dd2 100644--- a/backend/apps/community/src/analytics/analytics.controller.ts+++ b/backend/apps/community/src/analytics/analytics.controller.ts@@ -1638,6 +1638,7 @@ export class AnalyticsController {pid: logDTO.pid,host: this.analyticsService.getHostFromOrigin(headers.origin),pg: logDTO.pg,+ title: logDTO.title,dv: deviceType,br: browserName,brv: browserVersion,diff --git a/backend/apps/community/src/analytics/dto/pageviews.dto.ts b/backend/apps/community/src/analytics/dto/pageviews.dto.tsindex e63d1afc4..9ba8c0836 100644--- a/backend/apps/community/src/analytics/dto/pageviews.dto.ts+++ b/backend/apps/community/src/analytics/dto/pageviews.dto.ts@@ -56,6 +56,18 @@ export class PageviewsDto {@IsString()pg?: string+ @ApiProperty({+ example: 'Pricing | Swetrix',+ required: false,+ nullable: true,+ description: 'Page title at the time of the pageview',+ maxLength: 2048,+ })+ @IsOptional()+ @IsString()+ @MaxLength(2048)+ title?: string | null+@ApiProperty({example: 'en-GB',description: "User's locale",diff --git a/backend/apps/community/src/analytics/utils/transformers.ts b/backend/apps/community/src/analytics/utils/transformers.tsindex e192424b0..bd1ef1e99 100644--- a/backend/apps/community/src/analytics/utils/transformers.ts+++ b/backend/apps/community/src/analytics/utils/transformers.ts@@ -55,6 +55,7 @@ interface CommonOptions {interface PageviewOptions extends CommonOptions {type: 'pageview'+ title?: string | null}interface CustomEventOptions extends CommonOptions {@@ -147,6 +148,7 @@ export const eventTransformer = (opts: EventTransformerOptions) => {return {type: 'pageview' as const,...buildCommon(opts),+ title: opts.title || null,created,}}diff --git a/backend/apps/community/src/analytics/v2/__tests__/page-titles.spec.ts b/backend/apps/community/src/analytics/v2/__tests__/page-titles.spec.tsnew file mode 100644index 000000000..00d593d3e--- /dev/null+++ b/backend/apps/community/src/analytics/v2/__tests__/page-titles.spec.ts@@ -0,0 +1,86 @@+import { plainToInstance } from 'class-transformer'+import { validate } from 'class-validator'++import { AnalyticsService, DataType } from '../../analytics.service'+import { PageviewsDto } from '../../dto/pageviews.dto'+import { eventTransformer } from '../../utils/transformers'+import { buildBreakdownQuery } from '../query/breakdown-query.builder'+import { parseV2Filters, toV1FiltersJson } from '../query/filters.translator'+import { getBreakdownDimension, parseMetricsParam } from '../registry'+import { V2_VIEW_FILTER_DIMENSIONS } from '../../../common/constants'++const pid = 'testproject1'++describe('Page titles', () => {+ it.each([undefined, null, '', 'Pricing β ζ₯ζ¬θͺ', 'a'.repeat(2048)])(+ 'accepts an optional title and preserves it for storage (case %#)',+ async (title) => {+ const dto = plainToInstance(PageviewsDto, { pid, pg: '/pricing', title })+ expect(await validate(dto, { whitelist: true })).toEqual([])+ expect(+ eventTransformer({+ type: 'pageview',+ pid: dto.pid,+ pg: dto.pg,+ title: dto.title,+ }),+ ).toMatchObject({+ pg: '/pricing',+ title: title || null,+ })+ },+ )++ it.each([42, {}, ['Pricing'], 'a'.repeat(2049)])(+ 'rejects invalid titles (case %#)',+ async (title) => {+ const errors = await validate(+ plainToInstance(PageviewsDto, { pid, title }),+ )+ expect(errors.some((error) => error.property === 'title')).toBe(true)+ },+ )++ it('groups traffic by title while excluding historical rows without titles', () => {+ const query = buildBreakdownQuery({+ dataType: 'traffic',+ dimension: getBreakdownDimension('title', 'traffic'),+ metrics: parseMetricsParam('visitors,pageviews', 'traffic'),+ subQuery:+ "FROM events WHERE pid = {pid:FixedString(12)} AND type = 'pageview'",+ ctx: { customEVFilterApplied: false },+ sort: { field: 'visitors', direction: 'desc' },+ })+ expect(query).toContain('title AS value')+ expect(query).toContain('AND title IS NOT NULL')+ expect(query).toContain('GROUP BY value')+ expect(query).toContain('count(DISTINCT psid) AS visitors')+ expect(query).toContain('count(*) AS pageviews')+ })++ it.each([+ ['is', 'title ='],+ ['is_not', 'NOT title ='],+ ['contains', 'title ILIKE'],+ ['contains_not', 'NOT title ILIKE'],+ ])('compiles the %s title filter with a bound value', (operator, sql) => {+ const value = "Pricing's <Plans> β ζ₯ζ¬θͺ"+ const filters = parseV2Filters(+ JSON.stringify([{ dimension: 'title', operator, value }]),+ )+ const service = Object.create(+ AnalyticsService.prototype,+ ) as AnalyticsService+ const [query, params] = service.getFiltersQuery(+ toV1FiltersJson(filters, 'traffic'),+ DataType.ANALYTICS,+ )+ expect(query).toContain(sql)+ expect(query).not.toContain(value)+ expect(Object.values(params)).toContain(value)+ })++ it('allows title filters in saved views', () => {+ expect(V2_VIEW_FILTER_DIMENSIONS).toContain('title')+ })+})diff --git a/backend/apps/community/src/analytics/v2/registry/dimensions.ts b/backend/apps/community/src/analytics/v2/registry/dimensions.tsindex 22858d453..75bd85cab 100644--- a/backend/apps/community/src/analytics/v2/registry/dimensions.ts+++ b/backend/apps/community/src/analytics/v2/registry/dimensions.ts@@ -40,6 +40,13 @@ export const V2_DIMENSIONS: V2DimensionDef[] = [types: GEO_TYPES,description: 'Page path',},+ {+ api: 'title',+ column: 'title',+ types: ['traffic'],+ excludeNull: true,+ description: 'Page title',+ },{api: 'host',column: 'host',diff --git a/backend/apps/community/src/common/constants.ts b/backend/apps/community/src/common/constants.tsindex 0214e5005..b2a677cb6 100644--- a/backend/apps/community/src/common/constants.ts+++ b/backend/apps/community/src/common/constants.ts@@ -97,6 +97,7 @@ const TRAFFIC_COLUMNS = ['ctp','host','pg',+ 'title','lc','br','brv',@@ -138,6 +139,7 @@ const V2_VIEW_FILTER_DIMENSIONS = ['region','city','page',+ 'title','host','locale','browser',diff --git a/backend/migrations/clickhouse/2026_09_26_page_titles.js b/backend/migrations/clickhouse/2026_09_26_page_titles.jsnew file mode 100644index 000000000..839962a52--- /dev/null+++ b/backend/migrations/clickhouse/2026_09_26_page_titles.js@@ -0,0 +1,5 @@+const { queriesRunner, dbName } = require('./setup')++queriesRunner([+ `ALTER TABLE ${dbName}.events ADD COLUMN IF NOT EXISTS title Nullable(String) CODEC(ZSTD(3)) AFTER pg`,+])diff --git a/backend/migrations/clickhouse/2026_09_26_page_titles.md b/backend/migrations/clickhouse/2026_09_26_page_titles.mdnew file mode 100644index 000000000..7a83a6dfc--- /dev/null+++ b/backend/migrations/clickhouse/2026_09_26_page_titles.md@@ -0,0 +1,10 @@+# Page titles++Apply the schema change before deploying the API and dashboard that use titles. From `backend`, with the target ClickHouse environment configured:++- Cloud: `node migrations/clickhouse/2026_09_26_page_titles.js`+- Community: `node migrations/clickhouse/selfhosted_2026_09_26_page_titles.js`++The shared database initialiser also creates and upgrades the `events.title` column, including Community startup via `npm run clickhouse:initialise`. Both standalone migrations are safe to rerun.++Deploy the updated browser tracker to start collecting titles. Existing pageviews remain untitled; no historical titles are inferred. Server-side callers can supply `title` through the Events API or `TrackPageViewOptions` in the Node tracker.diff --git a/backend/migrations/clickhouse/initialise_database.js b/backend/migrations/clickhouse/initialise_database.jsindex aabea4ccc..a13a0aa16 100644--- a/backend/migrations/clickhouse/initialise_database.js+++ b/backend/migrations/clickhouse/initialise_database.js@@ -4,7 +4,6 @@ const { queriesRunner, dbName, databaselessQueriesRunner } = require('./setup')const CLICKHOUSE_DB_INIT_QUERIES = [`CREATE DATABASE IF NOT EXISTS ${dbName}`]const CLICKHOUSE_INIT_QUERIES = [-`CREATE TABLE IF NOT EXISTS ${dbName}.events(type LowCardinality(String),@@ -14,6 +13,7 @@ const CLICKHOUSE_INIT_QUERIES = [profileId Nullable(String) CODEC(ZSTD(3)),host Nullable(String) CODEC(ZSTD(3)),pg Nullable(String) CODEC(ZSTD(3)),+ title Nullable(String) CODEC(ZSTD(3)),dv LowCardinality(Nullable(String)),br LowCardinality(Nullable(String)),brv Nullable(String) CODEC(ZSTD(3)),@@ -59,6 +59,8 @@ const CLICKHOUSE_INIT_QUERIES = [PARTITION BY toYYYYMM(created)ORDER BY (pid, type, created);`,+ `ALTER TABLE ${dbName}.events ADD COLUMN IF NOT EXISTS title Nullable(String) CODEC(ZSTD(3)) AFTER pg`,+// Error events status table`CREATE TABLE IF NOT EXISTS ${dbName}.error_statuses (eid FixedString(32),diff --git a/backend/migrations/clickhouse/selfhosted_2026_09_26_page_titles.js b/backend/migrations/clickhouse/selfhosted_2026_09_26_page_titles.jsnew file mode 100644index 000000000..839962a52--- /dev/null+++ b/backend/migrations/clickhouse/selfhosted_2026_09_26_page_titles.js@@ -0,0 +1,5 @@+const { queriesRunner, dbName } = require('./setup')++queriesRunner([+ `ALTER TABLE ${dbName}.events ADD COLUMN IF NOT EXISTS title Nullable(String) CODEC(ZSTD(3)) AFTER pg`,+])diff --git a/docs/content/docs/analytics-dashboard/traffic.mdx b/docs/content/docs/analytics-dashboard/traffic.mdxindex 25c5011cb..8ddaca2de 100644--- a/docs/content/docs/analytics-dashboard/traffic.mdx+++ b/docs/content/docs/analytics-dashboard/traffic.mdx@@ -60,6 +60,7 @@ Understand the technology your visitors are using:See which parts of your website are most popular:- **Page Paths**: The specific URLs visited.+- **Titles**: Page titles captured with pageviews. Click a title to filter traffic, or use the filter menu for exact, contains, and exclusion filters. Pages sharing a title are grouped together; combine title and page-path filters to narrow them down.- **Entry Pages**: The first page visitors land on.- **Exit Pages**: The last page visitors view before leaving.- **Host**: Useful for cross-domain tracking, showing which specific domain or subdomain the traffic originated from.@@ -68,6 +69,8 @@ See which parts of your website are most popular:Looking for the paths visitors take through your site? Check out the dedicated **[Journeys](/analytics-dashboard/journeys)** tab.:::+Titles are collected by the browser tracker and can be [overridden or disabled](/swetrix-js-reference#page-titles). The Titles breakdown excludes pageviews without titles, including older data. This feature is available in Cloud and Community editions.+### Traffic SourcesIdentify how visitors find your website:diff --git a/docs/content/docs/api/events.mdx b/docs/content/docs/api/events.mdxindex 481b3554c..17d9df7f1 100644--- a/docs/content/docs/api/events.mdx+++ b/docs/content/docs/api/events.mdx@@ -63,6 +63,7 @@ Must be set to `application/json` for all requests.| `pid` | `string` | `true` | A project ID to record the pageview event for || `tz` | `string` | `false` | Visitor's timezone (used as a backup in case IP geolocation fails). I.e. if it's set to `Europe/Kiev` and IP geolocation fails, we will set the country of this entry to `Ukraine`) || `pg` | `string` | `false` | A page to record the pageview event for (e.g. `/home`). All our scripts send the `pg` string with a slash (`/`) at the beginning, it's not a requirement but it's best to do the same so the data would be consistent when used together with our official scripts |+| `title` | `string` or `null` | `false` | Page title, up to 2,048 characters. Omit it or send `null` to leave the title unset. || `lc` | `string` | `false` | A locale of the user (e.g. `en-US` or `uk-UA`) || `ref` | `string` | `false` | A referrer URL (e.g. `https://example.com/`) || `so` | `string` | `false` | A source of the pageview (e.g. `ref`, `source` or `utm_source` GET parameter) |diff --git a/docs/content/docs/script-reference.mdx b/docs/content/docs/script-reference.mdxindex ef3bbcc30..feb2c47f2 100644--- a/docs/content/docs/script-reference.mdx+++ b/docs/content/docs/script-reference.mdx@@ -108,7 +108,7 @@ swetrix.trackViews({| Name | Description | Default value || --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- || unique | If true, only unique events will be saved. This param is useful when tracking single-page landing websites. | `false` |-| callback | A callback used to edit / prevent sending pageviews.<br />It accepts an object with pageview event data as a parameter which has the following structure: <br />lc: string \| undefined<br />tz: string \| undefined<br />ref: string \| undefined<br />so: string \| undefined<br />me: string \| undefined<br />ca: string \| undefined<br />te: string \| undefined<br />co: string \| undefined<br />qs: string \| undefined<br />meta: object \| undefined ("object" values must be string, number, boolean, null, or undefined)<br />pg: string \| null \| undefined<br />profileId: string \| undefined<br /><br />The callback is supposed to return the edited payload or `false` to prevent sending the pageview. If `true` is returned, the payload will be sent as-is. | `undefined` |+| callback | A callback used to edit / prevent sending pageviews.<br />It accepts an object with pageview event data as a parameter which has the following structure: <br />lc: string \| undefined<br />tz: string \| undefined<br />ref: string \| undefined<br />so: string \| undefined<br />me: string \| undefined<br />ca: string \| undefined<br />te: string \| undefined<br />co: string \| undefined<br />qs: string \| undefined<br />meta: object \| undefined ("object" values must be string, number, boolean, null, or undefined)<br />pg: string \| null \| undefined<br />title: string \| null \| undefined<br />profileId: string \| undefined<br /><br />The callback is supposed to return the edited payload or `false` to prevent sending the pageview. If `true` is returned, the payload will be sent as-is. | `undefined` || heartbeatOnBackground | Send Heartbeat requests when the website tab is not active in the browser.<br />Setting this to `true` means users who keep your website open in an inactive browser tab or window can still be counted in realtime statistics.<br />Setting this to true is usually useful for services like Spotify or Youtube. | `false` || hash | Set to `true` to enable hash-based routing for every hash, or provide an array of exact hash values to include. For example, `['pricing', 'features']` includes `/path#pricing` and `/path#features` while ignoring other hashes. A leading `#` is optional in array values. | `false` || search | Set to `true` to enable search-based routing for every query parameter, or provide an array of parameter names to include. For example, `['search', 'page']` includes those parameters while ignoring unrelated ones. You can enable both `hash` and `search`; a pageview is fired only when an included part of the URL changes. | `false` |@@ -122,6 +122,30 @@ The `trackViews` function returns a `Promise` with an object with some methods a}```+### Page titles++The tracker reads `document.title` for each pageview, including automatic SPA navigation and manual `pageview()` calls. Titles are captured when the pageview is sent; changing only the title does not send another pageview. For routers that update the title asynchronously, send a manual pageview after the title is ready instead of enabling automatic tracking.++The `trackViews` callback receives the title as `payload.title`. Return a replacement to override it, or `null` to skip title collection:++```typescript+swetrix.trackViews({+ callback: (payload) => ({ ...payload, title: 'Product documentation' }),+});+```++For manual tracking, pass `title` alongside `pg`:++```typescript+swetrix.pageview({+ payload: { pg: '/pricing', title: 'Pricing' },+});+```++The exported `IPageViewPayload` type includes `title?: string | null`. Omit it to use `document.title`; use `null` or an empty string to leave the title unset. The browser tracker limits titles to 2,048 characters. Choose a generic title or disable title collection on pages with personal information in their titles.++Titles are available in **Traffic β Pages β Titles** in both Cloud and Community editions. Older pageviews, noscript visits, and requests without a title remain untitled.+## Noscript fallbackThe `/log/noscript` image pixel records pageviews for visitors with JavaScript disabled.diff --git a/packages/tracker-js/README.md b/packages/tracker-js/README.mdindex 1cfe8f69f..6df4d1824 100644--- a/packages/tracker-js/README.md+++ b/packages/tracker-js/README.md@@ -151,6 +151,18 @@ trackError({})```+### Page titles++Pageviews include the current `document.title`, including SPA path changes. Read or override `payload.title` in the `trackViews` callback, or set `payload.title` when calling `pageview`. The exported `IPageViewPayload` type accepts `title?: string | null`.++```typescript+trackViews({+ callback: (payload) => ({ ...payload, title: 'Documentation' }),+})+```++Omitting `title` uses the document title. Set it to `null` or `''` to skip title collection. Titles are limited to 2,048 characters. Only a pageview captures a title; title changes alone do not send pageviews.+### `pageview(options)`Manually track a single page view (useful for custom routing).diff --git a/packages/tracker-js/src/Lib.ts b/packages/tracker-js/src/Lib.tsindex e5bcd6687..2cb44c59e 100644--- a/packages/tracker-js/src/Lib.ts+++ b/packages/tracker-js/src/Lib.ts@@ -119,6 +119,7 @@ export interface IPageViewPayload {te?: stringco?: stringpg?: string | null+ title?: string | null/*** Raw URL query string of the landing page (without the leading `?`).@@ -1266,6 +1267,7 @@ export class Lib {}const pvPayload = {+ title: isInBrowser() ? document.title : undefined,lc: getLocale(),tz: getTimezone(),ref: getReferrer(),@@ -1295,6 +1297,10 @@ export class Lib {this.activePage = pvPayload.pg || null}+ if (typeof pvPayload.title === 'string') {+ pvPayload.title = pvPayload.title.slice(0, 2048)+ }+Object.assign(pvPayload, privateData)this.sendRequest('', pvPayload)diff --git a/packages/tracker-js/tests/pageTitle.test.ts b/packages/tracker-js/tests/pageTitle.test.tsnew file mode 100644index 000000000..4eec098df--- /dev/null+++ b/packages/tracker-js/tests/pageTitle.test.ts@@ -0,0 +1,91 @@+import { Lib } from '../src/Lib'+import { setLocation } from './testUtils'++describe('Page titles', () => {+ let lib: Lib+ let sendRequest: jest.SpyInstance++ beforeEach(() => {+ jest.useFakeTimers()+ setLocation({ pathname: '/home' })+ document.title = 'Home | Example'+ lib = new Lib('test-project', { devMode: true })+ sendRequest = jest.spyOn(lib as any, 'sendRequest').mockResolvedValue(undefined)+ })++ afterEach(() => {+ jest.clearAllTimers()+ jest.useRealTimers()+ })++ it('captures the document title alongside the initial page path', () => {+ lib.trackPageViews()++ expect(sendRequest).toHaveBeenCalledWith(+ '',+ expect.objectContaining({+ pg: '/home',+ title: 'Home | Example',+ }),+ )+ })++ it('reads the new title on SPA navigation without firing for title-only changes', () => {+ lib.trackPageViews()+ document.title = 'Home (1)'+ jest.advanceTimersByTime(2000)+ expect(sendRequest.mock.calls.filter(([path]) => path === '')).toHaveLength(1)++ setLocation({ pathname: '/pricing' })+ document.title = 'Pricing | Example'+ jest.advanceTimersByTime(2000)++ expect(sendRequest).toHaveBeenCalledWith(+ '',+ expect.objectContaining({+ pg: '/pricing',+ title: 'Pricing | Example',+ }),+ )+ })++ it('lets the callback inspect and replace the title', () => {+ const callback = jest.fn((payload) => {+ expect(payload.title).toBe('Home | Example')+ return { ...payload, title: 'Public title' }+ })+ lib.trackPageViews({ callback })++ expect(callback).toHaveBeenCalledTimes(1)+ expect(sendRequest).toHaveBeenCalledWith('', expect.objectContaining({ title: 'Public title' }))+ })++ it.each([null, ''])('preserves a callback title opt-out of %p', (title) => {+ lib.trackPageViews({ callback: () => ({ title }) })+ expect(sendRequest).toHaveBeenCalledWith('', expect.objectContaining({ title }))+ })++ it('still lets callbacks cancel the pageview', () => {+ lib.trackPageViews({ callback: () => false })+ expect(sendRequest).not.toHaveBeenCalled()+ })++ it('defaults manual pageviews to the current title', () => {+ lib.submitPageView({ pg: '/manual' }, false, {})+ expect(sendRequest).toHaveBeenCalledWith('', expect.objectContaining({ pg: '/manual', title: 'Home | Example' }))+ })++ it.each(['Manual title', null, ''])('preserves a manual title of %p', (title) => {+ lib.submitPageView({ pg: '/manual', title }, false, {})+ expect(sendRequest).toHaveBeenCalledWith('', expect.objectContaining({ title }))+ })++ it('limits document and callback titles without dropping the pageview', () => {+ document.title = 'a'.repeat(3000)+ lib.submitPageView({ pg: '/manual' }, false, {})+ expect(sendRequest).toHaveBeenLastCalledWith('', expect.objectContaining({ title: 'a'.repeat(2048) }))++ lib.trackPageViews({ callback: () => ({ title: 'b'.repeat(3000) }) })+ expect(sendRequest).toHaveBeenLastCalledWith('', expect.objectContaining({ title: 'b'.repeat(2048) }))+ })+})diff --git a/packages/tracker-node/src/index.ts b/packages/tracker-node/src/index.tsindex 4cf01d2ad..e06753918 100644--- a/packages/tracker-node/src/index.ts+++ b/packages/tracker-node/src/index.ts@@ -112,6 +112,7 @@ export interface TrackPageViewOptions {/** A page to record the pageview event for (e.g. /home). All our scripts send the pg string with a slash (/) at the beginning, it's not a requirement but it's best to do the same so the data would be consistent when used together with our official scripts */pg?: string+ title?: string | null/** A locale of the user (e.g. en-US or uk-UA) */lc?: stringdiff --git a/web/app/lib/v2Dimensions.ts b/web/app/lib/v2Dimensions.tsindex 797759589..ca1995482 100644--- a/web/app/lib/v2Dimensions.ts+++ b/web/app/lib/v2Dimensions.ts@@ -43,6 +43,7 @@ const TRAFFIC_DIMENSIONS = ['region','city','page',+ 'title','host','locale','browser',diff --git a/web/app/pages/Project/View/Panels.tsx b/web/app/pages/Project/View/Panels.tsxindex 2a7c00cd7..7ac788e6b 100644--- a/web/app/pages/Project/View/Panels.tsx+++ b/web/app/pages/Project/View/Panels.tsx@@ -2093,6 +2093,10 @@ const DetailsTable = ({}}+ if (activeTabId === 'title') {+ return entry.name || ''+ }+try {return decodeURIComponent(entry.name || '')} catch {diff --git a/web/app/pages/Project/View/ViewProject.helpers.tsx b/web/app/pages/Project/View/ViewProject.helpers.tsxindex cba0d3b98..c61f4f84d 100644--- a/web/app/pages/Project/View/ViewProject.helpers.tsx+++ b/web/app/pages/Project/View/ViewProject.helpers.tsx@@ -2329,6 +2329,7 @@ const typeNameMapping = (t: typeof i18next.t) => ({region: t('project.mapping.rg'),city: t('project.mapping.ct'),page: t('project.mapping.pg'),+ title: t('project.mapping.title'),query: t('project.seo.query'),entry_page: t('project.entryPages'),exit_page: t('project.exitPages'),diff --git a/web/app/pages/Project/tabs/Traffic/TrafficView.tsx b/web/app/pages/Project/tabs/Traffic/TrafficView.tsxindex dcc66c7ce..213fafc6b 100644--- a/web/app/pages/Project/tabs/Traffic/TrafficView.tsx+++ b/web/app/pages/Project/tabs/Traffic/TrafficView.tsx@@ -731,6 +731,7 @@ const TrafficViewInner = ({const pagesSubTabs = useMemo<BreakdownSubTab[]>(() => [{ id: 'page', label: t('project.mapping.pg'), dimension: 'page' },+ { id: 'title', label: t('project.mapping.title'), dimension: 'title' },{id: 'entry_page',label: t('project.entryPages'),@@ -875,6 +876,10 @@ const TrafficViewInner = ({)}+ if (subTabId === 'title') {+ return entryName+ }+let decodedUri = entryNametry {@@ -969,6 +974,7 @@ const TrafficViewInner = ({'city','locale','page',+ 'title','entry_page','exit_page','host',diff --git a/web/app/ui/FilterValueInput.tsx b/web/app/ui/FilterValueInput.tsxindex 107121674..0c3bfb3d1 100644--- a/web/app/ui/FilterValueInput.tsx+++ b/web/app/ui/FilterValueInput.tsx@@ -61,6 +61,7 @@ export const filterCategoryIcons: Record<string, ReactNode> = {region: <MapTrifoldIcon className='size-4' />,city: <BuildingIcon className='size-4' />,page: <FileTextIcon className='size-4' />,+ title: <FileTextIcon className='size-4' />,entry_page: <SignInIcon className='size-4' />,exit_page: <SignOutIcon className='size-4' />,host: <HardDrivesIcon className='size-4' />,diff --git a/web/public/locales/en.json b/web/public/locales/en.jsonindex f9dea084c..91c43955d 100644--- a/web/public/locales/en.json+++ b/web/public/locales/en.json@@ -2079,6 +2079,7 @@"rg": "Region","ct": "City","pg": "Page",+ "title": "Titles","host": "Host","lc": "Locale","map": "Map",