@amplifyup/sdk 0.1.24 → 0.1.25

package/dist/index.d.mts

@@ -108,6 +108,16 @@ declare function normalizeRoute(route: string): string;
  * Must stay aligned with SESSION_GAP_MS in apps/orchestrator/lib/aws-profiles.ts.
  */
 declare const SESSION_IDLE_GAP_MS: number;
+/**
+ * Time-on-page emit strategy (cumulative visible seconds).
+ * Early milestones, then sparse checkpoints — not a fixed heartbeat.
+ * Abandoned-but-visible tabs freeze after DWELL_ACTIVITY_IDLE_MS.
+ */
+declare const DWELL_MILESTONES_SEC: readonly [15, 30, 60, 120, 300];
+/** After the last milestone, emit at most once per this many seconds. */
+declare const DWELL_CHECKPOINT_SEC: number;
+/** Stop accruing dwell while visible but without user activity. */
+declare const DWELL_ACTIVITY_IDLE_MS: number;
 interface EventTrackingConfig {
     eventName: string;
     eventType: string;
@@ -194,8 +204,10 @@ declare class AmplifyUpSDK {
     /** Current page path for engagement attribution. */
     private currentPath;
     /**
-     * Automatic page-level Scroll Depth + Time on Page (dwell heartbeat).
-     * State lives on the instance so SPA route changes can reset milestones.
+     * Automatic page-level Scroll Depth + Time on Page.
+     * Dwell uses milestones / sparse checkpoints (not a fixed 15s heartbeat),
+     * freezes while the tab is visible but the user is idle, and always flushes
+     * on hide / unload / SPA route change.
      */
     private setupPageEngagement;
     /** Flush dwell then reset — used on SPA route changes. */
@@ -505,4 +517,4 @@ declare const verifyAWSConnection: () => {
 
 declare const _default: AmplifyUpSDK;
 
-export { AmplifyContentMeta, AmplifyUpConfig, AmplifyUpSDK, AmplifyUpTarget, CDPAdapter, ContentSource, EdgeResolveError, EventProperties, EventTrackingConfig$1 as EventTrackingConfig, type FetchContentOptions, type FetchContentResult, IdentifyInput, IdentifyTraits, PageConfig, ProfileFieldsInput, SESSION_IDLE_GAP_MS, buildLayoutProviderUrl, buildPageRenderUrl, cleanupEventTracking, _default as default, fetchContent, fetchEdgeResolve, fetchPageConfig, getDiagnostics, getInstanceId, getOrchestratorUrl, getSDK, getStatus, getTarget, getTrackingId, getUserId, identify, init, mapResolvedToPageConfig, normalizeRoute, page, refreshEventTracking, reset, routeChange, setProfileFields, setupComponentViewTracking, setupEventTracking, testTracking, track, trackClick, trackContentEngagement, trackContentView, trackFormFieldInteraction, trackFormSubmit, verifyAWSConnection };
+export { AmplifyContentMeta, AmplifyUpConfig, AmplifyUpSDK, AmplifyUpTarget, CDPAdapter, ContentSource, DWELL_ACTIVITY_IDLE_MS, DWELL_CHECKPOINT_SEC, DWELL_MILESTONES_SEC, EdgeResolveError, EventProperties, EventTrackingConfig$1 as EventTrackingConfig, type FetchContentOptions, type FetchContentResult, IdentifyInput, IdentifyTraits, PageConfig, ProfileFieldsInput, SESSION_IDLE_GAP_MS, buildLayoutProviderUrl, buildPageRenderUrl, cleanupEventTracking, _default as default, fetchContent, fetchEdgeResolve, fetchPageConfig, getDiagnostics, getInstanceId, getOrchestratorUrl, getSDK, getStatus, getTarget, getTrackingId, getUserId, identify, init, mapResolvedToPageConfig, normalizeRoute, page, refreshEventTracking, reset, routeChange, setProfileFields, setupComponentViewTracking, setupEventTracking, testTracking, track, trackClick, trackContentEngagement, trackContentView, trackFormFieldInteraction, trackFormSubmit, verifyAWSConnection };

package/dist/index.d.ts

@@ -108,6 +108,16 @@ declare function normalizeRoute(route: string): string;
  * Must stay aligned with SESSION_GAP_MS in apps/orchestrator/lib/aws-profiles.ts.
  */
 declare const SESSION_IDLE_GAP_MS: number;
+/**
+ * Time-on-page emit strategy (cumulative visible seconds).
+ * Early milestones, then sparse checkpoints — not a fixed heartbeat.
+ * Abandoned-but-visible tabs freeze after DWELL_ACTIVITY_IDLE_MS.
+ */
+declare const DWELL_MILESTONES_SEC: readonly [15, 30, 60, 120, 300];
+/** After the last milestone, emit at most once per this many seconds. */
+declare const DWELL_CHECKPOINT_SEC: number;
+/** Stop accruing dwell while visible but without user activity. */
+declare const DWELL_ACTIVITY_IDLE_MS: number;
 interface EventTrackingConfig {
     eventName: string;
     eventType: string;
@@ -194,8 +204,10 @@ declare class AmplifyUpSDK {
     /** Current page path for engagement attribution. */
     private currentPath;
     /**
-     * Automatic page-level Scroll Depth + Time on Page (dwell heartbeat).
-     * State lives on the instance so SPA route changes can reset milestones.
+     * Automatic page-level Scroll Depth + Time on Page.
+     * Dwell uses milestones / sparse checkpoints (not a fixed 15s heartbeat),
+     * freezes while the tab is visible but the user is idle, and always flushes
+     * on hide / unload / SPA route change.
      */
     private setupPageEngagement;
     /** Flush dwell then reset — used on SPA route changes. */
@@ -505,4 +517,4 @@ declare const verifyAWSConnection: () => {
 
 declare const _default: AmplifyUpSDK;
 
-export { AmplifyContentMeta, AmplifyUpConfig, AmplifyUpSDK, AmplifyUpTarget, CDPAdapter, ContentSource, EdgeResolveError, EventProperties, EventTrackingConfig$1 as EventTrackingConfig, type FetchContentOptions, type FetchContentResult, IdentifyInput, IdentifyTraits, PageConfig, ProfileFieldsInput, SESSION_IDLE_GAP_MS, buildLayoutProviderUrl, buildPageRenderUrl, cleanupEventTracking, _default as default, fetchContent, fetchEdgeResolve, fetchPageConfig, getDiagnostics, getInstanceId, getOrchestratorUrl, getSDK, getStatus, getTarget, getTrackingId, getUserId, identify, init, mapResolvedToPageConfig, normalizeRoute, page, refreshEventTracking, reset, routeChange, setProfileFields, setupComponentViewTracking, setupEventTracking, testTracking, track, trackClick, trackContentEngagement, trackContentView, trackFormFieldInteraction, trackFormSubmit, verifyAWSConnection };
+export { AmplifyContentMeta, AmplifyUpConfig, AmplifyUpSDK, AmplifyUpTarget, CDPAdapter, ContentSource, DWELL_ACTIVITY_IDLE_MS, DWELL_CHECKPOINT_SEC, DWELL_MILESTONES_SEC, EdgeResolveError, EventProperties, EventTrackingConfig$1 as EventTrackingConfig, type FetchContentOptions, type FetchContentResult, IdentifyInput, IdentifyTraits, PageConfig, ProfileFieldsInput, SESSION_IDLE_GAP_MS, buildLayoutProviderUrl, buildPageRenderUrl, cleanupEventTracking, _default as default, fetchContent, fetchEdgeResolve, fetchPageConfig, getDiagnostics, getInstanceId, getOrchestratorUrl, getSDK, getStatus, getTarget, getTrackingId, getUserId, identify, init, mapResolvedToPageConfig, normalizeRoute, page, refreshEventTracking, reset, routeChange, setProfileFields, setupComponentViewTracking, setupEventTracking, testTracking, track, trackClick, trackContentEngagement, trackContentView, trackFormFieldInteraction, trackFormSubmit, verifyAWSConnection };

package/dist/index.js

@@ -510,6 +510,10 @@ async function fetchContent(options) {
 
 // src/index.ts
 var SESSION_IDLE_GAP_MS = 30 * 60 * 1e3;
+var DWELL_MILESTONES_SEC = [15, 30, 60, 120, 300];
+var DWELL_CHECKPOINT_SEC = 15 * 60;
+var DWELL_ACTIVITY_IDLE_MS = 2 * 60 * 1e3;
+var DWELL_POLL_MS = 5e3;
 function readPreviewQueryOverrides() {
   if (typeof window === "undefined") return {};
   const params = new URLSearchParams(window.location.search);
@@ -580,7 +584,10 @@ var AmplifyUpSDK = class {
       visibleSince: null,
       lastDwellSecondsSent: 0,
       /** When the tab last became hidden — used for idle-resume re-page. */
-      hiddenAt: null
+      hiddenAt: null,
+      /** Last user interaction — freezes dwell when stale while visible. */
+      lastActivityAt: 0,
+      activityIdle: false
     };
     this.adapter = adapter || new AWSAdapter();
     if (typeof window !== "undefined") {
@@ -803,8 +810,10 @@ var AmplifyUpSDK = class {
     return window.location.pathname || "/";
   }
   /**
-   * Automatic page-level Scroll Depth + Time on Page (dwell heartbeat).
-   * State lives on the instance so SPA route changes can reset milestones.
+   * Automatic page-level Scroll Depth + Time on Page.
+   * Dwell uses milestones / sparse checkpoints (not a fixed 15s heartbeat),
+   * freezes while the tab is visible but the user is idle, and always flushes
+   * on hide / unload / SPA route change.
    */
   setupPageEngagement() {
     if (typeof window === "undefined" || typeof document === "undefined") return;
@@ -817,6 +826,8 @@ var AmplifyUpSDK = class {
     state.visibleSince = document.visibilityState === "visible" ? Date.now() : null;
     state.lastDwellSecondsSent = 0;
     state.hiddenAt = document.visibilityState === "hidden" ? Date.now() : null;
+    state.lastActivityAt = Date.now();
+    state.activityIdle = false;
     let scrollRaf = null;
     const path = () => this.currentPath();
     const measureScrollPercent = () => {
@@ -848,6 +859,7 @@ var AmplifyUpSDK = class {
       }
     };
     const onScroll = () => {
+      noteActivity();
       if (scrollRaf != null) return;
       scrollRaf = window.requestAnimationFrame(() => {
         scrollRaf = null;
@@ -859,19 +871,58 @@ var AmplifyUpSDK = class {
       state.visibleMs += Date.now() - state.visibleSince;
       state.visibleSince = Date.now();
     };
-    const emitDwell = (_force = false) => {
-      if (this.isPreviewMode()) return;
+    const freezeActivityIdle = () => {
+      if (state.activityIdle) return;
       accumulateVisible();
+      state.visibleSince = null;
+      state.activityIdle = true;
+    };
+    const noteActivity = () => {
+      state.lastActivityAt = Date.now();
+      if (state.activityIdle) {
+        state.activityIdle = false;
+        if (document.visibilityState === "visible" && state.visibleSince == null) {
+          state.visibleSince = Date.now();
+        }
+      }
+    };
+    const nextEmitTarget = (lastSent) => {
+      for (const m of DWELL_MILESTONES_SEC) {
+        if (m > lastSent) return { seconds: m, reason: "milestone" };
+      }
+      const nextCheckpoint = Math.floor(lastSent / DWELL_CHECKPOINT_SEC) * DWELL_CHECKPOINT_SEC + DWELL_CHECKPOINT_SEC;
+      const target = nextCheckpoint > lastSent ? nextCheckpoint : lastSent + DWELL_CHECKPOINT_SEC;
+      return { seconds: target, reason: "checkpoint" };
+    };
+    const emitDwell = (reason, force = false) => {
+      if (this.isPreviewMode()) return;
+      if (!state.activityIdle) {
+        accumulateVisible();
+      }
       const seconds = Math.floor(state.visibleMs / 1e3);
       if (seconds <= 0) return;
       if (seconds <= state.lastDwellSecondsSent) return;
+      if (!force) {
+        const target = nextEmitTarget(state.lastDwellSecondsSent);
+        if (!target || seconds < target.seconds) return;
+        reason = target.reason;
+      }
       state.lastDwellSecondsSent = seconds;
       this.track("Time on Page", {
         seconds,
-        path: this.lastTrackedPath || path()
+        path: this.lastTrackedPath || path(),
+        reason
       });
     };
-    this._emitPageDwell = emitDwell;
+    const evaluateDwell = () => {
+      if (document.visibilityState !== "visible") return;
+      if (Date.now() - state.lastActivityAt >= DWELL_ACTIVITY_IDLE_MS) {
+        freezeActivityIdle();
+        return;
+      }
+      emitDwell("milestone", false);
+    };
+    this._emitPageDwell = (force) => emitDwell("route", force !== false);
     const onVisibility = () => {
       if (document.visibilityState === "visible") {
         const idleMs = state.hiddenAt != null ? Date.now() - state.hiddenAt : 0;
@@ -889,35 +940,51 @@ var AmplifyUpSDK = class {
             );
           }
         }
+        noteActivity();
         state.visibleSince = Date.now();
+        state.activityIdle = false;
       } else {
-        emitDwell(true);
+        emitDwell("hidden", true);
         state.hiddenAt = Date.now();
         state.visibleSince = null;
+        state.activityIdle = false;
       }
     };
     const onPageHide = () => {
-      emitDwell(true);
+      emitDwell("unload", true);
       if (state.hiddenAt == null) {
         state.hiddenAt = Date.now();
       }
       state.visibleSince = null;
     };
+    const activityEvents = [
+      "pointerdown",
+      "keydown",
+      "scroll",
+      "touchstart"
+    ];
+    const onActivity = () => noteActivity();
     window.addEventListener("scroll", onScroll, { passive: true });
     document.addEventListener("visibilitychange", onVisibility);
     window.addEventListener("pagehide", onPageHide);
+    for (const evt of activityEvents) {
+      if (evt === "scroll") continue;
+      window.addEventListener(evt, onActivity, { passive: true });
+    }
     checkScroll();
     const heartbeat = setInterval(() => {
-      if (document.visibilityState === "visible") {
-        emitDwell(false);
-      }
-    }, 15e3);
+      evaluateDwell();
+    }, DWELL_POLL_MS);
     this.trackingIntervals.push(heartbeat);
     const previousCleanup = this.trackingCleanup;
     this.trackingCleanup = () => {
       window.removeEventListener("scroll", onScroll);
       document.removeEventListener("visibilitychange", onVisibility);
       window.removeEventListener("pagehide", onPageHide);
+      for (const evt of activityEvents) {
+        if (evt === "scroll") continue;
+        window.removeEventListener(evt, onActivity);
+      }
       if (scrollRaf != null) {
         window.cancelAnimationFrame(scrollRaf);
         scrollRaf = null;
@@ -943,6 +1010,8 @@ var AmplifyUpSDK = class {
     state.visibleMs = 0;
     state.lastDwellSecondsSent = 0;
     state.hiddenAt = null;
+    state.lastActivityAt = Date.now();
+    state.activityIdle = false;
     state.visibleSince = typeof document !== "undefined" && document.visibilityState === "visible" ? Date.now() : null;
     this.componentViewSeen.clear();
   }
@@ -2693,6 +2762,9 @@ var verifyAWSConnection = () => {
 var index_default = getSDK();
 
 exports.AmplifyUpSDK = AmplifyUpSDK;
+exports.DWELL_ACTIVITY_IDLE_MS = DWELL_ACTIVITY_IDLE_MS;
+exports.DWELL_CHECKPOINT_SEC = DWELL_CHECKPOINT_SEC;
+exports.DWELL_MILESTONES_SEC = DWELL_MILESTONES_SEC;
 exports.EdgeResolveError = EdgeResolveError;
 exports.SESSION_IDLE_GAP_MS = SESSION_IDLE_GAP_MS;
 exports.buildLayoutProviderUrl = buildLayoutProviderUrl;