@magicfeedback/popup-sdk 1.1.8 → 1.3.0

package/dist/react-native.d.mts

@@ -86,8 +86,11 @@ interface AnalyticsEnvelope {
  * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
  *
  * La analítica se envía como un Feedback del modelo del Surveys SDK, agrupado por una
- * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false` y
- * `finished:false` (nunca se "cierra"); el backend cose por `sessionId` + `user_id`.
+ * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false`; el
+ * backend cose por `sessionId` + `user_id`. El ÚLTIMO lote de una sesión (cierre de página,
+ * app a background, cambio de usuario) va con `completed:true`: cierra el registro y el
+ * siguiente lote omite el `sessionId` viejo para que el backend abra uno nuevo.
+ * `feedback.finished` se queda siempre en `false` (no es la señal de cierre acordada).
  *
  * Encoding:
  *  - todo va en `feedback.metadata`: contexto (user_id, session_id, platform…) + eventos
@@ -279,13 +282,16 @@ interface ReactNativeErrorUtils {
  * el funnel se correlaciona por `message_id` y se agrupa por `message_title`.
  */
 type MessageStage = 'delivered' | 'clicked' | 'converted';
+/** Canales válidos. Un mensaje tiene UN canal: se valida en runtime porque el host puede no ser TS. */
+declare const MESSAGE_CHANNELS: readonly ["push", "in_app"];
+type MessageChannel = (typeof MESSAGE_CHANNELS)[number];
 interface TrackMessageOptions {
     /** Identificador del mensaje/notificación — correlaciona el funnel delivered→clicked→converted. */
     id: string;
     /** Título del mensaje — dimensión de agrupación de #18–22. */
     title: string;
     /** Canal de entrega. */
-    channel: 'push' | 'in_app';
+    channel: MessageChannel;
     /** Nombre de la campaña (opcional). */
     campaign?: string;
     /** Valor de conversión (opcional, típico en `stage: 'converted'`). */
@@ -327,14 +333,24 @@ declare class DeepdotsPopups {
     private analyticsFlushTimer;
     /** Crash & error reporting (#14–17). Null hasta init(). */
     private crashReporter;
+    /** Protecciones del funnel de Messaging (#18–22). Vigencia de sesión: se reinicia en init(). */
+    private messageGuard;
     /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
     private navObserver;
     /** Tiempo activo (engagement time, #8). */
     private engagement;
     /** Atributos internos del usuario identificado → POST /sdk/popups/contact. Null si no hay userId. */
     private contact;
+    /** Storage resuelto en init() (inyectado por el host o localStorage). Reusado al cambiar de usuario. */
+    private storage;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     private navStarted;
+    /**
+     * `true` entre `session_start` y `session_end`. Hace idempotente tanto la apertura como
+     * el cierre (p. ej. `visibilitychange` + `pagehide` seguidos) y permite abrir una sesión
+     * nueva al volver a foreground o al conceder el consentimiento más tarde.
+     */
+    private sessionOpen;
     /**
      * 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.
@@ -378,20 +394,55 @@ declare class DeepdotsPopups {
     trackFindabilityFriction(frictionTopic: string, params?: Record<string, unknown>): void;
     /** Funnel: un paso del embudo, correlacionado por `taskId`. El backend reconstruye conversión/drop-off/tiempo. */
     trackFunnelStep(funnel: string, step: string, taskId: string, params?: Record<string, unknown>): void;
-    /** Messaging (#18–22): registra una etapa del funnel de una notificación (push/in-app). No-op si tracking off. */
+    /**
+     * Messaging (#18–22): registra una etapa del funnel de una notificación (push/in-app).
+     * No-op si tracking off. El evento se descarta (con warning) si el `channel` no es válido,
+     * si ese `(message_id, stage)` ya se emitió en la sesión, o si el `message_id` ya se reportó
+     * en otro canal — ver `MessageGuard`.
+     */
     trackMessage(stage: MessageStage, options: TrackMessageOptions): void;
     /**
      * Navegación MANUAL (entornos sin History API, p. ej. React Native con React Navigation).
      * El host la llama en cada cambio de pantalla; emite `page_view` al salir de la anterior.
      */
     setScreen(name: string): void;
-    /** App a foreground (RN: AppState 'active'): reanuda el engagement time. */
+    /** App a foreground (RN: AppState 'active'): reanuda el engagement time y abre sesión nueva. */
     onForeground(): void;
     /**
-     * App a background (RN: AppState 'background'): cierra pantalla actual (page_view),
-     * mini-service (mini_service_exit), emite engagement y hace flush del lote.
+     * App a background (RN: AppState 'background'): FIN DE SESIÓN. Cierra pantalla actual
+     * (page_view), mini-services (mini_service_exit), emite engagement + `session_end` y
+     * envía el último lote con `completed:true`.
+     *
+     * Es la única señal disponible en móvil: el kill de la app (swipe) NO da callback.
      */
     onBackground(): void;
+    /**
+     * Cierre EXPLÍCITO de la sesión por parte del host (logout, fin de flujo…): emite
+     * `session_end` y envía el último lote con `completed:true`.
+     */
+    endSession(): void;
+    /**
+     * Cambio de usuario (login / logout / cambio de cuenta). Cierra la sesión del usuario
+     * anterior (`session_end` con `reason: 'user_change'` + `completed:true`), cambia la
+     * identidad y abre una sesión nueva. Sin `userId` vuelve al id anónimo del SDK.
+     *
+     * Equivale a llamar a `init()` otra vez con otro `userId`.
+     */
+    setUserId(userId?: string): void;
+    /**
+     * Cierra la sesión actual: vuelca todo lo que quedaba abierto y envía el último lote
+     * marcado con `completed:true`, para que el backend cierre el registro. El `sessionId`
+     * cacheado se olvida → el lote siguiente abre un registro nuevo.
+     *
+     * Idempotente: dos cierres seguidos (p. ej. `visibilitychange` + `pagehide`) no duplican
+     * el `session_end`.
+     */
+    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.
+     */
+    private openSession;
     /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
     previewAnalytics(): AnalyticsEnvelope;
     /**
@@ -401,6 +452,7 @@ declare class DeepdotsPopups {
      */
     flushAnalytics(options?: {
         final?: boolean;
+        sessionEnd?: boolean;
     }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
@@ -560,7 +612,7 @@ declare class ReactNativePopupRenderer implements PopupRenderer {
     private partialEmitted;
     constructor(options?: ReactNativeRendererOptions);
     init(): void;
-    show(surveyId: string, productId: string, _actions: PopupActions | undefined, emit: EmitFn, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string): void;
+    show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: EmitFn, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string): void;
     hide(): void;
     /**
      * El host la conecta al `onMessage` del WebView. Traduce los mensajes del survey a

package/dist/react-native.d.ts

@@ -86,8 +86,11 @@ interface AnalyticsEnvelope {
  * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
  *
  * La analítica se envía como un Feedback del modelo del Surveys SDK, agrupado por una
- * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false` y
- * `finished:false` (nunca se "cierra"); el backend cose por `sessionId` + `user_id`.
+ * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false`; el
+ * backend cose por `sessionId` + `user_id`. El ÚLTIMO lote de una sesión (cierre de página,
+ * app a background, cambio de usuario) va con `completed:true`: cierra el registro y el
+ * siguiente lote omite el `sessionId` viejo para que el backend abra uno nuevo.
+ * `feedback.finished` se queda siempre en `false` (no es la señal de cierre acordada).
  *
  * Encoding:
  *  - todo va en `feedback.metadata`: contexto (user_id, session_id, platform…) + eventos
@@ -279,13 +282,16 @@ interface ReactNativeErrorUtils {
  * el funnel se correlaciona por `message_id` y se agrupa por `message_title`.
  */
 type MessageStage = 'delivered' | 'clicked' | 'converted';
+/** Canales válidos. Un mensaje tiene UN canal: se valida en runtime porque el host puede no ser TS. */
+declare const MESSAGE_CHANNELS: readonly ["push", "in_app"];
+type MessageChannel = (typeof MESSAGE_CHANNELS)[number];
 interface TrackMessageOptions {
     /** Identificador del mensaje/notificación — correlaciona el funnel delivered→clicked→converted. */
     id: string;
     /** Título del mensaje — dimensión de agrupación de #18–22. */
     title: string;
     /** Canal de entrega. */
-    channel: 'push' | 'in_app';
+    channel: MessageChannel;
     /** Nombre de la campaña (opcional). */
     campaign?: string;
     /** Valor de conversión (opcional, típico en `stage: 'converted'`). */
@@ -327,14 +333,24 @@ declare class DeepdotsPopups {
     private analyticsFlushTimer;
     /** Crash & error reporting (#14–17). Null hasta init(). */
     private crashReporter;
+    /** Protecciones del funnel de Messaging (#18–22). Vigencia de sesión: se reinicia en init(). */
+    private messageGuard;
     /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
     private navObserver;
     /** Tiempo activo (engagement time, #8). */
     private engagement;
     /** Atributos internos del usuario identificado → POST /sdk/popups/contact. Null si no hay userId. */
     private contact;
+    /** Storage resuelto en init() (inyectado por el host o localStorage). Reusado al cambiar de usuario. */
+    private storage;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     private navStarted;
+    /**
+     * `true` entre `session_start` y `session_end`. Hace idempotente tanto la apertura como
+     * el cierre (p. ej. `visibilitychange` + `pagehide` seguidos) y permite abrir una sesión
+     * nueva al volver a foreground o al conceder el consentimiento más tarde.
+     */
+    private sessionOpen;
     /**
      * 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.
@@ -378,20 +394,55 @@ declare class DeepdotsPopups {
     trackFindabilityFriction(frictionTopic: string, params?: Record<string, unknown>): void;
     /** Funnel: un paso del embudo, correlacionado por `taskId`. El backend reconstruye conversión/drop-off/tiempo. */
     trackFunnelStep(funnel: string, step: string, taskId: string, params?: Record<string, unknown>): void;
-    /** Messaging (#18–22): registra una etapa del funnel de una notificación (push/in-app). No-op si tracking off. */
+    /**
+     * Messaging (#18–22): registra una etapa del funnel de una notificación (push/in-app).
+     * No-op si tracking off. El evento se descarta (con warning) si el `channel` no es válido,
+     * si ese `(message_id, stage)` ya se emitió en la sesión, o si el `message_id` ya se reportó
+     * en otro canal — ver `MessageGuard`.
+     */
     trackMessage(stage: MessageStage, options: TrackMessageOptions): void;
     /**
      * Navegación MANUAL (entornos sin History API, p. ej. React Native con React Navigation).
      * El host la llama en cada cambio de pantalla; emite `page_view` al salir de la anterior.
      */
     setScreen(name: string): void;
-    /** App a foreground (RN: AppState 'active'): reanuda el engagement time. */
+    /** App a foreground (RN: AppState 'active'): reanuda el engagement time y abre sesión nueva. */
     onForeground(): void;
     /**
-     * App a background (RN: AppState 'background'): cierra pantalla actual (page_view),
-     * mini-service (mini_service_exit), emite engagement y hace flush del lote.
+     * App a background (RN: AppState 'background'): FIN DE SESIÓN. Cierra pantalla actual
+     * (page_view), mini-services (mini_service_exit), emite engagement + `session_end` y
+     * envía el último lote con `completed:true`.
+     *
+     * Es la única señal disponible en móvil: el kill de la app (swipe) NO da callback.
      */
     onBackground(): void;
+    /**
+     * Cierre EXPLÍCITO de la sesión por parte del host (logout, fin de flujo…): emite
+     * `session_end` y envía el último lote con `completed:true`.
+     */
+    endSession(): void;
+    /**
+     * Cambio de usuario (login / logout / cambio de cuenta). Cierra la sesión del usuario
+     * anterior (`session_end` con `reason: 'user_change'` + `completed:true`), cambia la
+     * identidad y abre una sesión nueva. Sin `userId` vuelve al id anónimo del SDK.
+     *
+     * Equivale a llamar a `init()` otra vez con otro `userId`.
+     */
+    setUserId(userId?: string): void;
+    /**
+     * Cierra la sesión actual: vuelca todo lo que quedaba abierto y envía el último lote
+     * marcado con `completed:true`, para que el backend cierre el registro. El `sessionId`
+     * cacheado se olvida → el lote siguiente abre un registro nuevo.
+     *
+     * Idempotente: dos cierres seguidos (p. ej. `visibilitychange` + `pagehide`) no duplican
+     * el `session_end`.
+     */
+    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.
+     */
+    private openSession;
     /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
     previewAnalytics(): AnalyticsEnvelope;
     /**
@@ -401,6 +452,7 @@ declare class DeepdotsPopups {
      */
     flushAnalytics(options?: {
         final?: boolean;
+        sessionEnd?: boolean;
     }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
@@ -560,7 +612,7 @@ declare class ReactNativePopupRenderer implements PopupRenderer {
     private partialEmitted;
     constructor(options?: ReactNativeRendererOptions);
     init(): void;
-    show(surveyId: string, productId: string, _actions: PopupActions | undefined, emit: EmitFn, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string): void;
+    show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: EmitFn, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string): void;
     hide(): void;
     /**
      * El host la conecta al `onMessage` del WebView. Traduce los mensajes del survey a