@magicfeedback/popup-sdk 1.1.7 → 1.2.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
@@ -139,9 +142,11 @@ interface DeepdotsInitParams {
     /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
     platform?: 'web' | 'android' | 'ios';
     /**
-     * BCP-47 language tag for the analytics context (e.g. 'es-ES'). If omitted, the SDK
-     * auto-detects: `navigator.language` on web, or the `Intl` locale as a fallback (works in
-     * React Native with Hermes, where `navigator.language` is absent).
+     * BCP-47 language tag (e.g. 'es-ES') used for the analytics context AND for popup
+     * language segmentation (`segments.lang`). If omitted, the SDK auto-detects:
+     * `navigator.language` on web, or the `Intl` locale as a fallback (works in
+     * React Native with Hermes, where `navigator.language` is absent). If no source
+     * resolves a language, popups with `segments.lang` cannot be filtered and are shown.
      */
     language?: string;
     /** Injectable device info (RN: from react-native-device-info). If missing, it is derived from the browser. */
@@ -277,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'`). */
@@ -325,14 +333,29 @@ 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.
+     */
+    private language;
     /** 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. */
@@ -371,24 +394,66 @@ 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;
-    /** Envía (hoy dry-run → console.log) el lote acumulado de analytics y vacía el buffer. */
-    flushAnalytics(): void;
+    /**
+     * 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.
+     */
+    flushAnalytics(options?: {
+        final?: boolean;
+        sessionEnd?: boolean;
+    }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
     private analyticsIdentity;

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
@@ -139,9 +142,11 @@ interface DeepdotsInitParams {
     /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
     platform?: 'web' | 'android' | 'ios';
     /**
-     * BCP-47 language tag for the analytics context (e.g. 'es-ES'). If omitted, the SDK
-     * auto-detects: `navigator.language` on web, or the `Intl` locale as a fallback (works in
-     * React Native with Hermes, where `navigator.language` is absent).
+     * BCP-47 language tag (e.g. 'es-ES') used for the analytics context AND for popup
+     * language segmentation (`segments.lang`). If omitted, the SDK auto-detects:
+     * `navigator.language` on web, or the `Intl` locale as a fallback (works in
+     * React Native with Hermes, where `navigator.language` is absent). If no source
+     * resolves a language, popups with `segments.lang` cannot be filtered and are shown.
      */
     language?: string;
     /** Injectable device info (RN: from react-native-device-info). If missing, it is derived from the browser. */
@@ -277,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'`). */
@@ -325,14 +333,29 @@ 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.
+     */
+    private language;
     /** 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. */
@@ -371,24 +394,66 @@ 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;
-    /** Envía (hoy dry-run → console.log) el lote acumulado de analytics y vacía el buffer. */
-    flushAnalytics(): void;
+    /**
+     * 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.
+     */
+    flushAnalytics(options?: {
+        final?: boolean;
+        sessionEnd?: boolean;
+    }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
     private analyticsIdentity;