feat: track time spent on a page

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

@@ -108,6 +108,17 @@
   events?: PreConsentEventsOptions;
 };
 
+export enum PageLifecycleEvents {
+  LOADED = 'Page Loaded',
+  UNLOADED = 'Page Unloaded',
+}
+
+export type TrackPageLifecycleOptions = {
+  enabled: boolean; // default false
+  events?: PageLifecycleEvents[];
+  options?: ApiOptions;
+};
+
 /**
  * Represents the options parameter in the load API
  */
@@ -150,6 +161,7 @@
   externalAnonymousIdCookieName?: string;
   useServerSideCookies?: boolean;
   dataServiceEndpoint?: string;
+  trackPageLifecycle?: TrackPageLifecycleOptions;
 };
 
 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)',
@@ -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/public/index.html

@@ -150,12 +150,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
 
@@ -80,7 +88,7 @@
     this.consent = this.consent.bind(this);
 
     RudderAnalytics.globalSingleton = this;
-
+    this.logger?.setMinLogLevel('WARN');
     // start loading if a load event was buffered or wait for explicit load call
     this.triggerBufferedLoadEvent();
 
@@ -133,6 +141,73 @@
     this.getAnalyticsInstance(writeKey).load(writeKey, dataPlaneUrl, loadOptions);
   }
 
+  /**
+   * A function to track page lifecycle events like page loaded and page unloaded
+   * @param preloadedEventsArray
+   * @param loadOptions
+   * @returns
+   */
+  // eslint-disable-next-line class-methods-use-this
+  trackPageLifecycleEvents(
+    preloadedEventsArray: PreloadedEventCall[],
+    loadOptions?: Partial<LoadOptions>,
+  ) {
+    const { trackPageLifecycle, useBeacon } = loadOptions ?? {};
+    const {
+      events = [PageLifecycleEvents.LOADED, PageLifecycleEvents.UNLOADED],
+      enabled = false,
+      options = {},
+    } = trackPageLifecycle ?? {};
+
+    if (!enabled) {
+      return;
+    }
+
+    const visitId = generateUUID();
+    const pageLoadedTimestamp = Date.now();
+
+    // 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);
+      }
+    }
+    setExposedGlobal(GLOBAL_PRELOAD_BUFFER, clone(preloadedEventsArray));
+  }
+
   /**
    * Trigger load event in buffer queue if exists and stores the
    * remaining preloaded events array in global object
@@ -155,6 +230,8 @@
 
     // Process load method if present in the buffered requests
     if (loadEvent.length > 0) {
+      // Track page loaded lifecycle event if enabled
+      this.trackPageLifecycleEvents(preloadedEventsArray, loadEvent[3]);
       // Remove the event name from the Buffered Event array and keep only arguments
       loadEvent.shift();
       // eslint-disable-next-line @typescript-eslint/ban-ts-comment

packages/analytics-js/src/components/utilities/loadOptions.ts

@@ -121,6 +121,14 @@
     normalizedLoadOpts.preConsent = removeUndefinedAndNullValues(normalizedLoadOpts.preConsent);
   }
 
+  if (!isObjectLiteralAndNotNull(normalizedLoadOpts.trackPageLifecycle)) {
+    delete normalizedLoadOpts.trackPageLifecycle;
+  } else {
+    normalizedLoadOpts.trackPageLifecycle = removeUndefinedAndNullValues(
+      normalizedLoadOpts.trackPageLifecycle,
+    );
+  }
+
   const mergedLoadOptions: LoadOptions = mergeDeepRight(loadOptionsFromState, normalizedLoadOpts);
 
   return mergedLoadOptions;

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

@@ -257,6 +257,8 @@ const INVALID_POLYFILL_URL_WARNING = (
 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 = `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 +323,5 @@ export {
   COMPONENT_BASE_URL_ERROR,
   SERVER_SIDE_COOKIE_FEATURE_OVERRIDE_WARNING,
   BAD_COOKIES_WARNING,
+  PAGE_UNLOAD_ON_BEACON_DISABLED_WARNING,
 };

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

@@ -1,6 +1,9 @@
 import { signal } from '@preact/signals-core';
 import { clone } from 'ramda';
-import type { LoadOptions } from '@rudderstack/analytics-js-common/types/LoadOptions';
+import {
+  PageLifecycleEvents,
+  type LoadOptions,
+} from '@rudderstack/analytics-js-common/types/LoadOptions';
 import type { LoadOptionsState } from '@rudderstack/analytics-js-common/types/ApplicationState';
 import {
   DEFAULT_DATA_PLANE_EVENTS_BUFFER_TIMEOUT_MS,
@@ -39,6 +42,10 @@ const defaultLoadOptions: LoadOptions = {
   },
   sendAdblockPageOptions: {},
   useServerSideCookies: false,
+  trackPageLifecycle: {
+    enabled: false,
+    events: [PageLifecycleEvents.LOADED, PageLifecycleEvents.UNLOADED],
+  },
 };
 
 const loadOptionsState: LoadOptionsState = signal(clone(defaultLoadOptions));