@magicfeedback/popup-sdk 1.8.2 → 1.8.3

package/dist/react-native.d.mts

@@ -156,6 +156,13 @@ interface DeepdotsInitParams {
      * to the configured integration; if missing, it stays in dry-run mode (console.log only).
      */
     analytics?: AnalyticsKeys;
+    /**
+     * IP geolocation (country/city) added to analytics. Default `true`. The lookup calls
+     * third-party services (ipapi.co, then ipwho.is, then ipinfo.io as fallbacks, 3 s timeout
+     * each) and only runs when `analytics` is configured, tracking is enabled and the 30-day
+     * cache is missing or expired. Set `false` to never call them nor attach country/city.
+     */
+    geolocation?: boolean;
     /**
      * Internal user attributes known only by the host (language, age, plan, ...), sent
      * to the backend Contact for segmentation/targeting. Requires `userId`. Equivalent to calling
@@ -406,11 +413,21 @@ declare class DeepdotsPopups {
      * nueva al volver a foreground o al conceder el consentimiento más tarde.
      */
     private sessionOpen;
+    /** Último `user_engagement` emitido (ms epoch): marca el latido. */
+    private lastEngagementAt;
+    /** Cuándo se ocultó la pestaña por última vez (ms epoch); null si está visible. */
+    private hiddenAt;
     /**
      * Idioma resuelto en init() (explícito > navigator.language > Intl). Única fuente de
      * verdad para el context de analytics Y para la segmentación por idioma de los popups.
      */
     private language;
+    /** `geolocation` del init: si es false no se usa ni la caché ni el lookup. */
+    private geoEnabled;
+    /** Solo se consulta a terceros si el país/ciudad se va a enviar (analytics configurado). */
+    private geoWanted;
+    /** Evita más de un lookup por instancia (el consentimiento puede ir y venir). */
+    private geoLookupStarted;
     /** Initialize the SDK with configuration */
     init(config: DeepdotsInitParams): void;
     /** User id actual (generado por el SDK o provisto por el cliente). Null si tracking off. */
@@ -522,6 +539,26 @@ declare class DeepdotsPopups {
     }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
+    /** Tick del flush periódico: latido de engagement si toca, y envío de lo acumulado. */
+    private onAnalyticsFlushTick;
+    /**
+     * La pestaña vuelve a verse. Tras más de ANALYTICS_SESSION_TIMEOUT_MS oculta, la sesión
+     * anterior termina y empieza otra: seguir con el mismo sessionId mezclaba dos visitas y,
+     * si el backend ya la había cerrado por inactividad, la partía en dos feedbacks.
+     *  - Oculta menos de ANALYTICS_SESSION_DISCARD_MS: el backend aún la tiene abierta → se
+     *    cierra con normalidad (page_view de la pantalla, session_end `idle_timeout`, completed).
+     *  - Más: ya la cerró el backend → se descarta sin enviar nada.
+     */
+    private onDocumentVisible;
+    /** Olvida la sesión abierta sin enviar nada (ver onDocumentVisible). */
+    private discardSession;
+    /**
+     * Geolocalización por IP (país/ciudad para analytics). La caché persistente es local y se
+     * aplica siempre que `geolocation` no esté desactivado. El lookup a terceros (ipapi.co →
+     * ipwho.is → ipinfo.io, fallback con timeout) solo se hace si el dato se va a ENVIAR:
+     * analytics configurado + tracking activo + caché ausente o caducada. Una vez por instancia.
+     */
+    private resolveGeo;
     private analyticsIdentity;
     /** Flush automático al ocultar/cerrar la página (no perder el lote pendiente). */
     private setupAnalyticsFlush;

package/dist/react-native.d.ts

@@ -156,6 +156,13 @@ interface DeepdotsInitParams {
      * to the configured integration; if missing, it stays in dry-run mode (console.log only).
      */
     analytics?: AnalyticsKeys;
+    /**
+     * IP geolocation (country/city) added to analytics. Default `true`. The lookup calls
+     * third-party services (ipapi.co, then ipwho.is, then ipinfo.io as fallbacks, 3 s timeout
+     * each) and only runs when `analytics` is configured, tracking is enabled and the 30-day
+     * cache is missing or expired. Set `false` to never call them nor attach country/city.
+     */
+    geolocation?: boolean;
     /**
      * Internal user attributes known only by the host (language, age, plan, ...), sent
      * to the backend Contact for segmentation/targeting. Requires `userId`. Equivalent to calling
@@ -406,11 +413,21 @@ declare class DeepdotsPopups {
      * nueva al volver a foreground o al conceder el consentimiento más tarde.
      */
     private sessionOpen;
+    /** Último `user_engagement` emitido (ms epoch): marca el latido. */
+    private lastEngagementAt;
+    /** Cuándo se ocultó la pestaña por última vez (ms epoch); null si está visible. */
+    private hiddenAt;
     /**
      * Idioma resuelto en init() (explícito > navigator.language > Intl). Única fuente de
      * verdad para el context de analytics Y para la segmentación por idioma de los popups.
      */
     private language;
+    /** `geolocation` del init: si es false no se usa ni la caché ni el lookup. */
+    private geoEnabled;
+    /** Solo se consulta a terceros si el país/ciudad se va a enviar (analytics configurado). */
+    private geoWanted;
+    /** Evita más de un lookup por instancia (el consentimiento puede ir y venir). */
+    private geoLookupStarted;
     /** Initialize the SDK with configuration */
     init(config: DeepdotsInitParams): void;
     /** User id actual (generado por el SDK o provisto por el cliente). Null si tracking off. */
@@ -522,6 +539,26 @@ declare class DeepdotsPopups {
     }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
+    /** Tick del flush periódico: latido de engagement si toca, y envío de lo acumulado. */
+    private onAnalyticsFlushTick;
+    /**
+     * La pestaña vuelve a verse. Tras más de ANALYTICS_SESSION_TIMEOUT_MS oculta, la sesión
+     * anterior termina y empieza otra: seguir con el mismo sessionId mezclaba dos visitas y,
+     * si el backend ya la había cerrado por inactividad, la partía en dos feedbacks.
+     *  - Oculta menos de ANALYTICS_SESSION_DISCARD_MS: el backend aún la tiene abierta → se
+     *    cierra con normalidad (page_view de la pantalla, session_end `idle_timeout`, completed).
+     *  - Más: ya la cerró el backend → se descarta sin enviar nada.
+     */
+    private onDocumentVisible;
+    /** Olvida la sesión abierta sin enviar nada (ver onDocumentVisible). */
+    private discardSession;
+    /**
+     * Geolocalización por IP (país/ciudad para analytics). La caché persistente es local y se
+     * aplica siempre que `geolocation` no esté desactivado. El lookup a terceros (ipapi.co →
+     * ipwho.is → ipinfo.io, fallback con timeout) solo se hace si el dato se va a ENVIAR:
+     * analytics configurado + tracking activo + caché ausente o caducada. Una vez por instancia.
+     */
+    private resolveGeo;
     private analyticsIdentity;
     /** Flush automático al ocultar/cerrar la página (no perder el lote pendiente). */
     private setupAnalyticsFlush;

package/dist/react-native.js

@@ -4124,10 +4124,13 @@ init_tracking_manager();
 
 // src/analytics/analytics-manager.ts
 function createDryRunSink(log = console.log) {
-  return (payload) => log(
-    "[DeepdotsAnalytics] (dry-run \xB7 NOT sent \xB7 no init.analytics) POST /sdk/feedback \u2192",
-    JSON.stringify(payload, null, 2)
-  );
+  return (payload, meta) => {
+    if (meta?.resetSession) return;
+    log(
+      "[DeepdotsAnalytics] (dry-run \xB7 NOT sent \xB7 no init.analytics) POST /sdk/feedback \u2192",
+      JSON.stringify(payload, null, 2)
+    );
+  };
 }
 var dryRunSink = createDryRunSink();
 var AnalyticsManager = class {
@@ -4194,6 +4197,19 @@ var AnalyticsManager = class {
       this.exitMiniService(name);
     }
   }
+  /**
+   * Olvida la sesión en curso SIN emitir nada: vacía el buffer y los mini-services activos
+   * (sin `mini_service_exit`). Para una sesión que el backend ya cerró por inactividad: lo
+   * que quedara pendiente pertenecía a ella y no debe llegar con la sesión nueva.
+   */
+  discardSession(identity) {
+    this.events = [];
+    this.activeMiniServices.clear();
+    try {
+      void this.sink({ ...this.buildPayload(identity), events: [] }, { resetSession: true });
+    } catch {
+    }
+  }
   /**
    * Olvida lo que pertenecía al usuario anterior (user attributes + métricas) al cambiar de
    * usuario. NO toca el buffer de eventos: el cierre de sesión ya lo vació con la identidad
@@ -4403,6 +4419,12 @@ function createFeedbackSink(options) {
     }
   };
   return async (envelope, meta) => {
+    if (meta?.resetSession) {
+      feedbackSessionId = void 0;
+      firstPostInFlight = null;
+      options.onSessionReset?.();
+      return;
+    }
     const final = meta?.final === true;
     const sessionEnd = meta?.sessionEnd === true;
     if (!feedbackSessionId && firstPostInFlight && !final) {
@@ -4469,6 +4491,14 @@ var NavigationObserver = class {
     this.closeCurrent();
     this.currentScreen = null;
   }
+  /**
+   * Olvida la pantalla actual SIN emitir su visita. Para una sesión que el backend ya dio
+   * por cerrada: su visita no tiene dónde ir, y mandarla con la sesión nueva la contaría
+   * donde no ocurrió. Después, `restart()` vuelve a empezar en la pantalla actual.
+   */
+  discard() {
+    this.currentScreen = null;
+  }
   /**
    * Retoma el seguimiento en la pantalla actual tras un `stop()`, cuando se abre una sesión
    * nueva sin navegar (cambio de usuario, vuelta de la bfcache). No-op si nunca se instaló
@@ -5002,6 +5032,10 @@ var EXIT_QUEUE_STORAGE_KEY = "__deepdots_exit_popup_queue__";
 var DAY_IN_MS = 24 * 60 * 60 * 1e3;
 var ANALYTICS_MAX_BATCH_SIZE = 20;
 var ANALYTICS_FLUSH_INTERVAL_MS = 3e4;
+var ANALYTICS_HEARTBEAT_MS = 5 * 6e4;
+var ANALYTICS_SESSION_TIMEOUT_MS = 30 * 6e4;
+var ANALYTICS_SERVER_IDLE_MS = 60 * 6e4;
+var ANALYTICS_SESSION_DISCARD_MS = ANALYTICS_SERVER_IDLE_MS - 10 * 6e4;
 var RESERVED_EVENT_PREFIX = "deepdots_";
 var CUSTOM_EVENT_PREFIX = "deepdots_event_";
 var DeepdotsPopups = class {
@@ -5065,11 +5099,21 @@ var DeepdotsPopups = class {
      * nueva al volver a foreground o al conceder el consentimiento más tarde.
      */
     this.sessionOpen = false;
+    /** Último `user_engagement` emitido (ms epoch): marca el latido. */
+    this.lastEngagementAt = 0;
+    /** Cuándo se ocultó la pestaña por última vez (ms epoch); null si está visible. */
+    this.hiddenAt = null;
     /**
      * Idioma resuelto en init() (explícito > navigator.language > Intl). Única fuente de
      * verdad para el context de analytics Y para la segmentación por idioma de los popups.
      */
     this.language = void 0;
+    /** `geolocation` del init: si es false no se usa ni la caché ni el lookup. */
+    this.geoEnabled = true;
+    /** Solo se consulta a terceros si el país/ciudad se va a enviar (analytics configurado). */
+    this.geoWanted = false;
+    /** Evita más de un lookup por instancia (el consentimiento puede ir y venir). */
+    this.geoLookupStarted = false;
   }
   /** Initialize the SDK with configuration */
   init(config) {
@@ -5155,15 +5199,9 @@ var DeepdotsPopups = class {
     if (this.tracking?.isTrackingEnabled()) {
       this.crashReporter.install();
     }
-    const cachedGeo = readCachedGeo(storage, Date.now());
-    if (cachedGeo) this.analytics.updateDevice(cachedGeo);
-    fetchGeo().then((geo) => {
-      if (geo) {
-        this.analytics?.updateDevice(geo);
-        writeCachedGeo(storage, geo, Date.now());
-      }
-    }).catch(() => {
-    });
+    this.geoEnabled = config.geolocation ?? true;
+    this.geoWanted = this.geoEnabled && !!config.analytics;
+    this.resolveGeo();
     this.navObserver = new NavigationObserver();
     this.navObserver.onVisit((v) => this.track("deepdots_page_view", { screen: v.screen, duration_seconds: v.durationSeconds }));
     this.navObserver.install();
@@ -5205,6 +5243,7 @@ var DeepdotsPopups = class {
     if (!enabled) this.closeSession("tracking_disabled");
     this.tracking?.setTrackingEnabled(enabled);
     if (enabled) this.openSession();
+    if (enabled) this.resolveGeo();
     this.log("tracking \xB7 setTrackingEnabled:", enabled, "\xB7 session_id:", this.tracking?.getSessionId() ?? null);
   }
   // ───────── Analytics (canal separado del feedback, vinculado por user_id) ─────────
@@ -5401,6 +5440,7 @@ var DeepdotsPopups = class {
     if (this.sessionOpen) return;
     if (!this.tracking?.isTrackingEnabled()) return;
     this.sessionOpen = true;
+    this.lastEngagementAt = Date.now();
     this.track("deepdots_session_start", {});
     this.navObserver?.restart();
     if (this.isDocumentVisible()) this.engagement?.resume();
@@ -5431,7 +5471,76 @@ var DeepdotsPopups = class {
   flushEngagement() {
     if (!this.tracking?.isTrackingEnabled()) return;
     const ms = this.engagement?.consume() ?? 0;
-    if (ms > 0) this.track("deepdots_user_engagement", { engagement_time_msec: ms });
+    if (ms > 0) {
+      this.track("deepdots_user_engagement", { engagement_time_msec: ms });
+      this.lastEngagementAt = Date.now();
+    }
+  }
+  /** Tick del flush periódico: latido de engagement si toca, y envío de lo acumulado. */
+  onAnalyticsFlushTick() {
+    if (this.sessionOpen && this.isDocumentVisible() && Date.now() - this.lastEngagementAt >= ANALYTICS_HEARTBEAT_MS) {
+      this.flushEngagement();
+    }
+    this.flushAnalytics();
+  }
+  /**
+   * La pestaña vuelve a verse. Tras más de ANALYTICS_SESSION_TIMEOUT_MS oculta, la sesión
+   * anterior termina y empieza otra: seguir con el mismo sessionId mezclaba dos visitas y,
+   * si el backend ya la había cerrado por inactividad, la partía en dos feedbacks.
+   *  - Oculta menos de ANALYTICS_SESSION_DISCARD_MS: el backend aún la tiene abierta → se
+   *    cierra con normalidad (page_view de la pantalla, session_end `idle_timeout`, completed).
+   *  - Más: ya la cerró el backend → se descarta sin enviar nada.
+   */
+  onDocumentVisible() {
+    const hiddenFor = this.hiddenAt === null ? 0 : Date.now() - this.hiddenAt;
+    this.hiddenAt = null;
+    if (!this.sessionOpen) return;
+    if (hiddenFor < ANALYTICS_SESSION_TIMEOUT_MS) {
+      this.engagement?.resume();
+      return;
+    }
+    if (hiddenFor < ANALYTICS_SESSION_DISCARD_MS) {
+      this.closeSession("idle_timeout");
+    } else {
+      this.discardSession();
+    }
+    this.openSession();
+  }
+  /** Olvida la sesión abierta sin enviar nada (ver onDocumentVisible). */
+  discardSession() {
+    this.sessionOpen = false;
+    this.navObserver?.discard();
+    this.analytics?.discardSession(this.analyticsIdentity());
+    this.engagement?.consume();
+    this.engagement?.pause();
+    this.analyticsFeedbackSessionId = void 0;
+    this.tracking?.setSessionId(null);
+    this.log("tracking \xB7 session discarded after", ANALYTICS_SESSION_DISCARD_MS / 6e4, "min hidden");
+  }
+  /**
+   * Geolocalización por IP (país/ciudad para analytics). La caché persistente es local y se
+   * aplica siempre que `geolocation` no esté desactivado. El lookup a terceros (ipapi.co →
+   * ipwho.is → ipinfo.io, fallback con timeout) solo se hace si el dato se va a ENVIAR:
+   * analytics configurado + tracking activo + caché ausente o caducada. Una vez por instancia.
+   */
+  resolveGeo() {
+    const storage = this.storage;
+    if (!this.geoEnabled || !storage || !this.analytics) return;
+    const cachedGeo = readCachedGeo(storage, Date.now());
+    if (cachedGeo) {
+      this.analytics.updateDevice(cachedGeo);
+      return;
+    }
+    if (!this.geoWanted || this.geoLookupStarted) return;
+    if (!this.tracking?.isTrackingEnabled()) return;
+    this.geoLookupStarted = true;
+    fetchGeo().then((geo) => {
+      if (geo) {
+        this.analytics?.updateDevice(geo);
+        writeCachedGeo(storage, geo, Date.now());
+      }
+    }).catch(() => {
+    });
   }
   analyticsIdentity() {
     return {
@@ -5441,8 +5550,8 @@ var DeepdotsPopups = class {
   }
   /** Flush automático al ocultar/cerrar la página (no perder el lote pendiente). */
   setupAnalyticsFlush() {
-    if (typeof document === "undefined" || typeof window === "undefined") return;
     this.startAnalyticsFlushTimer();
+    if (typeof document === "undefined" || typeof window === "undefined") return;
     window.addEventListener("pagehide", () => {
       clearInterval(this.analyticsFlushTimer);
       this.closeSession("page_hide");
@@ -5457,14 +5566,15 @@ var DeepdotsPopups = class {
         this.flushEngagement();
         this.engagement?.pause();
         this.flushAnalytics();
+        this.hiddenAt = Date.now();
       } else if (document.visibilityState === "visible") {
-        if (this.sessionOpen) this.engagement?.resume();
+        this.onDocumentVisible();
       }
     });
   }
   startAnalyticsFlushTimer() {
     clearInterval(this.analyticsFlushTimer);
-    this.analyticsFlushTimer = setInterval(() => this.flushAnalytics(), ANALYTICS_FLUSH_INTERVAL_MS);
+    this.analyticsFlushTimer = setInterval(() => this.onAnalyticsFlushTick(), ANALYTICS_FLUSH_INTERVAL_MS);
   }
   /** Enable auto-launch functionality with configured triggers */
   autoLaunch() {