refactor: rely on capture_pageview config

Author: lricoy

src/__tests__/__snapshots__/config-snapshot.test.ts.snap

@@ -53,10 +53,6 @@ exports[`config snapshot for PostHogConfig 1`] = `
     \\"false\\",
     \\"true\\"
   ],
-  \\"capture_history_events\\": [
-    \\"false\\",
-    \\"true\\"
-  ],
   \\"cross_subdomain_cookie\\": [
     \\"false\\",
     \\"true\\"
@@ -100,7 +96,8 @@ exports[`config snapshot for PostHogConfig 1`] = `
   ],
   \\"capture_pageview\\": [
     \\"false\\",
-    \\"true\\"
+    \\"true\\",
+    \\"\\\\\\"history_change\\\\\\"\\"
   ],
   \\"capture_pageleave\\": [
     \\"false\\",

src/__tests__/extensions/history-autocapture.test.ts

@@ -35,7 +35,7 @@ describe('HistoryAutocapture', () => {
         posthog = {
             capture,
             config: {
-                capture_history_events: true,
+                capture_pageview: 'history_change',
             },
             pageViewManager: {
                 doPageView: pageViewManagerDoPageView,
@@ -63,23 +63,29 @@ describe('HistoryAutocapture', () => {
             expect((window.history.replaceState as any).__posthog_wrapped__).toBe(true)
         })
 
-        it('should be enabled with true option', () => {
-            posthog.config.capture_history_events = true
+        it('should NOT be enabled with true option for backwards compatibility', () => {
+            posthog.config.capture_pageview = true
             const historyAutocaptureEnabled = new HistoryAutocapture(posthog)
-            expect(historyAutocaptureEnabled.isEnabled).toBe(true)
+            expect(historyAutocaptureEnabled.isEnabled).toBe(false)
         })
 
         it('should be disabled with false option', () => {
-            posthog.config.capture_history_events = false
+            posthog.config.capture_pageview = false
             const historyAutocaptureDisabled = new HistoryAutocapture(posthog)
             expect(historyAutocaptureDisabled.isEnabled).toBe(false)
         })
 
+        it('should be enabled with history_change option', () => {
+            posthog.config.capture_pageview = 'history_change'
+            const historyAutocaptureEnabled = new HistoryAutocapture(posthog)
+            expect(historyAutocaptureEnabled.isEnabled).toBe(true)
+        })
+
         it('should not setup event listeners if feature is disabled', () => {
             window.history.pushState = originalPushState
             window.history.replaceState = originalReplaceState
 
-            posthog.config.capture_history_events = false
+            posthog.config.capture_pageview = false
             const historyAutocaptureDisabled = new HistoryAutocapture(posthog)
             historyAutocaptureDisabled.startIfEnabled()
 
@@ -121,9 +127,9 @@ describe('HistoryAutocapture', () => {
             expect(capture).not.toHaveBeenCalled()
         })
 
-        it('should not capture pageview when capture_history_events is disabled', () => {
+        it('should not capture pageview when capture_pageview is disabled', () => {
             historyAutocapture.stop()
-            posthog.config.capture_history_events = false
+            posthog.config.capture_pageview = false
             historyAutocapture = new HistoryAutocapture(posthog)
             historyAutocapture.startIfEnabled()
 

src/extensions/history-autocapture.ts

@@ -7,6 +7,9 @@ import { patch } from './replay/rrweb-plugins/patch'
 /**
  * This class is used to capture pageview events when the user navigates using the history API (pushState, replaceState)
  * and when the user navigates using the browser's back/forward buttons.
+ *
+ * The behavior is controlled by the `capture_pageview` configuration option:
+ * - When set to `'history_change'`, this class will capture pageviews on history API changes
  */
 export class HistoryAutocapture {
     private _instance: PostHog
@@ -19,7 +22,7 @@ export class HistoryAutocapture {
     }
 
     public get isEnabled(): boolean {
-        return !!this._instance.config.capture_history_events
+        return this._instance.config.capture_pageview === 'history_change'
     }
 
     public startIfEnabled(): void {

src/posthog-core.ts

@@ -145,9 +145,8 @@ export const defaultConfig = (): PostHogConfig => ({
     custom_campaign_params: [],
     custom_blocked_useragents: [],
     save_referrer: true,
-    capture_pageview: true,
+    capture_pageview: true, // can be true, false, or 'history-change'
     capture_pageleave: 'if_capture_pageview', // We'll only capture pageleave events if capture_pageview is also true
-    capture_history_events: false,
     debug: (location && isString(location?.search) && location.search.indexOf('__posthog_debug=true') !== -1) || false,
     cookie_expiration: 365,
     upgrade: false,
@@ -2002,7 +2001,8 @@ export class PostHog {
     _shouldCapturePageleave(): boolean {
         return (
             this.config.capture_pageleave === true ||
-            (this.config.capture_pageleave === 'if_capture_pageview' && this.config.capture_pageview)
+            (this.config.capture_pageleave === 'if_capture_pageview' &&
+                (this.config.capture_pageview === true || this.config.capture_pageview === 'history_change'))
         )
     }
 

src/types.ts

@@ -331,13 +331,6 @@ export interface PostHogConfig {
      */
     rageclick: boolean
 
-    /**
-     * Determines whether PostHog should automatically capture navigation events using the History API and emit them as pageviews.
-     *
-     * @default false
-     */
-    capture_history_events: boolean
-
     /**
      * Determines if cookie should be set on the top level domain (example.com).
      * If PostHog-js is loaded on a subdomain (test.example.com), and `cross_subdomain_cookie` is set to false,
@@ -426,10 +419,14 @@ export interface PostHogConfig {
 
     /**
      * Determines whether PostHog should capture pageview events automatically.
+     * Can be:
+     * - `true`: Capture regular pageviews (default)
+     * - `false`: Don't capture any pageviews
+     * - `'history_change'`: Only capture pageviews on history API changes (pushState, replaceState, popstate)
      *
      * @default true
      */
-    capture_pageview: boolean
+    capture_pageview: boolean | 'history_change'
 
     /**
      * Determines whether PostHog should capture pageleave events.