@magicfeedback/popup-sdk 1.11.0 → 1.13.0

package/dist/index.d.mts

@@ -383,6 +383,23 @@ type EventListener = (event: DeepdotsEvent) => void;
  *    anterior se cierra y se abre otra, como hace GA con su timeout de sesión.
  */
 type SessionEndReason = 'page_hide' | 'background' | 'user_change' | 'tracking_disabled' | 'manual' | 'idle_timeout';
+/**
+ * Motivo del `deepdots_session_start` (param `reason`): por qué EMPIEZA la sesión. Permite a
+ * analytics separar una carga/arranque real de una vuelta desde background ("Started here").
+ * Mismos valores que el SDK nativo donde el significado coincide:
+ *  - `cold_start`: `init()` (carga de la página / arranque de la app RN) sin sesión suspendida
+ *    que reanudar. Una recarga en menos de 1 min no emite `session_start` sino
+ *    `deepdots_session_resume`.
+ *  - `foreground`: `onForeground()` (RN, AppState 'active') tras un cierre (`onBackground()`
+ *    o `endSession()`). Con la sesión abierta no emite nada.
+ *  - `tracking_enabled`: `setTrackingEnabled(true)` (consentimiento concedido).
+ *  - `user_change`: `setUserId()` o un `init()` con otro `userId`, tras cerrar la del anterior.
+ *  - `idle_timeout`: la pestaña vuelve a verse tras más de 30 min oculta (web): la sesión
+ *    anterior se cerró (o se descartó) y empieza otra.
+ *  - `bfcache_restore`: la página vuelve de la bfcache (botón atrás, `pageshow` con
+ *    `persisted`) fuera de la ventana de reanudación (web).
+ */
+type SessionStartReason = 'cold_start' | 'foreground' | 'tracking_enabled' | 'user_change' | 'idle_timeout' | 'bfcache_restore';
 /** Trigger type used by remote popup definitions */
 type PopupTriggerType = 'time_on_page' | 'scroll' | 'exit' | 'click' | 'event';
 type PopupTriggerConditionStatus = 'SHOWED' | 'PARTIAL' | 'COMPLETED';
@@ -888,8 +905,15 @@ declare class DeepdotsPopups {
      */
     private closeSession;
     /**
-     * Abre sesión (`session_start`) si no hay una abierta y el tracking está activo. Idempotente:
-     * se llama en init(), al volver a foreground y al conceder el consentimiento.
+     * Abre sesión (`session_start`) si no hay una abierta y el tracking está activo. Idempotente.
+     * El `reason` dice por qué empieza (ver `SessionStartReason`):
+     *  - `cold_start`: init() (carga de la página / arranque de la app RN).
+     *  - `foreground`: onForeground() tras un cierre (RN).
+     *  - `tracking_enabled`: setTrackingEnabled(true).
+     *  - `user_change`: setUserId() o init() con otro userId.
+     *  - `idle_timeout`: la pestaña vuelve a verse tras más de 30 min oculta.
+     *  - `bfcache_restore`: vuelta desde la bfcache fuera de la ventana de reanudación.
+     * Si hay una sesión suspendida a tiempo emite `deepdots_session_resume` en su lugar, sin reason.
      */
     private openSession;
     /** Web: si la pestaña se ve. Sin `document` (RN) manda AppState vía onForeground/onBackground. */
@@ -905,7 +929,20 @@ declare class DeepdotsPopups {
         final?: boolean;
         sessionEnd?: boolean;
     }): void;
-    /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
+    /**
+     * Emite un evento `user_engagement` con el tiempo activo acumulado (#8) y la pantalla en
+     * curso: `screen` y `path` (los mismos que llevará su `page_view`) y `screen_seconds` (lo
+     * que lleva en ella, medido como el `duration_seconds` del `page_view`).
+     *
+     * El `page_view` sale al SALIR de la pantalla; si el cierre no llega nunca (pestaña dormida
+     * y descartada al volver, pestaña o app matada en segundo plano), la última pantalla de la
+     * sesión se perdía y una visita de una sola pantalla se quedaba sin ninguna. Con la pantalla
+     * en el latido y en el engagement de ocultar la pestaña, el backend la reconstruye.
+     *
+     * En los cierres (`closeSession`, `suspendSession`) el observador ya emitió el `page_view`
+     * y no tiene pantalla, así que ese engagement va sin `screen`: nunca se cuenta dos veces.
+     * Tampoco se emite un `page_view` aquí, por lo mismo.
+     */
     private flushEngagement;
     /** Tick del flush periódico: latido de engagement si toca, y envío de lo acumulado. */
     private onAnalyticsFlushTick;
@@ -1362,4 +1399,4 @@ declare function collectRnDevice(d: DeviceInfoLike): DeviceInfo;
  */
 declare function setupReactNative(sdk: DeepdotsPopups, config: DeepdotsInitParams, deps?: ReactNativeSetupDeps): () => void;
 
-export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type BuildBodyOptions, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type CrashRecord, CrashReporter, type CrashSeverity, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, type DeepdotsInitParams, type DeepdotsLogger, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type DeviceSnapshot, type EventListener, type FeedbackKV, type FeedbackSession, InMemoryStorage, type KeyValueStorage, LABELS, MAX_TRACKED_MESSAGES, MESSAGE_CHANNELS, type MessageChannel, MessageGuard, type MessageGuardVerdict, type MessageRejectionReason, type MessageStage, type MmkvLike, NATIVE_READY_GRACE_MS, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupLabels, type PopupLocale, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, REVEAL_TIMEOUT_MS, RTL_LOCALES, type ReactNativeErrorUtils, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type ReportErrorOptions, type ResolvedActionLabels, SUPPORTED_LANGUAGES, type SessionEndReason, type TrackMessageOptions, type TriggerConfig, buildAnalyticsFeedbackBody, buildMessageParams, buildSurveyHtml, collectRnDevice, crashRecordToParams, createDefaultRenderer, createFeedbackSink, directionFor, getLabels, isRtlLanguage, mmkvStorage, resolveActionLabels, resolveLocale, setupReactNative };
+export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type BuildBodyOptions, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type CrashRecord, CrashReporter, type CrashSeverity, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, type DeepdotsInitParams, type DeepdotsLogger, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type DeviceSnapshot, type EventListener, type FeedbackKV, type FeedbackSession, InMemoryStorage, type KeyValueStorage, LABELS, MAX_TRACKED_MESSAGES, MESSAGE_CHANNELS, type MessageChannel, MessageGuard, type MessageGuardVerdict, type MessageRejectionReason, type MessageStage, type MmkvLike, NATIVE_READY_GRACE_MS, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupLabels, type PopupLocale, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, REVEAL_TIMEOUT_MS, RTL_LOCALES, type ReactNativeErrorUtils, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type ReportErrorOptions, type ResolvedActionLabels, SUPPORTED_LANGUAGES, type SessionEndReason, type SessionStartReason, type TrackMessageOptions, type TriggerConfig, buildAnalyticsFeedbackBody, buildMessageParams, buildSurveyHtml, collectRnDevice, crashRecordToParams, createDefaultRenderer, createFeedbackSink, directionFor, getLabels, isRtlLanguage, mmkvStorage, resolveActionLabels, resolveLocale, setupReactNative };

package/dist/index.d.ts

@@ -383,6 +383,23 @@ type EventListener = (event: DeepdotsEvent) => void;
  *    anterior se cierra y se abre otra, como hace GA con su timeout de sesión.
  */
 type SessionEndReason = 'page_hide' | 'background' | 'user_change' | 'tracking_disabled' | 'manual' | 'idle_timeout';
+/**
+ * Motivo del `deepdots_session_start` (param `reason`): por qué EMPIEZA la sesión. Permite a
+ * analytics separar una carga/arranque real de una vuelta desde background ("Started here").
+ * Mismos valores que el SDK nativo donde el significado coincide:
+ *  - `cold_start`: `init()` (carga de la página / arranque de la app RN) sin sesión suspendida
+ *    que reanudar. Una recarga en menos de 1 min no emite `session_start` sino
+ *    `deepdots_session_resume`.
+ *  - `foreground`: `onForeground()` (RN, AppState 'active') tras un cierre (`onBackground()`
+ *    o `endSession()`). Con la sesión abierta no emite nada.
+ *  - `tracking_enabled`: `setTrackingEnabled(true)` (consentimiento concedido).
+ *  - `user_change`: `setUserId()` o un `init()` con otro `userId`, tras cerrar la del anterior.
+ *  - `idle_timeout`: la pestaña vuelve a verse tras más de 30 min oculta (web): la sesión
+ *    anterior se cerró (o se descartó) y empieza otra.
+ *  - `bfcache_restore`: la página vuelve de la bfcache (botón atrás, `pageshow` con
+ *    `persisted`) fuera de la ventana de reanudación (web).
+ */
+type SessionStartReason = 'cold_start' | 'foreground' | 'tracking_enabled' | 'user_change' | 'idle_timeout' | 'bfcache_restore';
 /** Trigger type used by remote popup definitions */
 type PopupTriggerType = 'time_on_page' | 'scroll' | 'exit' | 'click' | 'event';
 type PopupTriggerConditionStatus = 'SHOWED' | 'PARTIAL' | 'COMPLETED';
@@ -888,8 +905,15 @@ declare class DeepdotsPopups {
      */
     private closeSession;
     /**
-     * Abre sesión (`session_start`) si no hay una abierta y el tracking está activo. Idempotente:
-     * se llama en init(), al volver a foreground y al conceder el consentimiento.
+     * Abre sesión (`session_start`) si no hay una abierta y el tracking está activo. Idempotente.
+     * El `reason` dice por qué empieza (ver `SessionStartReason`):
+     *  - `cold_start`: init() (carga de la página / arranque de la app RN).
+     *  - `foreground`: onForeground() tras un cierre (RN).
+     *  - `tracking_enabled`: setTrackingEnabled(true).
+     *  - `user_change`: setUserId() o init() con otro userId.
+     *  - `idle_timeout`: la pestaña vuelve a verse tras más de 30 min oculta.
+     *  - `bfcache_restore`: vuelta desde la bfcache fuera de la ventana de reanudación.
+     * Si hay una sesión suspendida a tiempo emite `deepdots_session_resume` en su lugar, sin reason.
      */
     private openSession;
     /** Web: si la pestaña se ve. Sin `document` (RN) manda AppState vía onForeground/onBackground. */
@@ -905,7 +929,20 @@ declare class DeepdotsPopups {
         final?: boolean;
         sessionEnd?: boolean;
     }): void;
-    /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
+    /**
+     * Emite un evento `user_engagement` con el tiempo activo acumulado (#8) y la pantalla en
+     * curso: `screen` y `path` (los mismos que llevará su `page_view`) y `screen_seconds` (lo
+     * que lleva en ella, medido como el `duration_seconds` del `page_view`).
+     *
+     * El `page_view` sale al SALIR de la pantalla; si el cierre no llega nunca (pestaña dormida
+     * y descartada al volver, pestaña o app matada en segundo plano), la última pantalla de la
+     * sesión se perdía y una visita de una sola pantalla se quedaba sin ninguna. Con la pantalla
+     * en el latido y en el engagement de ocultar la pestaña, el backend la reconstruye.
+     *
+     * En los cierres (`closeSession`, `suspendSession`) el observador ya emitió el `page_view`
+     * y no tiene pantalla, así que ese engagement va sin `screen`: nunca se cuenta dos veces.
+     * Tampoco se emite un `page_view` aquí, por lo mismo.
+     */
     private flushEngagement;
     /** Tick del flush periódico: latido de engagement si toca, y envío de lo acumulado. */
     private onAnalyticsFlushTick;
@@ -1362,4 +1399,4 @@ declare function collectRnDevice(d: DeviceInfoLike): DeviceInfo;
  */
 declare function setupReactNative(sdk: DeepdotsPopups, config: DeepdotsInitParams, deps?: ReactNativeSetupDeps): () => void;
 
-export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type BuildBodyOptions, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type CrashRecord, CrashReporter, type CrashSeverity, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, type DeepdotsInitParams, type DeepdotsLogger, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type DeviceSnapshot, type EventListener, type FeedbackKV, type FeedbackSession, InMemoryStorage, type KeyValueStorage, LABELS, MAX_TRACKED_MESSAGES, MESSAGE_CHANNELS, type MessageChannel, MessageGuard, type MessageGuardVerdict, type MessageRejectionReason, type MessageStage, type MmkvLike, NATIVE_READY_GRACE_MS, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupLabels, type PopupLocale, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, REVEAL_TIMEOUT_MS, RTL_LOCALES, type ReactNativeErrorUtils, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type ReportErrorOptions, type ResolvedActionLabels, SUPPORTED_LANGUAGES, type SessionEndReason, type TrackMessageOptions, type TriggerConfig, buildAnalyticsFeedbackBody, buildMessageParams, buildSurveyHtml, collectRnDevice, crashRecordToParams, createDefaultRenderer, createFeedbackSink, directionFor, getLabels, isRtlLanguage, mmkvStorage, resolveActionLabels, resolveLocale, setupReactNative };
+export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type BuildBodyOptions, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type CrashRecord, CrashReporter, type CrashSeverity, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, type DeepdotsInitParams, type DeepdotsLogger, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type DeviceSnapshot, type EventListener, type FeedbackKV, type FeedbackSession, InMemoryStorage, type KeyValueStorage, LABELS, MAX_TRACKED_MESSAGES, MESSAGE_CHANNELS, type MessageChannel, MessageGuard, type MessageGuardVerdict, type MessageRejectionReason, type MessageStage, type MmkvLike, NATIVE_READY_GRACE_MS, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupLabels, type PopupLocale, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, REVEAL_TIMEOUT_MS, RTL_LOCALES, type ReactNativeErrorUtils, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type ReportErrorOptions, type ResolvedActionLabels, SUPPORTED_LANGUAGES, type SessionEndReason, type SessionStartReason, type TrackMessageOptions, type TriggerConfig, buildAnalyticsFeedbackBody, buildMessageParams, buildSurveyHtml, collectRnDevice, crashRecordToParams, createDefaultRenderer, createFeedbackSink, directionFor, getLabels, isRtlLanguage, mmkvStorage, resolveActionLabels, resolveLocale, setupReactNative };

package/dist/index.js

@@ -7739,6 +7739,23 @@ var NavigationObserver = class {
     if (!this.installed || this.currentScreen != null || typeof window === "undefined") return;
     this.begin(window.location.href);
   }
+  /**
+   * La pantalla en curso, sin cerrarla ni emitir nada; null si no hay (antes de `begin`, tras
+   * `stop`/`discard`). Para que el `user_engagement` lleve la pantalla: si el cierre de la
+   * sesión no llega nunca (pestaña dormida y descartada, app matada), la última pantalla no
+   * tiene `page_view` y solo queda esto.
+   */
+  current() {
+    if (this.currentScreen == null) return null;
+    return {
+      screen: this.currentScreen,
+      path: this.currentPath ?? this.currentScreen,
+      seconds: this.secondsSinceEntry(this.now())
+    };
+  }
+  secondsSinceEntry(at) {
+    return Math.max(0, Math.round((at - this.entryAt) / 1e3));
+  }
   closeCurrent() {
     if (this.currentScreen == null) return;
     const exit = this.now();
@@ -7747,7 +7764,7 @@ var NavigationObserver = class {
       path: this.currentPath ?? this.currentScreen,
       entry: this.entryAt,
       exit,
-      durationSeconds: Math.max(0, Math.round((exit - this.entryAt) / 1e3))
+      durationSeconds: this.secondsSinceEntry(exit)
     };
     this.listeners.forEach((l) => {
       try {
@@ -8472,7 +8489,7 @@ var DeepdotsPopups = class {
     this.navObserver.install();
     this.engagement = new EngagementTracker();
     this.setupAnalyticsFlush();
-    this.openSession();
+    this.openSession("cold_start");
     if (resumable && this.analyticsFeedbackSessionId === resumable.sessionId) {
       this.notifyFeedbackSession(resumable.sessionId, "open");
     }
@@ -8530,7 +8547,7 @@ var DeepdotsPopups = class {
   setTrackingEnabled(enabled) {
     if (!enabled) this.closeSession("tracking_disabled");
     this.tracking?.setTrackingEnabled(enabled);
-    if (enabled) this.openSession();
+    if (enabled) this.openSession("tracking_enabled");
     if (enabled) this.resolveGeo();
     this.log("tracking \xB7 setTrackingEnabled:", enabled, "\xB7 session_id:", this.tracking?.getSessionId() ?? null);
   }
@@ -8647,7 +8664,7 @@ var DeepdotsPopups = class {
   /** App a foreground (RN: AppState 'active'): reanuda el engagement time y abre sesión nueva. */
   onForeground() {
     this.engagement?.resume();
-    this.openSession();
+    this.openSession("foreground");
   }
   /**
    * App a background (RN: AppState 'background'): FIN DE SESIÓN. Cierra pantalla actual
@@ -8695,7 +8712,7 @@ var DeepdotsPopups = class {
     this.answeredSurveys.clear();
     clearPopupState(storage);
     this.log("tracking \xB7 user_change \xB7 user_id:", this.tracking.getUserId());
-    this.openSession();
+    this.openSession("user_change");
   }
   /**
    * Cierra la sesión actual: vuelca todo lo que quedaba abierto y envía el último lote
@@ -8721,17 +8738,24 @@ var DeepdotsPopups = class {
     this.log("tracking \xB7 session_end:", reason);
   }
   /**
-   * Abre sesión (`session_start`) si no hay una abierta y el tracking está activo. Idempotente:
-   * se llama en init(), al volver a foreground y al conceder el consentimiento.
+   * Abre sesión (`session_start`) si no hay una abierta y el tracking está activo. Idempotente.
+   * El `reason` dice por qué empieza (ver `SessionStartReason`):
+   *  - `cold_start`: init() (carga de la página / arranque de la app RN).
+   *  - `foreground`: onForeground() tras un cierre (RN).
+   *  - `tracking_enabled`: setTrackingEnabled(true).
+   *  - `user_change`: setUserId() o init() con otro userId.
+   *  - `idle_timeout`: la pestaña vuelve a verse tras más de 30 min oculta.
+   *  - `bfcache_restore`: vuelta desde la bfcache fuera de la ventana de reanudación.
+   * Si hay una sesión suspendida a tiempo emite `deepdots_session_resume` en su lugar, sin reason.
    */
-  openSession() {
+  openSession(reason) {
     if (this.sessionOpen) return;
     if (!this.tracking?.isTrackingEnabled()) return;
     const suspendedMs = this.takeSuspendedSession();
     this.sessionOpen = true;
     this.lastEngagementAt = Date.now();
     if (suspendedMs === null) {
-      this.track("deepdots_session_start", {});
+      this.track("deepdots_session_start", { reason });
     } else {
       this.track("deepdots_session_resume", { suspended_ms: suspendedMs });
       this.log("tracking \xB7 session resumed after", suspendedMs, "ms:", this.analyticsFeedbackSessionId);
@@ -8761,12 +8785,29 @@ var DeepdotsPopups = class {
     if (!this.tracking?.isTrackingEnabled()) return;
     this.analytics?.flush(this.analyticsIdentity(), options);
   }
-  /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
+  /**
+   * Emite un evento `user_engagement` con el tiempo activo acumulado (#8) y la pantalla en
+   * curso: `screen` y `path` (los mismos que llevará su `page_view`) y `screen_seconds` (lo
+   * que lleva en ella, medido como el `duration_seconds` del `page_view`).
+   *
+   * El `page_view` sale al SALIR de la pantalla; si el cierre no llega nunca (pestaña dormida
+   * y descartada al volver, pestaña o app matada en segundo plano), la última pantalla de la
+   * sesión se perdía y una visita de una sola pantalla se quedaba sin ninguna. Con la pantalla
+   * en el latido y en el engagement de ocultar la pestaña, el backend la reconstruye.
+   *
+   * En los cierres (`closeSession`, `suspendSession`) el observador ya emitió el `page_view`
+   * y no tiene pantalla, así que ese engagement va sin `screen`: nunca se cuenta dos veces.
+   * Tampoco se emite un `page_view` aquí, por lo mismo.
+   */
   flushEngagement() {
     if (!this.tracking?.isTrackingEnabled()) return;
     const ms = this.engagement?.consume() ?? 0;
     if (ms > 0) {
-      this.track("deepdots_user_engagement", { engagement_time_msec: ms });
+      const current = this.navObserver?.current();
+      this.track("deepdots_user_engagement", {
+        engagement_time_msec: ms,
+        ...current ? { screen: current.screen, path: current.path, screen_seconds: current.seconds } : {}
+      });
       this.lastEngagementAt = Date.now();
     }
   }
@@ -8798,7 +8839,7 @@ var DeepdotsPopups = class {
     } else {
       this.discardSession();
     }
-    this.openSession();
+    this.openSession("idle_timeout");
   }
   /**
    * `pagehide` en web: SUSPENDE la sesión en vez de cerrarla, porque el navegador lo lanza
@@ -8922,7 +8963,7 @@ var DeepdotsPopups = class {
     window.addEventListener("pageshow", (event) => {
       if (!event.persisted) return;
       this.startAnalyticsFlushTimer();
-      this.openSession();
+      this.openSession("bfcache_restore");
     });
     document.addEventListener("visibilitychange", () => {
       if (document.visibilityState === "hidden") {