@magicfeedback/popup-sdk 1.1.8 → 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
@@ -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;

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;

package/dist/react-native.js

@@ -1149,6 +1149,11 @@ async function renderPopup(container, surveyId, productId, actions, emit, onClos
   const isDark = style?.theme === "dark";
   const theme = {
     popupBg: isDark ? "#1e1e1e" : "#fff",
+    // El popup fija su propio fondo, así que debe fijar también el esquema de color.
+    // Sin esto los controles de formulario (input/textarea/select) caen al estilo por
+    // defecto del navegador: en un host con `prefers-color-scheme: dark` se pintan
+    // oscuros con texto blanco sobre el fondo claro del popup.
+    colorScheme: isDark ? "dark" : "light",
     textPrimary: isDark ? "#f0f0f0" : "#111",
     closeBtnHoverBg: isDark ? "rgba(255,255,255,0.10)" : "rgba(0,0,0,0.06)",
     closeBtnHoverColor: isDark ? "#fff" : "#000000"
@@ -1171,6 +1176,7 @@ async function renderPopup(container, surveyId, productId, actions, emit, onClos
       flex-direction: column;
       justify-content: flex-start;
       background: ${theme.popupBg};
+      color-scheme: ${theme.colorScheme};
       border-radius: 8px;
       padding: 24px;
       box-shadow: 0 4px 6px rgba(0,0,0,0.1);
@@ -2079,6 +2085,15 @@ var AnalyticsManager = class {
       this.exitMiniService(name);
     }
   }
+  /**
+   * 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
+   * vieja, y lo que llegue después es del usuario nuevo.
+   */
+  resetUserScope() {
+    this.attributes = {};
+    this.metrics = {};
+  }
   /** Registra un evento de analítica (modelo GA: nombre + params). */
   track(name, params) {
     const current = this.getMiniService();
@@ -2166,7 +2181,7 @@ function pushKV(list, key, value) {
   if (value === void 0 || value === null || value === "") return;
   list.push({ key, value: [String(value)] });
 }
-function buildAnalyticsFeedbackBody(envelope, keys, feedbackSessionId) {
+function buildAnalyticsFeedbackBody(envelope, keys, feedbackSessionId, options) {
   const { context } = envelope;
   const profile = [];
   pushKV(profile, "external-user-id", envelope.userId);
@@ -2217,7 +2232,8 @@ function buildAnalyticsFeedbackBody(envelope, keys, feedbackSessionId) {
     },
     publicKey: keys.publicKey,
     integration: keys.integration,
-    completed: false,
+    // Único marcador de cierre acordado con backend: el último lote de la sesión.
+    completed: options?.sessionEnd === true,
     ...feedbackSessionId ? { sessionId: feedbackSessionId } : {}
   };
 }
@@ -2236,7 +2252,7 @@ function createFeedbackSink(options) {
   let feedbackSessionId;
   let firstPostInFlight = null;
   const url = `${options.baseUrl}/sdk/feedback`;
-  const post = async (body, final) => {
+  const post = async (body, final, sessionEnd = false) => {
     const json = JSON.stringify(body);
     const small = json.length <= KEEPALIVE_MAX_BYTES;
     if (final && options.sendBeaconImpl && small) {
@@ -2270,6 +2286,7 @@ function createFeedbackSink(options) {
       );
       return;
     }
+    if (sessionEnd) return;
     try {
       const data = await res.json();
       if (data?.sessionId && data.sessionId !== feedbackSessionId) {
@@ -2282,13 +2299,18 @@ function createFeedbackSink(options) {
   };
   return async (envelope, meta) => {
     const final = meta?.final === true;
+    const sessionEnd = meta?.sessionEnd === true;
     if (!feedbackSessionId && firstPostInFlight && !final) {
       await firstPostInFlight;
     }
-    const body = buildAnalyticsFeedbackBody(envelope, options.keys, feedbackSessionId);
+    const body = buildAnalyticsFeedbackBody(envelope, options.keys, feedbackSessionId, { sessionEnd });
     options.log?.("[DeepdotsAnalytics] POST /sdk/feedback \u2192", body);
-    const sent = post(body, final);
-    if (!feedbackSessionId) {
+    const sent = post(body, final, sessionEnd);
+    if (sessionEnd) {
+      feedbackSessionId = void 0;
+      firstPostInFlight = null;
+      options.onSessionReset?.();
+    } else if (!feedbackSessionId) {
       firstPostInFlight = sent.then(
         () => void 0,
         () => void 0
@@ -2727,6 +2749,7 @@ var CrashReporter = class {
 init_logger();
 
 // src/analytics/messaging.ts
+var MESSAGE_CHANNELS = ["push", "in_app"];
 function buildMessageParams(stage, o) {
   const p = {
     stage,
@@ -2739,6 +2762,57 @@ function buildMessageParams(stage, o) {
   if (o.currency) p.currency = o.currency;
   return { ...p, ...o.params ?? {} };
 }
+var MAX_TRACKED_MESSAGES = 500;
+var MessageGuard = class {
+  constructor(maxTrackedMessages = MAX_TRACKED_MESSAGES) {
+    this.maxTrackedMessages = maxTrackedMessages;
+    /** message_id → canal fijado + stages ya emitidos. El orden de inserción marca la eviction. */
+    this.seen = /* @__PURE__ */ new Map();
+  }
+  evaluate(stage, options) {
+    const channel = options.channel;
+    if (!MESSAGE_CHANNELS.includes(channel)) {
+      return {
+        emit: false,
+        reason: "invalid_channel",
+        detail: `channel "${channel}" no v\xE1lido (esperado ${MESSAGE_CHANNELS.join(" | ")})`
+      };
+    }
+    const entry = this.seen.get(options.id);
+    if (!entry) {
+      this.remember(options.id, channel, stage);
+      return { emit: true };
+    }
+    if (entry.channel !== channel) {
+      return {
+        emit: false,
+        reason: "channel_conflict",
+        detail: `message_id "${options.id}" ya se report\xF3 en channel "${entry.channel}"; se descarta "${channel}"`
+      };
+    }
+    if (entry.stages.has(stage)) {
+      return {
+        emit: false,
+        reason: "duplicate_stage",
+        detail: `stage "${stage}" ya emitido para message_id "${options.id}"`
+      };
+    }
+    entry.stages.add(stage);
+    return { emit: true };
+  }
+  /** Olvida todo lo vigilado (nueva sesión). */
+  reset() {
+    this.seen.clear();
+  }
+  remember(id, channel, stage) {
+    this.seen.set(id, { channel, stages: /* @__PURE__ */ new Set([stage]) });
+    while (this.seen.size > this.maxTrackedMessages) {
+      const oldest = this.seen.keys().next();
+      if (oldest.done) break;
+      this.seen.delete(oldest.value);
+    }
+  }
+};
 
 // src/core/deepdots-popups.ts
 var EXIT_QUEUE_STORAGE_KEY = "__deepdots_exit_popup_queue__";
@@ -2780,14 +2854,24 @@ var DeepdotsPopups = class {
     this.analyticsFlushTimer = void 0;
     /** Crash & error reporting (#14–17). Null hasta init(). */
     this.crashReporter = null;
+    /** Protecciones del funnel de Messaging (#18–22). Vigencia de sesión: se reinicia en init(). */
+    this.messageGuard = new MessageGuard();
     /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
     this.navObserver = null;
     /** Tiempo activo (engagement time, #8). */
     this.engagement = null;
     /** Atributos internos del usuario identificado → POST /sdk/popups/contact. Null si no hay userId. */
     this.contact = null;
+    /** Storage resuelto en init() (inyectado por el host o localStorage). Reusado al cambiar de usuario. */
+    this.storage = null;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     this.navStarted = false;
+    /**
+     * `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.
+     */
+    this.sessionOpen = false;
     /**
      * 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.
@@ -2799,6 +2883,11 @@ var DeepdotsPopups = class {
     this.logger = config.logger ?? console;
     setLogger(this.logger);
     if (this.initialized) {
+      const nextUserId = config.userId || void 0;
+      if (nextUserId !== this.config?.userId) {
+        this.setUserId(nextUserId);
+        return;
+      }
       this.log("SDK already initialized");
       return;
     }
@@ -2811,6 +2900,7 @@ var DeepdotsPopups = class {
       userId: config.userId || void 0
     };
     const storage = config.storage ?? createDefaultStorage();
+    this.storage = storage;
     this.tracking = new TrackingManager({
       storage,
       clientUserId: this.config.userId,
@@ -2838,6 +2928,9 @@ var DeepdotsPopups = class {
       sendBeaconImpl: typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function" ? (url, body) => navigator.sendBeacon(url, body) : void 0,
       onSessionId: (id) => {
         this.analyticsFeedbackSessionId = id;
+      },
+      onSessionReset: () => {
+        this.analyticsFeedbackSessionId = void 0;
       }
     }) : createDryRunSink((...a) => this.logger.log(...a));
     const device = config.device ?? collectDeviceInfo(config.appVersion);
@@ -2846,6 +2939,7 @@ var DeepdotsPopups = class {
       navigator: typeof navigator !== "undefined" ? navigator : void 0,
       intl: typeof Intl !== "undefined" ? Intl : void 0
     });
+    this.messageGuard.reset();
     this.analytics = new AnalyticsManager({
       sink: analyticsSink,
       publicKey: config.analytics?.publicKey ?? this.config.apiKey,
@@ -2881,7 +2975,7 @@ var DeepdotsPopups = class {
     this.engagement = new EngagementTracker();
     this.engagement.resume();
     this.setupAnalyticsFlush();
-    this.track("deepdots_session_start", {});
+    this.openSession();
     const pendingCrashes = this.crashReporter.drainPendingCrashes();
     if (this.tracking?.isTrackingEnabled()) {
       for (const rec of pendingCrashes) {
@@ -2913,7 +3007,9 @@ var DeepdotsPopups = class {
   }
   /** Activa/desactiva el tracking (identidad + sesión + analytics). Kill-switch del contrato §7bis. */
   setTrackingEnabled(enabled) {
+    if (!enabled) this.closeSession("tracking_disabled");
     this.tracking?.setTrackingEnabled(enabled);
+    if (enabled) this.openSession();
     this.log("tracking \xB7 setTrackingEnabled:", enabled, "\xB7 session_id:", this.tracking?.getSessionId() ?? null);
   }
   // ───────── Analytics (canal separado del feedback, vinculado por user_id) ─────────
@@ -2983,8 +3079,18 @@ var DeepdotsPopups = class {
   trackFunnelStep(funnel, step, taskId, params) {
     this.track("deepdots_funnel_step", { funnel, step, task_id: taskId, ...params ?? {} });
   }
-  /** 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, options) {
+    const verdict = this.messageGuard.evaluate(stage, options);
+    if (!verdict.emit) {
+      console.warn(`[DeepdotsPopups] trackMessage descartado (${verdict.reason}): ${verdict.detail}`);
+      return;
+    }
     this.track("deepdots_message", buildMessageParams(stage, options));
   }
   /**
@@ -3000,21 +3106,86 @@ var DeepdotsPopups = class {
       this.navObserver.visit(name);
     }
   }
-  /** 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() {
     this.engagement?.resume();
+    this.openSession();
   }
   /**
-   * 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() {
+    this.closeSession("background");
+    this.engagement?.pause();
+  }
+  /**
+   * 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() {
+    this.closeSession("manual");
+  }
+  /**
+   * 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) {
+    const next = userId || void 0;
+    if (!this.initialized || !this.config || next === this.config.userId) return;
+    this.closeSession("user_change");
+    const enabled = this.tracking?.isTrackingEnabled() ?? true;
+    const storage = this.storage ?? createDefaultStorage();
+    this.config.userId = next;
+    this.tracking = new TrackingManager({ storage, clientUserId: next, enabled });
+    this.contact = next ? new ContactManager({
+      storage,
+      publicKey: this.config.apiKey ?? "",
+      userId: next,
+      post: (body) => this.postContact(body)
+    }) : null;
+    this.analytics?.resetUserScope();
+    this.messageGuard.reset();
+    this.log("tracking \xB7 user_change \xB7 user_id:", this.tracking.getUserId());
+    this.openSession();
+  }
+  /**
+   * 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`.
+   */
+  closeSession(reason) {
+    if (!this.sessionOpen) return;
+    if (!this.tracking?.isTrackingEnabled()) return;
+    this.sessionOpen = false;
     this.navObserver?.stop();
     this.navStarted = false;
-    if (this.tracking?.isTrackingEnabled()) this.analytics?.exitAllMiniServices();
+    this.analytics?.exitAllMiniServices();
     this.flushEngagement();
-    this.engagement?.pause();
-    this.flushAnalytics();
+    this.track("deepdots_session_end", { reason });
+    this.flushAnalytics({ final: reason === "page_hide", sessionEnd: true });
+    this.analyticsFeedbackSessionId = void 0;
+    this.tracking?.setSessionId(null);
+    this.log("tracking \xB7 session_end:", reason);
+  }
+  /**
+   * 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.
+   */
+  openSession() {
+    if (this.sessionOpen) return;
+    if (!this.tracking?.isTrackingEnabled()) return;
+    this.sessionOpen = true;
+    this.track("deepdots_session_start", {});
   }
   /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
   previewAnalytics() {
@@ -3052,10 +3223,7 @@ var DeepdotsPopups = class {
     this.analyticsFlushTimer = setInterval(() => this.flushAnalytics(), ANALYTICS_FLUSH_INTERVAL_MS);
     window.addEventListener("pagehide", () => {
       clearInterval(this.analyticsFlushTimer);
-      this.navObserver?.stop();
-      if (this.tracking?.isTrackingEnabled()) this.analytics?.exitAllMiniServices();
-      this.flushEngagement();
-      this.flushAnalytics({ final: true });
+      this.closeSession("page_hide");
     });
     document.addEventListener("visibilitychange", () => {
       if (document.visibilityState === "hidden") {
@@ -3730,7 +3898,8 @@ function setupReactNative(sdk2, config, deps = {}) {
   if (deps.appState?.addEventListener) {
     subscription = deps.appState.addEventListener("change", (state) => {
       if (state === "active") sdk2.onForeground();
-      else sdk2.onBackground();
+      else if (state === "background") sdk2.onBackground();
+      else sdk2.flushAnalytics();
     });
   }
   return () => {