feat: track time spent on a page

packages/analytics-js-common/src/types/ApplicationState.ts

@@ -83,6 +83,15 @@ export type LifecycleState = {
   dataPlaneUrl: Signal<string | undefined>;
 };
 
+export type AutoTrackState = {
+  pageLifecycle: PageLifecycleState;
+};
+
+export type PageLifecycleState = {
+  visitId: Signal<string | undefined>;
+  pageLoadedTimestamp: Signal<number | undefined>;
+};
+
 export type LoadOptionsState = Signal<LoadOptions>;
 
 // TODO: define the metrics that we need to track
@@ -191,6 +200,7 @@ export interface ApplicationState {
   storage: StorageState;
   serverCookies: ServerCookiesState;
   dataPlaneEvents: DataPlaneEventsState;
+  autoTrack: AutoTrackState;
 }
 
 export type DebouncedFunction = (...args: any[]) => void;

packages/analytics-js-common/src/types/LoadOptions.ts

@@ -108,6 +108,23 @@
   events?: PreConsentEventsOptions;
 };
 
+export enum PageLifecycleEvents {
+  LOADED = 'Page Loaded',
+  UNLOADED = 'Page Unloaded',
+}
+
+export type PageLifecycleOptions = {
+  enabled: boolean; // default false
+  events?: PageLifecycleEvents[];
+  options?: ApiOptions;
+};
+
+export type AutoTrackOptions = {
+  enabled?: boolean; // default false
+  options?: ApiOptions;
+  pageLifecycle?: PageLifecycleOptions;
+};
+
 /**
  * Represents the options parameter in the load API
  */
@@ -150,6 +167,7 @@
   externalAnonymousIdCookieName?: string;
   useServerSideCookies?: boolean;
   dataServiceEndpoint?: string;
+  autoTrack?: AutoTrackOptions;
 };
 
 export type ConsentOptions = {

packages/analytics-js/.size-limit.mjs

@@ -36,7 +36,7 @@ export default [
     name: 'Core - Modern - NPM (CJS)',
     path: 'dist/npm/modern/cjs/index.cjs',
     import: '*',
-    limit: '24.5 KiB',
+    limit: '25 KiB',
   },
   {
     name: 'Core - Modern - NPM (UMD)',
@@ -47,7 +47,7 @@ export default [
   {
     name: 'Core - Modern - CDN',
     path: 'dist/cdn/modern/iife/rsa.min.js',
-    limit: '24.5 KiB',
+    limit: '25 KiB',
   },
   {
     name: 'Core (Bundled) - Legacy - NPM (ESM)',
@@ -83,7 +83,7 @@ export default [
     name: 'Core (Bundled) - Modern - NPM (UMD)',
     path: 'dist/npm/modern/bundled/umd/index.js',
     import: '*',
-    limit: '39 KiB',
+    limit: '39.5 KiB',
   },
   {
     name: 'Core (Content Script) - Legacy - NPM (ESM)',
@@ -113,7 +113,7 @@ export default [
     name: 'Core (Content Script) - Modern - NPM (CJS)',
     path: 'dist/npm/modern/content-script/cjs/index.cjs',
     import: '*',
-    limit: '38.5 KiB',
+    limit: '39 KiB',
   },
   {
     name: 'Core (Content Script) - Modern - NPM (UMD)',

packages/analytics-js/__tests__/services/Logger/Logger.test.ts

@@ -188,7 +188,7 @@ describe('Logger', () => {
     );
   });
 
-  it(`should default the min log level to error if incorrectly set`, () => {
+  it(`should default the min log level to log if incorrectly set`, () => {
     loggerInstance = new Logger();
     loggerInstance.setMinLogLevel('dummy' as LogLevel);
     loggerInstance.error('dummy error msg');
@@ -199,6 +199,6 @@ describe('Logger', () => {
     );
 
     loggerInstance.warn('dummy warn msg');
-    expect(console.warn).not.toHaveBeenCalled();
+    expect(console.warn).toHaveBeenCalled();
   });
 });

packages/analytics-js/public/index.html

@@ -154,12 +154,15 @@
               //   events: {
               //     delivery: 'buffer'
               //   }
-              }
+              },
               // plugins: [
               //   'StorageEncryption',
               //   'StorageMigrator',
               //   'XhrQueue'
               // ]
+              // trackPageLifecycle:{
+              //   enabled: true,
+              // }
             };
 
             rudderanalytics.load('__WRITE_KEY__', '__DATAPLANE_URL__', loadOptions);

packages/analytics-js/src/app/RudderAnalytics.ts

@@ -9,16 +9,19 @@
 } from '@rudderstack/analytics-js-common/utilities/eventMethodOverloads';
 import type { IRudderAnalytics } from '@rudderstack/analytics-js-common/types/IRudderAnalytics';
 import type { Nullable } from '@rudderstack/analytics-js-common/types/Nullable';
-import type {
-  AnonymousIdOptions,
-  ConsentOptions,
-  LoadOptions,
+import {
+  PageLifecycleEvents,
+  type AnonymousIdOptions,
+  type ConsentOptions,
+  type LoadOptions,
 } from '@rudderstack/analytics-js-common/types/LoadOptions';
 import type { ApiCallback, ApiOptions } from '@rudderstack/analytics-js-common/types/EventApi';
 import type { ApiObject } from '@rudderstack/analytics-js-common/types/ApiObject';
 import { RS_APP } from '@rudderstack/analytics-js-common/constants/loggerContexts';
 import { isString } from '@rudderstack/analytics-js-common/utilities/checks';
 import type { IdentifyTraits } from '@rudderstack/analytics-js-common/types/traits';
+import { generateUUID } from '@rudderstack/analytics-js-common/utilities/uuId';
+import { onPageLeave } from '@rudderstack/analytics-js-common/utilities/page';
 import { GLOBAL_PRELOAD_BUFFER } from '../constants/app';
 import {
   getPreloadedLoadEvent,
@@ -29,8 +32,13 @@
 import type { IAnalytics } from '../components/core/IAnalytics';
 import { Analytics } from '../components/core/Analytics';
 import { defaultLogger } from '../services/Logger/Logger';
-import { EMPTY_GROUP_CALL_ERROR, WRITE_KEY_NOT_A_STRING_ERROR } from '../constants/logMessages';
+import {
+  EMPTY_GROUP_CALL_ERROR,
+  PAGE_UNLOAD_ON_BEACON_DISABLED_WARNING,
+  WRITE_KEY_NOT_A_STRING_ERROR,
+} from '../constants/logMessages';
 import { defaultErrorHandler } from '../services/ErrorHandler';
+import { state } from '../state';
 
 // TODO: add analytics restart/reset mechanism
 
@@ -81,6 +89,9 @@
 
     RudderAnalytics.globalSingleton = this;
 
+    state.autoTrack.pageLifecycle.visitId.value = generateUUID();
+    state.autoTrack.pageLifecycle.pageLoadedTimestamp.value = Date.now();
+
     // start loading if a load event was buffered or wait for explicit load call
     this.triggerBufferedLoadEvent();
 
@@ -129,18 +140,100 @@
     }
 
     this.setDefaultInstanceKey(writeKey);
+    // Track page loaded lifecycle event if enabled
+    this.trackPageLifecycleEvents(loadOptions);
+
     this.analyticsInstances[writeKey] = new Analytics();
     this.getAnalyticsInstance(writeKey).load(writeKey, dataPlaneUrl, loadOptions);
   }
 
+  /**
+   * A function to get preloaded events array from global object
+   * @returns preloaded events array
+   */
+  // eslint-disable-next-line class-methods-use-this
+  getPreloadedEvents() {
+    return Array.isArray((globalThis as typeof window).rudderanalytics)
+      ? ((globalThis as typeof window).rudderanalytics as unknown as PreloadedEventCall[])
+      : ([] as PreloadedEventCall[]);
+  }
+
+  /**
+   * A function to track page lifecycle events like page loaded and page unloaded
+   * @param preloadedEventsArray
+   * @param loadOptions
+   * @returns
+   */
+  trackPageLifecycleEvents(loadOptions?: Partial<LoadOptions>) {
+    const { autoTrack, useBeacon } = loadOptions ?? {};
+    const {
+      enabled: autoTrackEnabled = false,
+      options: autoTrackOptions = {},
+      pageLifecycle,
+    } = autoTrack ?? {};
+    const {
+      events = [PageLifecycleEvents.LOADED, PageLifecycleEvents.UNLOADED],
+      enabled = autoTrackEnabled,
+      options = autoTrackOptions,
+    } = pageLifecycle ?? {};
+
+    const visitId = state.autoTrack.pageLifecycle.visitId.value;
+    const pageLoadedTimestamp = state.autoTrack.pageLifecycle.pageLoadedTimestamp.value as number;
+
+    if (!enabled) {
+      return;
+    }
+
+    const preloadedEventsArray = this.getPreloadedEvents();
+
+    // track page loaded event
+    if (events.length === 0 || events.includes(PageLifecycleEvents.LOADED)) {
+      preloadedEventsArray.unshift([
+        'track',
+        PageLifecycleEvents.LOADED,
+        { visitId },
+        {
+          ...options,
+          originalTimestamp: new Date(pageLoadedTimestamp).toISOString(),
+        },
+      ]);
+    }
+
+    // track page unloaded event
+    if (events.length === 0 || events.includes(PageLifecycleEvents.UNLOADED)) {
+      if (useBeacon === true) {
+        // Register the page unloaded lifecycle event listeners
+        onPageLeave((isAccessible: boolean) => {
+          if (isAccessible === false && state.lifecycle.loaded.value) {
+            const pageUnloadedTimestamp = Date.now();
+            const visitDuration = pageUnloadedTimestamp - pageLoadedTimestamp;
+            this.track(
+              PageLifecycleEvents.UNLOADED,
+              {
+                visitId,
+                visitDuration,
+              },
+              {
+                ...options,
+                originalTimestamp: new Date(pageUnloadedTimestamp).toISOString(),
+              },
+            );
+          }
+        });
+      } else {
+        // throw warning if beacon is disabled
+        this.logger.warn(PAGE_UNLOAD_ON_BEACON_DISABLED_WARNING(RS_APP));
+      }
+    }
+    setExposedGlobal(GLOBAL_PRELOAD_BUFFER, clone(preloadedEventsArray));
+  }
+
   /**
    * Trigger load event in buffer queue if exists and stores the
    * remaining preloaded events array in global object
    */
   triggerBufferedLoadEvent() {
-    const preloadedEventsArray = Array.isArray((globalThis as typeof window).rudderanalytics)
-      ? ((globalThis as typeof window).rudderanalytics as unknown as PreloadedEventCall[])
-      : ([] as PreloadedEventCall[]);
+    const preloadedEventsArray = this.getPreloadedEvents();
 
     // The array will be mutated in the below method
     promotePreloadedConsentEventsToTop(preloadedEventsArray);

packages/analytics-js/src/components/core/Analytics.ts

@@ -33,7 +33,7 @@ import {
   trackArgumentsToCallOptions,
 } from '@rudderstack/analytics-js-common/utilities/eventMethodOverloads';
 import { BufferQueue } from '@rudderstack/analytics-js-common/services/BufferQueue/BufferQueue';
-import { defaultLogger } from '../../services/Logger';
+import { POST_LOAD_LOG_LEVEL, defaultLogger } from '../../services/Logger';
 import { defaultErrorHandler } from '../../services/ErrorHandler';
 import { defaultPluginEngine } from '../../services/PluginEngine';
 import { PluginsManager } from '../pluginsManager';
@@ -127,9 +127,7 @@ class Analytics implements IAnalytics {
     });
 
     // set log level as early as possible
-    if (state.loadOptions.value.logLevel) {
-      this.logger?.setMinLogLevel(state.loadOptions.value.logLevel);
-    }
+    this.logger?.setMinLogLevel(state.loadOptions.value.logLevel ?? POST_LOAD_LOG_LEVEL);
 
     // Expose state to global objects
     setExposedGlobal('state', state, writeKey);

packages/analytics-js/src/constants/logMessages.ts

@@ -257,6 +257,9 @@
 const BAD_COOKIES_WARNING = (key: string) =>
   `The cookie data for ${key} seems to be encrypted using SDK versions < v3. The data is dropped. This can potentially stem from using SDK versions < v3 on other sites or web pages that can share cookies with this webpage. We recommend using the same SDK (v3) version everywhere or avoid disabling the storage data migration.`;
 
+const PAGE_UNLOAD_ON_BEACON_DISABLED_WARNING = (context: string) =>
+  `${context}${LOG_CONTEXT_SEPARATOR}Page Unloaded event can only be tracked when the Beacon transport is active. Please enable "useBeacon" load API option.`;
+
 export {
   UNSUPPORTED_CONSENT_MANAGER_ERROR,
   UNSUPPORTED_ERROR_REPORTING_PROVIDER_WARNING,
@@ -321,4 +324,5 @@
   COMPONENT_BASE_URL_ERROR,
   SERVER_SIDE_COOKIE_FEATURE_OVERRIDE_WARNING,
   BAD_COOKIES_WARNING,
+  PAGE_UNLOAD_ON_BEACON_DISABLED_WARNING,
 };

packages/analytics-js/src/services/Logger/Logger.ts

@@ -11,7 +11,8 @@ const LOG_LEVEL_MAP: Record<LogLevel, number> = {
   NONE: 5,
 };
 
-const DEFAULT_LOG_LEVEL = 'ERROR';
+const DEFAULT_LOG_LEVEL = 'LOG';
+const POST_LOAD_LOG_LEVEL = 'ERROR';
 const LOG_MSG_PREFIX = 'RS SDK';
 const LOG_MSG_PREFIX_STYLE = 'font-weight: bold; background: black; color: white;';
 const LOG_MSG_STYLE = 'font-weight: normal;';
@@ -120,4 +121,5 @@ export {
   LOG_MSG_PREFIX_STYLE,
   LOG_MSG_STYLE,
   defaultLogger,
+  POST_LOAD_LOG_LEVEL,
 };

packages/analytics-js/src/services/Logger/index.ts

@@ -1 +1,7 @@
-export { Logger, DEFAULT_LOG_LEVEL, LOG_LEVEL_MAP, defaultLogger } from './Logger';
+export {
+  Logger,
+  DEFAULT_LOG_LEVEL,
+  LOG_LEVEL_MAP,
+  defaultLogger,
+  POST_LOAD_LOG_LEVEL,
+} from './Logger';

packages/analytics-js/src/state/index.ts

@@ -15,6 +15,7 @@ import { pluginsState } from './slices/plugins';
 import { storageState } from './slices/storage';
 import { serverSideCookiesState } from './slices/serverCookies';
 import { dataPlaneEventsState } from './slices/dataPlaneEvents';
+import { autoTrackState } from './slices/autoTrack';
 
 const defaultStateValues: ApplicationState = {
   capabilities: capabilitiesState,
@@ -32,6 +33,7 @@ const defaultStateValues: ApplicationState = {
   storage: storageState,
   serverCookies: serverSideCookiesState,
   dataPlaneEvents: dataPlaneEventsState,
+  autoTrack: autoTrackState,
 };
 
 const state: ApplicationState = {
@@ -54,6 +56,7 @@ const resetState = () => {
   state.storage = clone(defaultStateValues.storage);
   state.serverCookies = clone(defaultStateValues.serverCookies);
   state.dataPlaneEvents = clone(defaultStateValues.dataPlaneEvents);
+  state.autoTrack = clone(defaultStateValues.autoTrack);
 };
 
 export { state, resetState };

packages/analytics-js/src/state/slices/autoTrack.ts

@@ -0,0 +1,11 @@
+import { signal } from '@preact/signals-core';
+import type { AutoTrackState } from '@rudderstack/analytics-js-common/types/ApplicationState';
+
+const autoTrackState: AutoTrackState = {
+  pageLifecycle: {
+    visitId: signal(undefined),
+    pageLoadedTimestamp: signal(undefined),
+  },
+};
+
+export { autoTrackState };