@magicfeedback/popup-sdk 1.8.1 → 1.8.3

package/README.md

@@ -122,6 +122,11 @@ Config fields:
 - `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.
+- `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 +273,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 +337,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

@@ -95,7 +95,8 @@ interface AnalyticsEnvelope {
 interface AnalyticsFlushMeta {
     /**
      * `true` cuando el flush ocurre porque la página/app se está cerrando. El sink debe usar
-     * un transporte que sobreviva al unload (sendBeacon) y no puede esperar respuestas.
+     * un transporte que sobreviva al unload (`fetch` con `keepalive`) y no puede esperar
+     * respuestas.
      */
     final?: boolean;
     /**
@@ -104,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
@@ -174,9 +181,11 @@ interface FeedbackSinkOptions {
     /** fetch inyectable (tests / RN). */
     fetchImpl?: typeof fetch;
     /**
-     * `navigator.sendBeacon` inyectable. Solo se usa en el flush final (cierre de página):
-     * sobrevive al unload, a cambio de no poder leer la respuesta. Si no se pasa, el flush
-     * final usa `fetch` con `keepalive`.
+     * @deprecated Se ignora. El flush final salía por `sendBeacon`, que va SIEMPRE con
+     * credenciales; contra la API (`Access-Control-Allow-Origin: *` + `Allow-Credentials:
+     * true`) el preflight fallaba y el lote de cierre, el único con `completed:true`, no
+     * llegaba nunca. Ahora sale por `fetch` con `keepalive`. Se mantiene en el tipo para no
+     * romper a quien lo pase.
      */
     sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
@@ -194,8 +203,9 @@ interface FeedbackSinkOptions {
  * Garantías de entrega:
  *  - mientras no se conozca el `sessionId`, los lotes se **serializan** (esperan la primera
  *    respuesta): dos POSTs a la vez sin `sessionId` crearían dos registros y partirían los datos;
- *  - `keepalive` para que el navegador no cancele el POST al navegar fuera, y `sendBeacon`
- *    en el flush final (cierre de página), donde `fetch` puede morir con el documento;
+ *  - `keepalive` para que el navegador no cancele el POST al navegar fuera ni al cerrar la
+ *    página, también en el flush final (sin `sendBeacon`: ver `sendBeaconImpl`);
+ *  - sin credenciales, que es lo único que pasa el CORS de la API (`Allow-Origin: *`);
  *  - la promesa **rechaza** en fallo transitorio (red, 5xx, 408, 429) para que el
  *    `AnalyticsManager` re-encole el lote; un 4xx se loguea y se descarta.
  */
@@ -250,6 +260,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
@@ -326,8 +343,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';
@@ -700,11 +719,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. */
@@ -801,12 +830,14 @@ declare class DeepdotsPopups {
      * se llama en init(), al volver a foreground y al conceder el consentimiento.
      */
     private openSession;
+    /** Web: si la pestaña se ve. Sin `document` (RN) manda AppState vía onForeground/onBackground. */
+    private isDocumentVisible;
     /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
     previewAnalytics(): AnalyticsEnvelope;
     /**
      * Envía el lote acumulado de analytics y vacía el buffer.
-     * `final: true` (cierre de página/app) cambia el transporte a `sendBeacon`, que sobrevive
-     * al unload; un lote que falle por red o 5xx se re-encola para el siguiente flush.
+     * `final: true` (cierre de página/app): el lote no espera al primer POST en vuelo, porque
+     * el documento se muere; un lote que falle por red o 5xx se re-encola para el siguiente flush.
      */
     flushAnalytics(options?: {
         final?: boolean;
@@ -814,9 +845,30 @@ 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;
+    private startAnalyticsFlushTimer;
     /** Enable auto-launch functionality with configured triggers */
     autoLaunch(): void;
     /** Inicia los triggers configurados */
@@ -896,11 +948,18 @@ declare class DeepdotsPopups {
     private mapPopupTriggerType;
     private markSurveyProgress;
     /**
-     * Rehidrata el estado de redisplay desde el storage. `answeredSurveys` se reconstruye
-     * desde las entradas COMPLETED: es exactamente lo que persiste `markSurveyAnswered`.
+     * Fusiona el estado de redisplay del storage con el de memoria: por cada popup/survey gana
+     * la entrada MÁS RECIENTE. Fusionar y no sustituir es lo que hace convivir a varias
+     * pestañas sobre el mismo `localStorage`: se llama en el `init()`, antes de cada decisión
+     * de mostrar y antes de cada escritura. `answeredSurveys` se reconstruye desde las
+     * entradas COMPLETED: es exactamente lo que persiste `markSurveyAnswered`.
      */
     private loadPopupState;
-    /** Vuelca el estado de redisplay al storage. Sin storage (o bloqueado) degrada a memoria. */
+    /**
+     * Vuelca el estado de redisplay al storage. Sin storage (o bloqueado) degrada a memoria.
+     * Fusiona antes de escribir: escribir solo la foto en memoria borraba lo que otra pestaña
+     * hubiese guardado desde nuestro `init()`.
+     */
     private persistPopupState;
     private isPopupDefinition;
     private isPopupTrigger;

package/dist/index.d.ts

@@ -95,7 +95,8 @@ interface AnalyticsEnvelope {
 interface AnalyticsFlushMeta {
     /**
      * `true` cuando el flush ocurre porque la página/app se está cerrando. El sink debe usar
-     * un transporte que sobreviva al unload (sendBeacon) y no puede esperar respuestas.
+     * un transporte que sobreviva al unload (`fetch` con `keepalive`) y no puede esperar
+     * respuestas.
      */
     final?: boolean;
     /**
@@ -104,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
@@ -174,9 +181,11 @@ interface FeedbackSinkOptions {
     /** fetch inyectable (tests / RN). */
     fetchImpl?: typeof fetch;
     /**
-     * `navigator.sendBeacon` inyectable. Solo se usa en el flush final (cierre de página):
-     * sobrevive al unload, a cambio de no poder leer la respuesta. Si no se pasa, el flush
-     * final usa `fetch` con `keepalive`.
+     * @deprecated Se ignora. El flush final salía por `sendBeacon`, que va SIEMPRE con
+     * credenciales; contra la API (`Access-Control-Allow-Origin: *` + `Allow-Credentials:
+     * true`) el preflight fallaba y el lote de cierre, el único con `completed:true`, no
+     * llegaba nunca. Ahora sale por `fetch` con `keepalive`. Se mantiene en el tipo para no
+     * romper a quien lo pase.
      */
     sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
@@ -194,8 +203,9 @@ interface FeedbackSinkOptions {
  * Garantías de entrega:
  *  - mientras no se conozca el `sessionId`, los lotes se **serializan** (esperan la primera
  *    respuesta): dos POSTs a la vez sin `sessionId` crearían dos registros y partirían los datos;
- *  - `keepalive` para que el navegador no cancele el POST al navegar fuera, y `sendBeacon`
- *    en el flush final (cierre de página), donde `fetch` puede morir con el documento;
+ *  - `keepalive` para que el navegador no cancele el POST al navegar fuera ni al cerrar la
+ *    página, también en el flush final (sin `sendBeacon`: ver `sendBeaconImpl`);
+ *  - sin credenciales, que es lo único que pasa el CORS de la API (`Allow-Origin: *`);
  *  - la promesa **rechaza** en fallo transitorio (red, 5xx, 408, 429) para que el
  *    `AnalyticsManager` re-encole el lote; un 4xx se loguea y se descarta.
  */
@@ -250,6 +260,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
@@ -326,8 +343,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';
@@ -700,11 +719,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. */
@@ -801,12 +830,14 @@ declare class DeepdotsPopups {
      * se llama en init(), al volver a foreground y al conceder el consentimiento.
      */
     private openSession;
+    /** Web: si la pestaña se ve. Sin `document` (RN) manda AppState vía onForeground/onBackground. */
+    private isDocumentVisible;
     /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
     previewAnalytics(): AnalyticsEnvelope;
     /**
      * Envía el lote acumulado de analytics y vacía el buffer.
-     * `final: true` (cierre de página/app) cambia el transporte a `sendBeacon`, que sobrevive
-     * al unload; un lote que falle por red o 5xx se re-encola para el siguiente flush.
+     * `final: true` (cierre de página/app): el lote no espera al primer POST en vuelo, porque
+     * el documento se muere; un lote que falle por red o 5xx se re-encola para el siguiente flush.
      */
     flushAnalytics(options?: {
         final?: boolean;
@@ -814,9 +845,30 @@ 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;
+    private startAnalyticsFlushTimer;
     /** Enable auto-launch functionality with configured triggers */
     autoLaunch(): void;
     /** Inicia los triggers configurados */
@@ -896,11 +948,18 @@ declare class DeepdotsPopups {
     private mapPopupTriggerType;
     private markSurveyProgress;
     /**
-     * Rehidrata el estado de redisplay desde el storage. `answeredSurveys` se reconstruye
-     * desde las entradas COMPLETED: es exactamente lo que persiste `markSurveyAnswered`.
+     * Fusiona el estado de redisplay del storage con el de memoria: por cada popup/survey gana
+     * la entrada MÁS RECIENTE. Fusionar y no sustituir es lo que hace convivir a varias
+     * pestañas sobre el mismo `localStorage`: se llama en el `init()`, antes de cada decisión
+     * de mostrar y antes de cada escritura. `answeredSurveys` se reconstruye desde las
+     * entradas COMPLETED: es exactamente lo que persiste `markSurveyAnswered`.
      */
     private loadPopupState;
-    /** Vuelca el estado de redisplay al storage. Sin storage (o bloqueado) degrada a memoria. */
+    /**
+     * Vuelca el estado de redisplay al storage. Sin storage (o bloqueado) degrada a memoria.
+     * Fusiona antes de escribir: escribir solo la foto en memoria borraba lo que otra pestaña
+     * hubiese guardado desde nuestro `init()`.
+     */
     private persistPopupState;
     private isPopupDefinition;
     private isPopupTrigger;