@magicfeedback/popup-sdk 1.8.2 → 1.8.4

package/README.md

@@ -121,7 +121,13 @@ Config fields:
 - `logger?: DeepdotsLogger` — replaces `console` for SDK logs
 - `trackingEnabled?: boolean` — starts analytics on (default) or off, for consent flows
 - `analytics?: { publicKey: string; integration: string }` — enables the real analytics
-  delivery. Without it the analytics channel stays in dry-run and only logs the payload.
+  delivery. Without it the analytics channel stays in dry-run: nothing is sent, and the
+  payload is only logged when `debug` is on.
+- `geolocation?: boolean` — IP geolocation (country/city) for analytics, default `true`. It
+  calls third-party services (`ipapi.co`, then `ipwho.is`, then `ipinfo.io` as fallbacks, 3 s
+  timeout each, stopping at the first answer). It only runs when `analytics` is set, tracking
+  is enabled and the 30-day cache is missing or expired, at most once per SDK instance. Pass
+  `false` to never call those services nor attach country/city.
 - `appVersion?: string` — reported in the analytics device context
 - `storage?: KeyValueStorage` — persistence override (React Native uses MMKV; the browser
   defaults to `localStorage`)
@@ -268,7 +274,7 @@ session start/end and unhandled errors are automatic. The rest is instrumented b
 | `trackFunnelStep(funnel, step, taskId, params?)` | A funnel step, correlated by `taskId` |
 | `trackFindabilityFriction(topic, params?)` | Friction signal |
 | `trackMeaningfulInteraction(interactionType, params?)` | A meaningful interaction, grouped by `interaction_type` |
-| `enterMiniService(name, entryPointType?)` / `exitMiniService(name)` | Mini-service, with duration |
+| `enterMiniService(name, entryPointType?)` / `exitMiniService(name)` | A task flow with a start and an end — [not a page](#mini-services--enterminiservicename-entrypointtype--exitminiservicename) |
 | `setUserAttributes(map)` / `setMetric(key, value)` | Breakdown dimensions / measurable values |
 | `setUserId(userId?)` | Login, logout or account switch |
 | `endSession()` | Closes the session explicitly |
@@ -332,6 +338,32 @@ values (oldest evicted first). A rejected event does not consume state: after a
 > restricted permissions, will not fire it — so a client-side `delivered` count sits below the
 > real one. For a reliable denominator, take `delivered` from your sending provider.
 
+### Mini-services — `enterMiniService(name, entryPointType?)` / `exitMiniService(name)`
+
+A mini-service is a **self-contained task inside the app, with a start and an end**: a booking,
+a checkout, an onboarding, a form the user fills in. Deepdots treats it as a flow. It reports
+completion and drop-off per mini-service, draws it in the session journey as a lane between
+where it was entered and where it was left, and tags every event emitted while it is active
+with `mini_service`.
+
+```ts
+popups.enterMiniService('checkout', 'cart_button'); // the user starts the task
+// ...
+popups.exitMiniService('checkout');                 // and finishes it
+```
+
+- Enter it when the task starts and exit it when the task is done. One still open when the
+  session closes is exited by the SDK.
+- `entryPointType` is optional and says where the user started it from (a banner, a menu, a
+  deep link). It is sent as `entry_point_type`.
+
+**A mini-service is not a page, a section or an area of the app.** Navigation is already
+recorded as `page_view`, with the screen and how long the user stayed on it, and time per area
+comes from grouping those page views by screen. Opening a mini-service for every section turns
+each navigation into an abandoned flow: a move from `/feedback` to `/explorer` reads as
+*"entered the explorer mini-service and never completed it"*, the journey loses the edge
+between the two pages, and every section counts as drop-off.
+
 ## Supported Trigger Types
 
 Popup definitions use these trigger types:

package/dist/index.d.mts

@@ -105,6 +105,12 @@ interface AnalyticsFlushMeta {
      * el `sessionId`, para que el lote siguiente abra un registro nuevo.
      */
     sessionEnd?: boolean;
+    /**
+     * `true` para olvidar la sesión SIN enviar nada (el payload llega vacío): el backend ya la
+     * cerró por inactividad. El sink descarta su `sessionId` para que el lote siguiente abra un
+     * registro nuevo, igual que tras `sessionEnd`, pero sin POST.
+     */
+    resetSession?: boolean;
 }
 /**
  * Envío del lote. Si devuelve una promesa que **rechaza**, el manager re-encola los
@@ -251,9 +257,17 @@ interface DeepdotsInitParams {
     device?: DeviceInfo;
     /**
      * Analytics channel keys (`POST /sdk/feedback`). If provided, analytics is SENT
-     * to the configured integration; if missing, it stays in dry-run mode (console.log only).
+     * to the configured integration; if missing, it stays in dry-run mode: nothing is sent, and the payload is only
+     * logged when `debug` is true.
      */
     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
@@ -330,8 +344,10 @@ type EventListener = (event: DeepdotsEvent) => void;
  *  - `user_change`: `setUserId()` o un `init()` con otro `userId` (login/logout del host).
  *  - `tracking_disabled`: `setTrackingEnabled(false)` (consentimiento revocado).
  *  - `manual`: `endSession()` llamado por el host.
+ *  - `idle_timeout`: la pestaña vuelve a verse tras más de 30 min oculta (web). La sesión
+ *    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';
+type SessionEndReason = 'page_hide' | 'background' | 'user_change' | 'tracking_disabled' | 'manual' | 'idle_timeout';
 /** Trigger type used by remote popup definitions */
 type PopupTriggerType = 'time_on_page' | 'scroll' | 'exit' | 'click' | 'event';
 type PopupTriggerConditionStatus = 'SHOWED' | 'PARTIAL' | 'COMPLETED';
@@ -704,11 +720,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. */
@@ -820,6 +846,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/index.d.ts

@@ -105,6 +105,12 @@ interface AnalyticsFlushMeta {
      * el `sessionId`, para que el lote siguiente abra un registro nuevo.
      */
     sessionEnd?: boolean;
+    /**
+     * `true` para olvidar la sesión SIN enviar nada (el payload llega vacío): el backend ya la
+     * cerró por inactividad. El sink descarta su `sessionId` para que el lote siguiente abra un
+     * registro nuevo, igual que tras `sessionEnd`, pero sin POST.
+     */
+    resetSession?: boolean;
 }
 /**
  * Envío del lote. Si devuelve una promesa que **rechaza**, el manager re-encola los
@@ -251,9 +257,17 @@ interface DeepdotsInitParams {
     device?: DeviceInfo;
     /**
      * Analytics channel keys (`POST /sdk/feedback`). If provided, analytics is SENT
-     * to the configured integration; if missing, it stays in dry-run mode (console.log only).
+     * to the configured integration; if missing, it stays in dry-run mode: nothing is sent, and the payload is only
+     * logged when `debug` is true.
      */
     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
@@ -330,8 +344,10 @@ type EventListener = (event: DeepdotsEvent) => void;
  *  - `user_change`: `setUserId()` o un `init()` con otro `userId` (login/logout del host).
  *  - `tracking_disabled`: `setTrackingEnabled(false)` (consentimiento revocado).
  *  - `manual`: `endSession()` llamado por el host.
+ *  - `idle_timeout`: la pestaña vuelve a verse tras más de 30 min oculta (web). La sesión
+ *    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';
+type SessionEndReason = 'page_hide' | 'background' | 'user_change' | 'tracking_disabled' | 'manual' | 'idle_timeout';
 /** Trigger type used by remote popup definitions */
 type PopupTriggerType = 'time_on_page' | 'scroll' | 'exit' | 'click' | 'event';
 type PopupTriggerConditionStatus = 'SHOWED' | 'PARTIAL' | 'COMPLETED';
@@ -704,11 +720,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. */
@@ -820,6 +846,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/index.js

@@ -2454,9 +2454,9 @@ var init_logo = __esm({
   }
 });
 
-// ../../../../../../../Users/sarias/developer/Deepdots/deepdots-popup-sdk/node_modules/@magicfeedback/native/dist/magicfeedback-sdk.browser.js
+// node_modules/@magicfeedback/native/dist/magicfeedback-sdk.browser.js
 var require_magicfeedback_sdk_browser = __commonJS({
-  "../../../../../../../Users/sarias/developer/Deepdots/deepdots-popup-sdk/node_modules/@magicfeedback/native/dist/magicfeedback-sdk.browser.js"(exports, module2) {
+  "node_modules/@magicfeedback/native/dist/magicfeedback-sdk.browser.js"(exports, module2) {
     "use strict";
     !(function(e, t) {
       "object" == typeof exports && "object" == typeof module2 ? module2.exports = t() : "function" == typeof define && define.amd ? define([], t) : "object" == typeof exports ? exports.magicfeedback = t() : e.magicfeedback = t();
@@ -6564,10 +6564,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 {
@@ -6634,6 +6637,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
@@ -6843,6 +6859,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) {
@@ -6909,6 +6931,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ó
@@ -7442,6 +7472,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 {
@@ -7505,11 +7539,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) {
@@ -7567,7 +7611,9 @@ var DeepdotsPopups = class {
       onSessionReset: () => {
         this.analyticsFeedbackSessionId = void 0;
       }
-    }) : createDryRunSink((...a) => this.logger.log(...a));
+    }) : createDryRunSink((...a) => {
+      if (this.config?.debug) this.logger.log(...a);
+    });
     const device = config.device ?? collectDeviceInfo(config.appVersion);
     this.language = resolveLanguage({
       explicit: config.language,
@@ -7595,15 +7641,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();
@@ -7645,6 +7685,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) ─────────
@@ -7841,6 +7882,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();
@@ -7871,7 +7913,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 {
@@ -7881,8 +7992,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");
@@ -7897,14 +8008,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() {