Skip to content

fix(browser): capture SPA pageviews on query string and hash changes #4729

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
posthog wants to merge 2 commits into
base: main
Choose a base branch
from
+31 −10
Draft

fix(browser): capture SPA pageviews on query string and hash changes #4729

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9c0ce52
fix(browser): capture SPA pageviews on query string and hash changes
posthog[bot] Sep 1, 2026
d87fcd0
chore: use a patch changeset and regenerate public API references
posthog[bot] Sep 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .changeset/history-change-captures-search-and-hash.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
---
'posthog-js': minor
'@posthog/types': minor
---

`capture_pageview: 'history_change'` now captures a `$pageview` when a single-page-app navigation changes the query string or the hash, not only the path. Before this change, navigation to search results, filters, pagination, and tab state captured no pageview, so these apps undercounted pageviews. `disable_capture_url_hashes` still suppresses hash-only changes. To keep the old behaviour, set `capture_pageview: { path: true }`.

@posthog posthog Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

State when modern defaults disable hash capture

consider documentation

Why we think it's a valid issue
  • Checked: the default resolution in packages/browser/src/posthog-core.ts, the hash gate in packages/browser/src/extensions/history-autocapture.ts, the doc comment the PR edits in packages/types/src/posthog-config.ts, and the changeset text itself.
  • Found: packages/browser/src/posthog-core.ts:251 sets disable_capture_url_hashes: !!(defaults && defaults >= '2026-06-25'), and line 244 sets capture_pageview: 'history_change' for defaults >= '2025-05-24'. A project on '2026-06-25' defaults therefore gets 'history_change' and hash stripping at the same time.
  • Found: packages/browser/src/extensions/history-autocapture.ts:127-129 returns false from _shouldCaptureHashChanges in that state, so _hasLocationChanged (line 139) ignores hash-only navigation and monitorHistoryChanges (line 73) never adds the hashchange listener. The test at packages/browser/src/__tests__/extensions/history-autocapture.test.ts:214-222 confirms the silence.
  • Found: the changeset (line 6) and the doc comment (packages/types/src/posthog-config.ts:1371-1372) both name disable_capture_url_hashes, but neither says the SDK turns it on from '2026-06-25' defaults. So the premise of the finding is correct: the note promises hash pageviews to a cohort that will not receive them.
  • Impact: the omission is real but small. The note already names the exact option that suppresses hash capture, and a project on '2026-06-25' defaults opted into hash stripping through a change that its own release note called a breaking change for hash-routing apps. Such a project already collapses hash routes in $current_url, so no hash-only pageview is the consistent result, not a surprise. The added clause improves the note; its absence misleads few readers.
  • Priority: lowered to consider. No code behavior is wrong, the escape hatch is already named in the same paragraph, and the fix is one clause of release-note text.
Issue description

The release note names disable_capture_url_hashes, but it does not state when the SDK enables that option automatically. Users with defaults: '2026-06-25' or later still receive no hash-only pageviews.

Suggested fix

State that modern defaults enable disable_capture_url_hashes. Tell users to set disable_capture_url_hashes: false if they want hash-only navigation pageviews.

Prompt to fix with AI (copy-paste) 
## Context
@.changeset/history-change-captures-search-and-hash.md#L6

<issue_description>
The release note names `disable_capture_url_hashes`, but it does not state when the SDK enables that option automatically. Users with `defaults: '2026-06-25'` or later still receive no hash-only pageviews.
</issue_description>

<issue_validation>
- **Checked:** the default resolution in `packages/browser/src/posthog-core.ts`, the hash gate in `packages/browser/src/extensions/history-autocapture.ts`, the doc comment the PR edits in `packages/types/src/posthog-config.ts`, and the changeset text itself.
- **Found:** `packages/browser/src/posthog-core.ts:251` sets `disable_capture_url_hashes: !!(defaults && defaults >= '2026-06-25')`, and line 244 sets `capture_pageview: 'history_change'` for `defaults >= '2025-05-24'`. A project on `'2026-06-25'` defaults therefore gets `'history_change'` and hash stripping at the same time.
- **Found:** `packages/browser/src/extensions/history-autocapture.ts:127-129` returns false from `_shouldCaptureHashChanges` in that state, so `_hasLocationChanged` (line 139) ignores hash-only navigation and `monitorHistoryChanges` (line 73) never adds the hashchange listener. The test at `packages/browser/src/__tests__/extensions/history-autocapture.test.ts:214-222` confirms the silence.
- **Found:** the changeset (line 6) and the doc comment (`packages/types/src/posthog-config.ts:1371-1372`) both name `disable_capture_url_hashes`, but neither says the SDK turns it on from `'2026-06-25'` defaults. So the premise of the finding is correct: the note promises hash pageviews to a cohort that will not receive them.
- **Impact:** the omission is real but small. The note already names the exact option that suppresses hash capture, and a project on `'2026-06-25'` defaults opted into hash stripping through a change that its own release note called a breaking change for hash-routing apps. Such a project already collapses hash routes in `$current_url`, so no hash-only pageview is the consistent result, not a surprise. The added clause improves the note; its absence misleads few readers.
- **Priority:** lowered to `consider`. No code behavior is wrong, the escape hatch is already named in the same paragraph, and the fix is one clause of release-note text.
</issue_validation>

## Task
Investigate the issue and solve it

<potential_solution>
State that modern defaults enable `disable_capture_url_hashes`. Tell users to set `disable_capture_url_hashes: false` if they want hash-only navigation pageviews.
</potential_solution>

28 changes: 21 additions & 7 deletions packages/browser/src/__tests__/extensions/history-autocapture.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,13 +171,14 @@ describe('HistoryAutocapture', () => {
expect(capture).toHaveBeenCalledWith('$pageview', { navigation_type: 'pushState' })
})

it('should not capture when only the query string changes with history_change', () => {
it('should capture when only the query string changes with history_change', () => {
capture.mockClear()

mockLocation.search = '?param=value'
window.history.pushState({ page: 1 }, 'Test Page', '/initial?param=value')

expect(capture).not.toHaveBeenCalled()
expect(capture).toHaveBeenCalledTimes(1)
expect(capture).toHaveBeenCalledWith('$pageview', { navigation_type: 'pushState' })
})

it('should not capture pageview when capture_pageview is disabled', () => {
Expand All @@ -201,12 +202,23 @@ describe('HistoryAutocapture', () => {
expect(capture).toHaveBeenCalledWith('$pageview', { navigation_type: 'replaceState' })
})

it('should not capture when only the hash changes with history_change', () => {
it('should capture when only the hash changes with history_change', () => {
capture.mockClear()

mockLocation.hash = '#section'
window.history.replaceState({ page: 2 }, 'Test Page 2', '/initial#section')

expect(capture).toHaveBeenCalledTimes(1)
expect(capture).toHaveBeenCalledWith('$pageview', { navigation_type: 'replaceState' })
})

it('should not capture hash-only changes with history_change when disable_capture_url_hashes is set', () => {
posthog.config.disable_capture_url_hashes = true
restartWithCapturePageview('history_change')

mockLocation.hash = '#section'
window.history.replaceState({ page: 2 }, 'Test Page 2', '/initial#section')

expect(capture).not.toHaveBeenCalled()
})
})
Expand Down Expand Up @@ -309,13 +321,14 @@ describe('HistoryAutocapture', () => {
})

describe('hashchange events', () => {
it('should not capture direct hash changes with history_change', () => {
it('should capture direct hash changes with history_change', () => {
capture.mockClear()

mockLocation.hash = '#section'
window.dispatchEvent(new Event('hashchange'))

expect(capture).not.toHaveBeenCalled()
expect(capture).toHaveBeenCalledTimes(1)
expect(capture).toHaveBeenCalledWith('$pageview', { navigation_type: 'hashchange' })
})

it('should capture direct hash changes when hash is enabled', () => {
Expand Down Expand Up @@ -398,14 +411,15 @@ describe('HistoryAutocapture', () => {
expect(capture).toHaveBeenCalledWith('$pageview', { navigation_type: 'pushState' })
})

it('should not capture with history_change when only query and hash change together', () => {
it('should capture once with history_change when query and hash change together', () => {
capture.mockClear()

mockLocation.search = '?filter=new'
mockLocation.hash = '#results'
window.history.pushState({ page: 1 }, 'Filter Results', '/initial?filter=new#results')

expect(capture).not.toHaveBeenCalled()
expect(capture).toHaveBeenCalledTimes(1)
expect(capture).toHaveBeenCalledWith('$pageview', { navigation_type: 'pushState' })
})
})

Expand Down
2 changes: 1 addition & 1 deletion packages/browser/src/extensions/history-autocapture.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ export class HistoryAutocapture implements Extension {
const capturePageview = this._instance.config.capture_pageview

if (capturePageview === 'history_change') {
return { path: true }
return { path: true, search: true, hash: true }

@posthog posthog Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Startup query changes can send duplicate pageviews

consider bug

Why we think it's a valid issue
  • Checked: the init order in packages/browser/src/posthog-core.ts, every reference to _initialPageviewCaptured, the $pageview capture sites, and the capture path in packages/browser/src/extensions/history-autocapture.ts.
  • Found: the race window is real in the default configuration. posthog-core.ts:902 calls _initExtensions synchronously, so HistoryAutocapture snapshots _lastLocation (history-autocapture.ts:25) and patches pushState/replaceState (history-autocapture.ts:69-70, 98) before _loaded() runs at posthog-core.ts:1018. _loaded() then defers the initial pageview with setTimeout(..., 1) at posthog-core.ts:1293-1301. Any history call in the same task, or in a microtask, runs before that timer.
  • Found: the two capture paths share no state. _initialPageviewCaptured appears only at posthog-core.ts:463, 661, and 4670-4671, so the history capture at history-autocapture.ts:151-152 never sets it. The $pageview handling in capture() (posthog-core.ts:1902, 1911) adds properties but does not deduplicate. Two $pageview events therefore reach the queue with the same $current_url.
  • Found: the defect class already exists on main. Before this PR 'history_change' expanded to { path: true }, so a bootstrap redirect that changes the path (for example / to /login) already produced the same pair of events, and the granular { path, search, hash } config was already public. Line 121 widens the trigger to query-only and hash-only startup changes; it does not create the coordination gap.
  • Impact: confirmed duplicate pageviews, but only for a narrow window. The URL mutation must happen inside the init task or a microtask, before the 1 ms timer. The OAuth cleanup named in the finding usually runs after an await, so it lands after the initial pageview and then reports a genuinely different URL, which is the intended new behavior and not a duplicate. Hash-routing apps on defaults of '2026-06-25' or later are also unaffected, because disable_capture_url_hashes suppresses the hash capture (posthog-core.ts:251, history-autocapture.ts:127-129).
  • Priority: lowered to consider. The mechanism is verified, but the trigger is a sub-millisecond startup window, the same double capture already occurs on main for the far more common path redirect, and the suggested fix redesigns initial-pageview coordination well beyond this one-line change.
Issue description

Line 121 enables search and hash captures as soon as HistoryAutocapture initializes. PostHog initializes this extension before config.loaded, but _loaded() defers the initial pageview with a timer. If startup code changes only the query or hash, the history hook sends a pageview for the final URL. The timer then sends another pageview for that same URL because the history capture does not set _initialPageviewCaptured. This creates duplicate pageviews during common router or OAuth URL normalization.

Suggested fix

Coordinate history capture with the initial pageview state. Before the initial pageview fires, make a history capture satisfy it or suppress the history capture. Add an integration test that changes the query and hash during loaded, advances the timer, and expects exactly one pageview.

Prompt to fix with AI (copy-paste) 
## Context
@packages/browser/src/extensions/history-autocapture.ts#L121

<issue_description>
Line 121 enables search and hash captures as soon as `HistoryAutocapture` initializes. PostHog initializes this extension before `config.loaded`, but `_loaded()` defers the initial pageview with a timer. If startup code changes only the query or hash, the history hook sends a pageview for the final URL. The timer then sends another pageview for that same URL because the history capture does not set `_initialPageviewCaptured`. This creates duplicate pageviews during common router or OAuth URL normalization.
</issue_description>

<issue_validation>
- **Checked:** the init order in `packages/browser/src/posthog-core.ts`, every reference to `_initialPageviewCaptured`, the `$pageview` capture sites, and the capture path in `packages/browser/src/extensions/history-autocapture.ts`.
- **Found:** the race window is real in the default configuration. `posthog-core.ts:902` calls `_initExtensions` synchronously, so `HistoryAutocapture` snapshots `_lastLocation` (`history-autocapture.ts:25`) and patches `pushState`/`replaceState` (`history-autocapture.ts:69-70, 98`) before `_loaded()` runs at `posthog-core.ts:1018`. `_loaded()` then defers the initial pageview with `setTimeout(..., 1)` at `posthog-core.ts:1293-1301`. Any history call in the same task, or in a microtask, runs before that timer.
- **Found:** the two capture paths share no state. `_initialPageviewCaptured` appears only at `posthog-core.ts:463`, `661`, and `4670-4671`, so the history capture at `history-autocapture.ts:151-152` never sets it. The `$pageview` handling in `capture()` (`posthog-core.ts:1902`, `1911`) adds properties but does not deduplicate. Two `$pageview` events therefore reach the queue with the same `$current_url`.
- **Found:** the defect class already exists on `main`. Before this PR `'history_change'` expanded to `{ path: true }`, so a bootstrap redirect that changes the path (for example `/` to `/login`) already produced the same pair of events, and the granular `{ path, search, hash }` config was already public. Line 121 widens the trigger to query-only and hash-only startup changes; it does not create the coordination gap.
- **Impact:** confirmed duplicate pageviews, but only for a narrow window. The URL mutation must happen inside the init task or a microtask, before the 1 ms timer. The OAuth cleanup named in the finding usually runs after an `await`, so it lands after the initial pageview and then reports a genuinely different URL, which is the intended new behavior and not a duplicate. Hash-routing apps on `defaults` of `'2026-06-25'` or later are also unaffected, because `disable_capture_url_hashes` suppresses the hash capture (`posthog-core.ts:251`, `history-autocapture.ts:127-129`).
- **Priority:** lowered to `consider`. The mechanism is verified, but the trigger is a sub-millisecond startup window, the same double capture already occurs on `main` for the far more common path redirect, and the suggested fix redesigns initial-pageview coordination well beyond this one-line change.
</issue_validation>

## Task
Investigate the issue and solve it

<potential_solution>
Coordinate history capture with the initial pageview state. Before the initial pageview fires, make a history capture satisfy it or suppress the history capture. Add an integration test that changes the query and hash during `loaded`, advances the timer, and expects exactly one pageview.
</potential_solution>

@posthog posthog Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Preserve the pinned history_change contract

must_fix compatibility

Why we think it's a valid issue
  • Checked: the defaults contract in packages/types/src/posthog-config.ts, the date-gated default map in packages/browser/src/posthog-core.ts, the runtime expansion in history-autocapture.ts, the shipped CHANGELOG history, and the versioned reference snapshots in packages/browser/references/.
  • Found: a pinned defaults date cannot freeze this behavior. posthog-core.ts:244 pins only the value 'history_change'; history-autocapture.ts:117-125 expands that string at runtime with no reference to defaults. Every project pinned from '2025-05-24' through '2026-08-30' therefore changes behavior on a minor upgrade with no config edit. posthog-config.ts:1737-1739 documents defaults as "Configuration defaults for breaking changes. When set to a specific date, enables new default behaviors that were introduced on that date" — the mechanism this change routes around.
  • Found: the team made the opposite decision nine days ago and told customers so. packages/browser/CHANGELOG.md:287 (release 1.418.13, PR feat(browser): add granular SPA pageview options #4418, dated 2026-08-24) shipped the granular { path, search, hash } object and states "The existing 'history_change' option continues to capture pathname changes." The object form was published as the opt-in for search and hash. This PR reverses that promise in the next minor.
  • Found: direct precedent for gating. posthog-core.ts:251 gates disable_capture_url_hashes at '2026-06-25', and packages/core/CHANGELOG.md:508 calls that URL-capture change "a breaking behavior change" that is "disabled by default for backwards compatibility." Eight dated revisions exist, so adding one is the idiomatic and cheap path the suggestion proposes.
  • Found: one point cuts the other way, and the author should weigh it. Before 1.418.13 the reference described 'history_change' as "Capture pageviews on the initial page load and on history API changes (pushState, replaceState, popstate)", which supports reading path-only capture as an under-implementation rather than a promise. The explicit pathname wording is recent; the path-only behavior is about a year old.
  • Impact: confirmed contract break for existing installs. Extra $pageview events land in every SPA on 'history_change' after a minor bump, which shifts pageview counts, funnel and conversion baselines, and billable event volume without any customer action. The changeset marks posthog-js as minor, and the PR leaves the backwards-compatibility checklist item unticked.
Issue description

This mapping changes the documented meaning of the public history_change option. It also changes every pinned defaults snapshot from 2025-05-24 onward. Existing apps will send new query-only and hash-only $pageview events after a minor upgrade. This can change analytics, billing volume, and captured URL data without a configuration change.

Suggested fix

Keep history_change mapped to { path: true }. Add a new dated defaults revision that uses { path: true, search: true, hash: true }. Customers can also opt in with the existing object form. Update the type comment and changeset to explain the gated behavior.

Prompt to fix with AI (copy-paste) 
## Context
@packages/browser/src/extensions/history-autocapture.ts#L121

<issue_description>
This mapping changes the documented meaning of the public `history_change` option. It also changes every pinned defaults snapshot from `2025-05-24` onward. Existing apps will send new query-only and hash-only `$pageview` events after a minor upgrade. This can change analytics, billing volume, and captured URL data without a configuration change.
</issue_description>

<issue_validation>
- **Checked:** the `defaults` contract in `packages/types/src/posthog-config.ts`, the date-gated default map in `packages/browser/src/posthog-core.ts`, the runtime expansion in `history-autocapture.ts`, the shipped `CHANGELOG` history, and the versioned reference snapshots in `packages/browser/references/`.
- **Found:** a pinned `defaults` date cannot freeze this behavior. `posthog-core.ts:244` pins only the *value* `'history_change'`; `history-autocapture.ts:117-125` expands that string at runtime with no reference to `defaults`. Every project pinned from `'2025-05-24'` through `'2026-08-30'` therefore changes behavior on a minor upgrade with no config edit. `posthog-config.ts:1737-1739` documents `defaults` as "Configuration defaults for **breaking changes**. When set to a specific date, enables new default behaviors that were introduced on that date" — the mechanism this change routes around.
- **Found:** the team made the opposite decision nine days ago and told customers so. `packages/browser/CHANGELOG.md:287` (release 1.418.13, PR #4418, dated 2026-08-24) shipped the granular `{ path, search, hash }` object and states "The existing `'history_change'` option continues to capture pathname changes." The object form was published as the opt-in for search and hash. This PR reverses that promise in the next minor.
- **Found:** direct precedent for gating. `posthog-core.ts:251` gates `disable_capture_url_hashes` at `'2026-06-25'`, and `packages/core/CHANGELOG.md:508` calls that URL-capture change "a breaking behavior change" that is "disabled by default for backwards compatibility." Eight dated revisions exist, so adding one is the idiomatic and cheap path the suggestion proposes.
- **Found:** one point cuts the other way, and the author should weigh it. Before 1.418.13 the reference described `'history_change'` as "Capture pageviews on the initial page load and on history API changes (pushState, replaceState, popstate)", which supports reading path-only capture as an under-implementation rather than a promise. The explicit pathname wording is recent; the path-only behavior is about a year old.
- **Impact:** confirmed contract break for existing installs. Extra `$pageview` events land in every SPA on `'history_change'` after a minor bump, which shifts pageview counts, funnel and conversion baselines, and billable event volume without any customer action. The changeset marks `posthog-js` as `minor`, and the PR leaves the backwards-compatibility checklist item unticked.
</issue_validation>

## Task
Investigate the issue and solve it

<potential_solution>
Keep `history_change` mapped to `{ path: true }`. Add a new dated defaults revision that uses `{ path: true, search: true, hash: true }`. Customers can also opt in with the existing object form. Update the type comment and changeset to explain the gated behavior.
</potential_solution>

@posthog posthog Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do not count PostHog's URL cleanup as a pageview

should_fix bug

Why we think it's a valid issue
  • Checked: Whether any SDK-owned code calls the patched replaceState with a URL that differs only in the query string. Searched packages/browser/src and packages/browser-common/src for replaceState outside tests.
  • Found: clearRestoreTokenFromUrl at packages/browser/src/extensions/conversations/external/url-utils.ts:63-78 deletes ph_conv_restore from the URL and calls the global window.history.replaceState(window.history.state, '', newUrl). It uses the global method, so the patch installed by _patchHistoryMethod (packages/browser/src/extensions/history-autocapture.ts:78-101) intercepts it. The path and the hash do not change; only location.search changes.
  • Found: The changed line makes options.search true for history_change, so the search clause in _hasLocationChanged (packages/browser/src/extensions/history-autocapture.ts:130-140) now fires. _capturePageview then sends $pageview with navigation_type: 'replaceState' (packages/browser/src/extensions/history-autocapture.ts:151). Before this change history_change compared pathname alone, so the same cleanup was silent. The regression is introduced by this line.
  • Checked: The order of installation, to confirm the patch is live when the cleanup runs. Read the extension registration in packages/browser/src/posthog-core.ts:1102-1103 and :1131-1132, and the conversations load path.
  • Found: historyAutocapture is registered before conversations, and the conversations manager loads lazily on remote config through loadExternalDependency (packages/browser/src/extensions/conversations/posthog-conversations.ts:51 and :155). The patch is therefore always in place first. _lastLocation is set in the constructor while the token is still in the URL, so the cleanup produces a genuine search difference.
  • Checked: The downstream effect of an extra $pageview.
  • Found: doPageView at packages/browser/src/page-view.ts:77-84 resets the scroll context and closes the previous pageview segment. The synthetic pageview therefore ends the real pageview's duration and scroll measurement almost immediately, and emits $prev_pageview_max_scroll and related properties for a segment of near-zero length.
  • Found: The repeat-cleanup concern is supported by the code's own comment at packages/browser/src/extensions/conversations/external/index.tsx:480-484: cleanup runs three times, because "SPA routers (Next.js, React Router, etc.) maintain their own URL state and can overwrite a single replaceState call." Each overwrite and re-clean pair changes search again, so a router that restores the parameter multiplies the synthetic pageviews.
  • Impact: A user who opens a conversations restore link on any install with capture_pageview: 'history_change' gets at least one $pageview that represents no navigation, plus corrupted scroll and duration attribution on the real pageview. The trigger is a designed product path, not a rare edge case. The same class of problem also reaches the toolbar hash cleanup at packages/browser/src/extensions/toolbar.ts:109, which now changes a captured URL component when disable_capture_url_hashes is false. This is a correctness defect that works against the accuracy goal of the change itself.
Issue description

This enables search capture for every wrapped replaceState call. Conversations uses replaceState to remove its ph_conv_restore parameter after remote configuration loads. That cleanup now sends a $pageview, although the user did not navigate. It also resets pageview duration and scroll state. Routers can restore the parameter between cleanup attempts, which can create more synthetic pageviews.

Suggested fix

Add an internal way to call replaceState without history autocapture. Use it for SDK-owned URL cleanup. Add an integration test with ?ph_conv_restore=.... Assert that cleanup sends no pageview after the initial pageview.

Prompt to fix with AI (copy-paste) 
## Context
@packages/browser/src/extensions/history-autocapture.ts#L121

<issue_description>
This enables search capture for every wrapped `replaceState` call. Conversations uses `replaceState` to remove its `ph_conv_restore` parameter after remote configuration loads. That cleanup now sends a `$pageview`, although the user did not navigate. It also resets pageview duration and scroll state. Routers can restore the parameter between cleanup attempts, which can create more synthetic pageviews.
</issue_description>

<issue_validation>
- **Checked:** Whether any SDK-owned code calls the patched `replaceState` with a URL that differs only in the query string. Searched `packages/browser/src` and `packages/browser-common/src` for `replaceState` outside tests.
- **Found:** `clearRestoreTokenFromUrl` at `packages/browser/src/extensions/conversations/external/url-utils.ts:63-78` deletes `ph_conv_restore` from the URL and calls the global `window.history.replaceState(window.history.state, '', newUrl)`. It uses the global method, so the patch installed by `_patchHistoryMethod` (`packages/browser/src/extensions/history-autocapture.ts:78-101`) intercepts it. The path and the hash do not change; only `location.search` changes.
- **Found:** The changed line makes `options.search` true for `history_change`, so the search clause in `_hasLocationChanged` (`packages/browser/src/extensions/history-autocapture.ts:130-140`) now fires. `_capturePageview` then sends `$pageview` with `navigation_type: 'replaceState'` (`packages/browser/src/extensions/history-autocapture.ts:151`). Before this change `history_change` compared `pathname` alone, so the same cleanup was silent. The regression is introduced by this line.
- **Checked:** The order of installation, to confirm the patch is live when the cleanup runs. Read the extension registration in `packages/browser/src/posthog-core.ts:1102-1103` and `:1131-1132`, and the conversations load path.
- **Found:** `historyAutocapture` is registered before `conversations`, and the conversations manager loads lazily on remote config through `loadExternalDependency` (`packages/browser/src/extensions/conversations/posthog-conversations.ts:51` and `:155`). The patch is therefore always in place first. `_lastLocation` is set in the constructor while the token is still in the URL, so the cleanup produces a genuine search difference.
- **Checked:** The downstream effect of an extra `$pageview`.
- **Found:** `doPageView` at `packages/browser/src/page-view.ts:77-84` resets the scroll context and closes the previous pageview segment. The synthetic pageview therefore ends the real pageview's duration and scroll measurement almost immediately, and emits `$prev_pageview_max_scroll` and related properties for a segment of near-zero length.
- **Found:** The repeat-cleanup concern is supported by the code's own comment at `packages/browser/src/extensions/conversations/external/index.tsx:480-484`: cleanup runs three times, because "SPA routers (Next.js, React Router, etc.) maintain their own URL state and can overwrite a single replaceState call." Each overwrite and re-clean pair changes `search` again, so a router that restores the parameter multiplies the synthetic pageviews.
- **Impact:** A user who opens a conversations restore link on any install with `capture_pageview: 'history_change'` gets at least one `$pageview` that represents no navigation, plus corrupted scroll and duration attribution on the real pageview. The trigger is a designed product path, not a rare edge case. The same class of problem also reaches the toolbar hash cleanup at `packages/browser/src/extensions/toolbar.ts:109`, which now changes a captured URL component when `disable_capture_url_hashes` is false. This is a correctness defect that works against the accuracy goal of the change itself.
</issue_validation>

## Task
Investigate the issue and solve it

<potential_solution>
Add an internal way to call `replaceState` without history autocapture. Use it for SDK-owned URL cleanup. Add an integration test with `?ph_conv_restore=...`. Assert that cleanup sends no pageview after the initial pageview.
</potential_solution>

}

return isObject(capturePageview) ? capturePageview : {}
Expand Down
3 changes: 2 additions & 1 deletion packages/types/src/posthog-config.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1368,7 +1368,8 @@ export interface PostHogConfig {
* Can be:
* - `true`: Capture the initial pageview
* - `false`: Don't capture any pageviews
* - `'history_change'`: Capture the initial pageview and pageviews when the pathname changes
* - `'history_change'`: Capture the initial pageview and pageviews when the path, query string, or hash changes.
* `disable_capture_url_hashes` still suppresses hash-only changes.
Comment on lines +1371 to +1372

@posthog posthog Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Regenerate the public API reference

must_fix documentation

Why we think it's a valid issue
  • Checked: the committed reference JSON, the source of the doc text, the generate-references job in .github/workflows/library-ci.yml, the scripts/check-public-api.js gate it calls, and .github/workflows/generated-files-notice.yml.
  • Found: the committed artifact is stale. packages/browser/references/posthog-js-references-latest.json still carries the pre-PR sentence "Capture the initial pageview and pageviews when the pathname changes", next to the unchanged bullet "An object: Capture the initial pageview and pageviews when any selected URL component changes" — the same doc block the PR edits at packages/types/src/posthog-config.ts:1369-1373. A grep across packages/**/*.ts finds the old wording in no source file, so regeneration will rewrite that string.
  • Found: the check runs on this PR and fails deterministically. .github/workflows/library-ci.yml:3-4 triggers on every pull_request, and the generate-references job at line 474 runs pnpm generate-references then pnpm check:public-api with no needs or if gate. scripts/check-public-api.js:10-56 runs git status --porcelain over packages/browser/references/posthog-js-references-latest.json and calls process.exit(1) on any diff, with the message "Run pnpm generate-references and commit the updated latest reference files." The suggested action matches the repo's own instruction.
  • Found: the working tree shows the file clean, so the stale copy is what the PR carries. The PR touches 4 files and none is a reference file.
  • Found: .github/workflows/generated-files-notice.yml does not contradict this. It only prints a non-blocking warning when a human PR edits generated paths, and it states that it "does not fail the workflow and does not block merge".
  • Impact: confirmed red CI job on this PR, plus a published API reference that states the superseded 'history_change' contract for consumers who read the reference rather than the source.
  • Priority: raised to must_fix. The failure is deterministic and the author must land the regenerated file before this PR can merge, which is a harder blocker than should_fix implies.
Issue description

The checked-in browser API reference still says that history_change watches only the pathname. CI regenerates this reference and fails when it finds the difference. The published reference also retains the old contract.

Suggested fix

Run pnpm generate-references. Commit the updated packages/browser/references/posthog-js-references-latest.json.

Prompt to fix with AI (copy-paste) 
## Context
@packages/types/src/posthog-config.ts#L1371-1372

<issue_description>
The checked-in browser API reference still says that `history_change` watches only the pathname. CI regenerates this reference and fails when it finds the difference. The published reference also retains the old contract.
</issue_description>

<issue_validation>
- **Checked:** the committed reference JSON, the source of the doc text, the `generate-references` job in `.github/workflows/library-ci.yml`, the `scripts/check-public-api.js` gate it calls, and `.github/workflows/generated-files-notice.yml`.
- **Found:** the committed artifact is stale. `packages/browser/references/posthog-js-references-latest.json` still carries the pre-PR sentence "Capture the initial pageview and pageviews when the pathname changes", next to the unchanged bullet "An object: Capture the initial pageview and pageviews when any selected URL component changes" — the same doc block the PR edits at `packages/types/src/posthog-config.ts:1369-1373`. A grep across `packages/**/*.ts` finds the old wording in no source file, so regeneration will rewrite that string.
- **Found:** the check runs on this PR and fails deterministically. `.github/workflows/library-ci.yml:3-4` triggers on every `pull_request`, and the `generate-references` job at line 474 runs `pnpm generate-references` then `pnpm check:public-api` with no `needs` or `if` gate. `scripts/check-public-api.js:10-56` runs `git status --porcelain` over `packages/browser/references/posthog-js-references-latest.json` and calls `process.exit(1)` on any diff, with the message "Run `pnpm generate-references` and commit the updated latest reference files." The suggested action matches the repo's own instruction.
- **Found:** the working tree shows the file clean, so the stale copy is what the PR carries. The PR touches 4 files and none is a reference file.
- **Found:** `.github/workflows/generated-files-notice.yml` does not contradict this. It only prints a non-blocking warning when a human PR edits generated paths, and it states that it "does not fail the workflow and does not block merge".
- **Impact:** confirmed red CI job on this PR, plus a published API reference that states the superseded `'history_change'` contract for consumers who read the reference rather than the source.
- **Priority:** raised to `must_fix`. The failure is deterministic and the author must land the regenerated file before this PR can merge, which is a harder blocker than `should_fix` implies.
</issue_validation>

## Task
Investigate the issue and solve it

<potential_solution>
Run `pnpm generate-references`. Commit the updated `packages/browser/references/posthog-js-references-latest.json`.
</potential_solution>

Comment on lines +1371 to +1372

@posthog posthog Bot Sep 1, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Update the JavaScript SDK config guide

should_fix documentation

Why we think it's a valid issue
  • Checked: the live public guide at posthog.com/docs/libraries/js/config, the generated reference artifact in this repo, and the repo's own convention comment about website docs.
  • Found: the premise holds. The published config guide describes the option as "If the special string history_change is provided, PostHog will capture pageviews based on path changes by listening to the browser's history API which is useful for single page apps." It names no query string, search, or hash component. After this PR that sentence states the wrong contract, not merely an incomplete one.
  • Found: the guide text is hand-written, so no generation step fixes it. Its wording ("path changes", "useful for single page apps") differs from the api-extractor output in packages/browser/references/posthog-js-references-latest.json, which uses "Capture the initial pageview and pageviews when the pathname changes". The two artifacts are separate: regenerating the reference JSON leaves the guide unchanged, so this does not duplicate the stale-reference finding.
  • Found: the repo asks contributors to do this. packages/browser/src/posthog-core.ts:255-256 states "Remember to update types.ts when changing a default value / to guarantee documentation is up to date, make sure to also update our website docs." The request follows a house rule rather than inventing one.
  • Impact: confirmed. This PR raises $pageview volume for every project on 'history_change', and the guide customers read to explain that number still documents path-only capture. A reader cannot connect the volume change to the SDK behavior from the current text.
  • Impact: the fix lands in the posthog.com repository, so it cannot block this PR and reads as a follow-up. I verified the rendered page, not the exact source path contents/docs/libraries/js/config.mdx, so the author should confirm the file name when they make that change.
Issue description

The public JavaScript config guide still says that history_change captures path changes only. Users who read that guide will expect the old behavior and event volume.

Suggested fix

Update contents/docs/libraries/js/config.mdx in the posthog.com repository. List path, query string, and hash changes. Also explain the disable_capture_url_hashes interaction.

Prompt to fix with AI (copy-paste) 
## Context
@packages/types/src/posthog-config.ts#L1371-1372

<issue_description>
The public JavaScript config guide still says that `history_change` captures path changes only. Users who read that guide will expect the old behavior and event volume.
</issue_description>

<issue_validation>
- **Checked:** the live public guide at `posthog.com/docs/libraries/js/config`, the generated reference artifact in this repo, and the repo's own convention comment about website docs.
- **Found:** the premise holds. The published config guide describes the option as "If the special string history_change is provided, PostHog will capture pageviews based on **path changes** by listening to the browser's history API which is useful for single page apps." It names no query string, search, or hash component. After this PR that sentence states the wrong contract, not merely an incomplete one.
- **Found:** the guide text is hand-written, so no generation step fixes it. Its wording ("path changes", "useful for single page apps") differs from the api-extractor output in `packages/browser/references/posthog-js-references-latest.json`, which uses "Capture the initial pageview and pageviews when the pathname changes". The two artifacts are separate: regenerating the reference JSON leaves the guide unchanged, so this does not duplicate the stale-reference finding.
- **Found:** the repo asks contributors to do this. `packages/browser/src/posthog-core.ts:255-256` states "Remember to update `types.ts` when changing a default value / to guarantee documentation is up to date, make sure to also update our website docs." The request follows a house rule rather than inventing one.
- **Impact:** confirmed. This PR raises `$pageview` volume for every project on `'history_change'`, and the guide customers read to explain that number still documents path-only capture. A reader cannot connect the volume change to the SDK behavior from the current text.
- **Impact:** the fix lands in the `posthog.com` repository, so it cannot block this PR and reads as a follow-up. I verified the rendered page, not the exact source path `contents/docs/libraries/js/config.mdx`, so the author should confirm the file name when they make that change.
</issue_validation>

## Task
Investigate the issue and solve it

<potential_solution>
Update `contents/docs/libraries/js/config.mdx` in the `posthog.com` repository. List path, query string, and hash changes. Also explain the `disable_capture_url_hashes` interaction.
</potential_solution>

* - An object: Capture the initial pageview and pageviews when any selected URL component changes
*
* @default true (or `'history_change'` when `defaults` is `'2025-05-24'` or later)
Expand Down
Loading