@magicfeedback/popup-sdk 1.1.6 → 1.1.8

package/README.md

@@ -177,6 +177,11 @@ Config fields:
 - `mode?: 'server' | 'client'`
 - `debug?: boolean`
 - `popups?: PopupDefinition[]`
+- `language?: string` — BCP-47 tag (`'en'`, `'en-US'`, …) used for popup language
+  segmentation (`segments.lang`) and for the analytics context. If omitted it is
+  auto-detected from `navigator.language`, falling back to the `Intl` locale (which is
+  what makes it work in React Native, where `navigator.language` does not exist). If no
+  source resolves a language, popups with `segments.lang` cannot be filtered and are shown.
 
 ### `autoLaunch()`
 

package/dist/index.d.mts

@@ -86,10 +86,25 @@ interface AnalyticsEnvelope {
         device?: DeviceInfo;
         /** User attributes del cliente, usados para breakdowns (registration_status, pass_type, …). */
         attributes: Record<string, string>;
+        /** Métricas del host: valores medibles persistentes → van en `feedback.metrics` del body. */
+        metrics?: Record<string, string>;
     };
     events: AnalyticsEvent[];
 }
-type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
+/** Contexto del flush, para que el sink pueda adaptar el transporte. */
+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.
+     */
+    final?: boolean;
+}
+/**
+ * Envío del lote. Si devuelve una promesa que **rechaza**, el manager re-encola los
+ * eventos para reintentarlos en el siguiente flush (fallo transitorio: red o 5xx).
+ * Resolver = lote entregado o descartado definitivamente (no se reintenta).
+ */
+type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) => void | Promise<void>;
 
 /**
  * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
@@ -103,7 +118,8 @@ type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
  *  - cada entrada usa `value: string[]` (array de un elemento)
  *  - eventos: {key: nombre_evento, value: [JSON(timestamp + params)]}
  *  - identidad (user_id) → `profile` como `external-user-id`
- *  - `answers` vacío, `metrics` no se usa
+ *  - métricas del host (setMetric) → `feedback.metrics` (mismo shape que metadata, sin prefijo)
+ *  - `answers` vacío
  *  - `text` vacío
  */
 
@@ -119,6 +135,7 @@ interface AnalyticsFeedbackBody {
     feedback: {
         text: string;
         answers: FeedbackKV[];
+        metrics: FeedbackKV[];
         metadata: FeedbackKV[];
         profile: FeedbackKV[];
         finished: boolean;
@@ -139,15 +156,29 @@ interface FeedbackSinkOptions {
     log?: (...args: unknown[]) => void;
     /** 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`.
+     */
+    sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
     onSessionId?: (id: string) => void;
 }
 /**
  * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/feedback`.
- * Fire-and-forget (no bloquea el flush); errores solo se loguean.
- * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta
- * y lo envía en los siguientes POSTs para que el backend agrupe todos los eventos
- * en un único registro de feedback.
+ *
+ * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta y lo
+ * envía en los siguientes POSTs para que el backend agrupe todos los eventos en un único
+ * registro de feedback.
+ *
+ * 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;
+ *  - 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.
  */
 declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
 
@@ -185,6 +216,14 @@ interface DeepdotsInitParams {
     storage?: KeyValueStorage;
     /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
     platform?: 'web' | 'android' | 'ios';
+    /**
+     * 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. */
     device?: DeviceInfo;
     /**
@@ -517,6 +556,11 @@ declare class DeepdotsPopups {
     private contact;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     private navStarted;
+    /**
+     * 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. */
@@ -529,6 +573,11 @@ declare class DeepdotsPopups {
     track(name: string, params?: Record<string, unknown>): void;
     /** User attributes para breakdowns (registration_status, pass_type, sector, pass_status…). */
     setUserAttributes(attributes: Record<string, string | number | boolean>): void;
+    /**
+     * Registra/actualiza una métrica (valor medible) → `feedback.metrics` del body.
+     * Persistente y sobrescribe por key. No-op si tracking off.
+     */
+    setMetric(key: string, value: string | number | boolean): void;
     /** Reporta un error del host (manejado o no) → evento `deepdots_app_crash`. No-op si tracking off. */
     reportError(error: unknown, options?: ReportErrorOptions): void;
     /** Engancha `global.ErrorUtils` de RN para capturar errores JS no manejados. No-op si tracking off. */
@@ -566,8 +615,14 @@ declare class DeepdotsPopups {
     onBackground(): void;
     /** 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;
+    }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
     private analyticsIdentity;

package/dist/index.d.ts

@@ -86,10 +86,25 @@ interface AnalyticsEnvelope {
         device?: DeviceInfo;
         /** User attributes del cliente, usados para breakdowns (registration_status, pass_type, …). */
         attributes: Record<string, string>;
+        /** Métricas del host: valores medibles persistentes → van en `feedback.metrics` del body. */
+        metrics?: Record<string, string>;
     };
     events: AnalyticsEvent[];
 }
-type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
+/** Contexto del flush, para que el sink pueda adaptar el transporte. */
+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.
+     */
+    final?: boolean;
+}
+/**
+ * Envío del lote. Si devuelve una promesa que **rechaza**, el manager re-encola los
+ * eventos para reintentarlos en el siguiente flush (fallo transitorio: red o 5xx).
+ * Resolver = lote entregado o descartado definitivamente (no se reintenta).
+ */
+type AnalyticsSink = (payload: AnalyticsEnvelope, meta?: AnalyticsFlushMeta) => void | Promise<void>;
 
 /**
  * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
@@ -103,7 +118,8 @@ type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
  *  - cada entrada usa `value: string[]` (array de un elemento)
  *  - eventos: {key: nombre_evento, value: [JSON(timestamp + params)]}
  *  - identidad (user_id) → `profile` como `external-user-id`
- *  - `answers` vacío, `metrics` no se usa
+ *  - métricas del host (setMetric) → `feedback.metrics` (mismo shape que metadata, sin prefijo)
+ *  - `answers` vacío
  *  - `text` vacío
  */
 
@@ -119,6 +135,7 @@ interface AnalyticsFeedbackBody {
     feedback: {
         text: string;
         answers: FeedbackKV[];
+        metrics: FeedbackKV[];
         metadata: FeedbackKV[];
         profile: FeedbackKV[];
         finished: boolean;
@@ -139,15 +156,29 @@ interface FeedbackSinkOptions {
     log?: (...args: unknown[]) => void;
     /** 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`.
+     */
+    sendBeaconImpl?: (url: string, body: Blob | string) => boolean;
     /** Callback invocado cuando el backend devuelve un nuevo sessionId (primer POST). */
     onSessionId?: (id: string) => void;
 }
 /**
  * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/feedback`.
- * Fire-and-forget (no bloquea el flush); errores solo se loguean.
- * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta
- * y lo envía en los siguientes POSTs para que el backend agrupe todos los eventos
- * en un único registro de feedback.
+ *
+ * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta y lo
+ * envía en los siguientes POSTs para que el backend agrupe todos los eventos en un único
+ * registro de feedback.
+ *
+ * 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;
+ *  - 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.
  */
 declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
 
@@ -185,6 +216,14 @@ interface DeepdotsInitParams {
     storage?: KeyValueStorage;
     /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
     platform?: 'web' | 'android' | 'ios';
+    /**
+     * 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. */
     device?: DeviceInfo;
     /**
@@ -517,6 +556,11 @@ declare class DeepdotsPopups {
     private contact;
     /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
     private navStarted;
+    /**
+     * 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. */
@@ -529,6 +573,11 @@ declare class DeepdotsPopups {
     track(name: string, params?: Record<string, unknown>): void;
     /** User attributes para breakdowns (registration_status, pass_type, sector, pass_status…). */
     setUserAttributes(attributes: Record<string, string | number | boolean>): void;
+    /**
+     * Registra/actualiza una métrica (valor medible) → `feedback.metrics` del body.
+     * Persistente y sobrescribe por key. No-op si tracking off.
+     */
+    setMetric(key: string, value: string | number | boolean): void;
     /** Reporta un error del host (manejado o no) → evento `deepdots_app_crash`. No-op si tracking off. */
     reportError(error: unknown, options?: ReportErrorOptions): void;
     /** Engancha `global.ErrorUtils` de RN para capturar errores JS no manejados. No-op si tracking off. */
@@ -566,8 +615,14 @@ declare class DeepdotsPopups {
     onBackground(): void;
     /** 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;
+    }): void;
     /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
     private flushEngagement;
     private analyticsIdentity;