@magicfeedback/popup-sdk 1.10.0 → 1.11.0

package/README.md

@@ -215,6 +215,26 @@ const renderer = new ReactNativePopupRenderer({
 `onReady` is optional: a host that opens its container on `onShow` still never shows the spinner,
 because the HTML reveals itself; the container just appears a few hundred ms before the card.
 
+### Focus on text questions
+
+When the first question of a page is a text field (text, long text, email or number), the cursor
+is placed in it so the user can start typing:
+
+- **When the popup opens:** only on devices with a mouse or trackpad (`pointer: fine`). On touch
+  devices it does nothing, so the keyboard never pops up over a popup the user has not touched.
+- **After Start, Next or Back:** on every device, since the user has just tapped.
+
+Only the first question counts: if the page starts with a rating and the text field comes after
+it, nothing is focused. The focus is never taken away from a field of the host page.
+
+The focus itself comes from `@magicfeedback/native` (its `autofocus` option, which the popup sets
+to `'navigation'`, and `focusFirstQuestion()` when the popup is revealed). Versions of
+`@magicfeedback/native` without that option simply ignore it.
+
+In React Native on iOS, the WebView ignores focus set from JavaScript unless the keyboard is
+allowed to open without a direct tap. `DeepdotsProvider` already does this; if you mount the
+WebView yourself, add `keyboardDisplayRequiresUserAction={false}` to it.
+
 ### `autoLaunch()`
 
 Starts the triggers derived from the popup definitions loaded during `init()`.
@@ -237,6 +257,8 @@ Example:
 popups.triggerEvent('search');
 ```
 
+It can be called right after `init()`: if the popup definitions are still loading, the event is kept and evaluated as soon as they arrive (the same applies to `triggerSurvey`).
+
 ### `triggerSurvey(surveyId, popupId?)`
 
 Opens a specific survey directly, bypassing trigger evaluation.
@@ -500,7 +522,7 @@ interface DeepdotsEvent {
 - `action`
 - `userId`
 
-`popup_clicked` is a general interaction event. Depending on the flow, `data.action` can contain values such as `loaded`, `start_survey`, `manual_send`, `back`, `complete`, or `close_icon`.
+`popup_clicked` means the user did something in the popup. On the web, `data.action` is one of `start_survey`, `manual_send`, `back`, `complete`, `close_icon`, or `partial` (the user answered a page and moved on; this one also marks the popup as `PARTIAL` in the backend). Loading the survey, the start of a submit, and validation or submit errors are not interactions and do not emit it. In React Native the bridge emits it once per popup, with `action: 'partial'`, on the first real interaction (sending an answer or going back).
 
 ## Important Behavior Notes
 

package/dist/index.d.mts

@@ -188,6 +188,11 @@ interface FeedbackSinkOptions {
      * romper a quien lo pase.
      */
     sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
+    /**
+     * Registro en el que seguir desde el primer lote: el de una sesión suspendida por un
+     * `pagehide` y reanudada tras recargar la página (ver `suspended-session.ts`).
+     */
+    initialSessionId?: string;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
     onSessionId?: (id: string) => void;
     /** Callback invocado al cerrar la sesión (`completed:true`): el sessionId cacheado se olvida. */
@@ -708,6 +713,14 @@ declare class DeepdotsPopups {
     private popupContainer;
     private popupDefinitions;
     private popupsLoaded;
+    /**
+     * `true` mientras el `GET /sdk/{apiKey}/popups` de `init()` está en vuelo. En esa ventana los
+     * disparos del host (`triggerEvent`, `triggerSurvey`) no tienen contra qué evaluarse, así que
+     * se guardan en `pendingTriggers` y se reproducen al cargar. Click, scroll, time y exit no
+     * hacen falta: son listeners que `autoLaunch` instala ya con las definiciones cargadas.
+     */
+    private awaitingPopups;
+    private pendingTriggers;
     private pendingAutoLaunch;
     private answeredSurveys;
     private surveyProgress;
@@ -756,6 +769,13 @@ declare class DeepdotsPopups {
     private lastEngagementAt;
     /** Cuándo se ocultó la pestaña por última vez (ms epoch); null si está visible. */
     private hiddenAt;
+    /**
+     * Sesión suspendida por un `pagehide` (ms epoch y `deepdots_user_id`); null si no hay.
+     * `openSession` la reanuda si sigue a tiempo (ver ANALYTICS_RESUME_WINDOW_MS).
+     */
+    private suspended;
+    /** Integración de analytics del init: la sesión suspendida solo la hereda la misma. */
+    private analyticsIntegration;
     /**
      * 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.
@@ -898,6 +918,31 @@ declare class DeepdotsPopups {
      *  - Más: ya la cerró el backend → se descarta sin enviar nada.
      */
     private onDocumentVisible;
+    /**
+     * `pagehide` en web: SUSPENDE la sesión en vez de cerrarla, porque el navegador lo lanza
+     * igual al recargar que al cerrar la pestaña. Vuelca lo pendiente (page_view de la
+     * pantalla, mini-services, engagement) con un `deepdots_session_suspend` y SIN
+     * `completed`, y deja el registro en `sessionStorage` (ver `suspended-session.ts`):
+     *  - si la página vuelve a cargar en esta pestaña, `init()` sigue en el mismo registro;
+     *  - si la pestaña se cerró, el backend lo cierra a los pocos minutos sin otro lote.
+     *
+     * Devuelve false cuando no se puede suspender — aún no se conoce el registro (el primer
+     * POST sigue en vuelo) o no hay `sessionStorage` — y entonces el caller cierra como antes.
+     */
+    private suspendSession;
+    /**
+     * Recoge la sesión que dejó suspendida la carga anterior de esta pestaña (ver
+     * `suspendSession`). Solo con analytics configurado y el tracking activo: sin ellos no hay
+     * registro en el que seguir.
+     */
+    private readResumableSession;
+    /**
+     * Consume la sesión suspendida al abrir: los ms que estuvo suspendida si se puede seguir en
+     * ella (mismo usuario, dentro de ANALYTICS_RESUME_WINDOW_MS); null si no había o ya no toca.
+     * En ese caso se olvida su registro sin enviar nada: lo cierra el backend, y la sesión que
+     * se abre ahora va a uno nuevo.
+     */
+    private takeSuspendedSession;
     /** Olvida la sesión abierta sin enviar nada (ver onDocumentVisible). */
     private discardSession;
     /**
@@ -923,6 +968,17 @@ declare class DeepdotsPopups {
     triggerSurvey(surveyId: string, popupId?: string): void;
     /** Trigger popups configured with trigger.type = 'event' and matching trigger.value */
     triggerEvent(eventName: string): void;
+    private evaluateEvent;
+    /**
+     * Guarda `trigger` si las definiciones aún no han llegado. Devuelve `true` si lo guardó (el
+     * llamador no debe evaluarlo ahora) y `false` si no hay carga en vuelo (se evalúa ya, como
+     * siempre: tras cargar, tras un fallo o sin apiKey).
+     */
+    private bufferIfAwaitingPopups;
+    /** La carga falló: sin definiciones no hay nada que reproducir, se descarta todo. */
+    private dropPendingTriggers;
+    /** Reproduce en orden por la evaluación normal (segmentos, cooldowns y condiciones de AHORA). */
+    private replayPendingTriggers;
     private showDefinition;
     private shouldShow;
     private matchesSegmentsLang;
@@ -961,7 +1017,7 @@ declare class DeepdotsPopups {
     private removeDeferredExitPopup;
     private getDeferredExitQueue;
     private setDeferredExitQueue;
-    /** Fetch al servidor para obtener popups */
+    /** Fetch al servidor para obtener popups. `null` si la carga falló (red, no-2xx, payload inválido). */
     private fetchPopupsFromServer;
     /** Envía los atributos de contact a la API (`POST /sdk/popups/contact`). */
     private postContact;

package/dist/index.d.ts

@@ -188,6 +188,11 @@ interface FeedbackSinkOptions {
      * romper a quien lo pase.
      */
     sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
+    /**
+     * Registro en el que seguir desde el primer lote: el de una sesión suspendida por un
+     * `pagehide` y reanudada tras recargar la página (ver `suspended-session.ts`).
+     */
+    initialSessionId?: string;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
     onSessionId?: (id: string) => void;
     /** Callback invocado al cerrar la sesión (`completed:true`): el sessionId cacheado se olvida. */
@@ -708,6 +713,14 @@ declare class DeepdotsPopups {
     private popupContainer;
     private popupDefinitions;
     private popupsLoaded;
+    /**
+     * `true` mientras el `GET /sdk/{apiKey}/popups` de `init()` está en vuelo. En esa ventana los
+     * disparos del host (`triggerEvent`, `triggerSurvey`) no tienen contra qué evaluarse, así que
+     * se guardan en `pendingTriggers` y se reproducen al cargar. Click, scroll, time y exit no
+     * hacen falta: son listeners que `autoLaunch` instala ya con las definiciones cargadas.
+     */
+    private awaitingPopups;
+    private pendingTriggers;
     private pendingAutoLaunch;
     private answeredSurveys;
     private surveyProgress;
@@ -756,6 +769,13 @@ declare class DeepdotsPopups {
     private lastEngagementAt;
     /** Cuándo se ocultó la pestaña por última vez (ms epoch); null si está visible. */
     private hiddenAt;
+    /**
+     * Sesión suspendida por un `pagehide` (ms epoch y `deepdots_user_id`); null si no hay.
+     * `openSession` la reanuda si sigue a tiempo (ver ANALYTICS_RESUME_WINDOW_MS).
+     */
+    private suspended;
+    /** Integración de analytics del init: la sesión suspendida solo la hereda la misma. */
+    private analyticsIntegration;
     /**
      * 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.
@@ -898,6 +918,31 @@ declare class DeepdotsPopups {
      *  - Más: ya la cerró el backend → se descarta sin enviar nada.
      */
     private onDocumentVisible;
+    /**
+     * `pagehide` en web: SUSPENDE la sesión en vez de cerrarla, porque el navegador lo lanza
+     * igual al recargar que al cerrar la pestaña. Vuelca lo pendiente (page_view de la
+     * pantalla, mini-services, engagement) con un `deepdots_session_suspend` y SIN
+     * `completed`, y deja el registro en `sessionStorage` (ver `suspended-session.ts`):
+     *  - si la página vuelve a cargar en esta pestaña, `init()` sigue en el mismo registro;
+     *  - si la pestaña se cerró, el backend lo cierra a los pocos minutos sin otro lote.
+     *
+     * Devuelve false cuando no se puede suspender — aún no se conoce el registro (el primer
+     * POST sigue en vuelo) o no hay `sessionStorage` — y entonces el caller cierra como antes.
+     */
+    private suspendSession;
+    /**
+     * Recoge la sesión que dejó suspendida la carga anterior de esta pestaña (ver
+     * `suspendSession`). Solo con analytics configurado y el tracking activo: sin ellos no hay
+     * registro en el que seguir.
+     */
+    private readResumableSession;
+    /**
+     * Consume la sesión suspendida al abrir: los ms que estuvo suspendida si se puede seguir en
+     * ella (mismo usuario, dentro de ANALYTICS_RESUME_WINDOW_MS); null si no había o ya no toca.
+     * En ese caso se olvida su registro sin enviar nada: lo cierra el backend, y la sesión que
+     * se abre ahora va a uno nuevo.
+     */
+    private takeSuspendedSession;
     /** Olvida la sesión abierta sin enviar nada (ver onDocumentVisible). */
     private discardSession;
     /**
@@ -923,6 +968,17 @@ declare class DeepdotsPopups {
     triggerSurvey(surveyId: string, popupId?: string): void;
     /** Trigger popups configured with trigger.type = 'event' and matching trigger.value */
     triggerEvent(eventName: string): void;
+    private evaluateEvent;
+    /**
+     * Guarda `trigger` si las definiciones aún no han llegado. Devuelve `true` si lo guardó (el
+     * llamador no debe evaluarlo ahora) y `false` si no hay carga en vuelo (se evalúa ya, como
+     * siempre: tras cargar, tras un fallo o sin apiKey).
+     */
+    private bufferIfAwaitingPopups;
+    /** La carga falló: sin definiciones no hay nada que reproducir, se descarta todo. */
+    private dropPendingTriggers;
+    /** Reproduce en orden por la evaluación normal (segmentos, cooldowns y condiciones de AHORA). */
+    private replayPendingTriggers;
     private showDefinition;
     private shouldShow;
     private matchesSegmentsLang;
@@ -961,7 +1017,7 @@ declare class DeepdotsPopups {
     private removeDeferredExitPopup;
     private getDeferredExitQueue;
     private setDeferredExitQueue;
-    /** Fetch al servidor para obtener popups */
+    /** Fetch al servidor para obtener popups. `null` si la carga falló (red, no-2xx, payload inválido). */
     private fetchPopupsFromServer;
     /** Envía los atributos de contact a la API (`POST /sdk/popups/contact`). */
     private postContact;