@magicfeedback/popup-sdk 1.7.1 → 1.8.0

package/dist/react-native.d.mts

@@ -286,6 +286,11 @@ interface PopupRenderOptions {
 interface PopupRenderer {
     /** Preparar recursos si aplica */
     init?(): void;
+    /**
+     * Traer por adelantado lo que la apertura necesitará, en idle. Opcional: solo lo implementan
+     * los renderers cuyo coste de apertura se paga delante del usuario.
+     */
+    preload?(): void;
     /** Mostrar popup */
     show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: (type: DeepdotsEventType, surveyId: string, data?: Record<string, unknown>) => void, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string, renderChrome?: boolean, options?: PopupRenderOptions): void;
     /** Ocultar popup */
@@ -533,7 +538,27 @@ declare class DeepdotsPopups {
     private showDefinition;
     private shouldShow;
     private matchesSegmentsLang;
+    /** `segments.path`: rutas donde el popup PUEDE mostrarse. Sin lista, en todas. */
     private matchesSegmentsPath;
+    /**
+     * `segments.excludedPaths`: rutas donde el popup NO debe mostrarse. Gana sobre
+     * `segments.path` (`path: ['/']` + `excludedPaths: ['/cart']` = en todas menos el
+     * carrito) y se aplica también cuando no hay `path` (= en todas menos las excluidas).
+     */
+    private isPathExcluded;
+    /**
+     * Compara UN candidato de `segments.path`/`segments.excludedPaths` con la ruta
+     * actual. Mismas reglas para incluir y para excluir:
+     *  - URL absoluta  → href completo exacto
+     *  - empieza por / → subcadena del href (así entran las rutas con hash: `/#/home`)
+     *  - resto         → pathname exacto
+     * Ignora entradas que no sean string: el backend puede colar un `null` en la lista
+     * y no puede tumbar la evaluación del trigger entero (mismo fallo que hubo con
+     * `segments.lang`).
+     */
+    private matchesPathCandidate;
+    /** href + pathname normalizados de la ruta a evaluar, o null si no hay `window.location`. */
+    private resolveCurrentLocation;
     private evaluateCooldown;
     private evaluateLegacyCondition;
     private hasCooldownElapsed;
@@ -652,23 +677,47 @@ interface ReactNativeRendererOptions {
     onShow?: (payload: ReactNativeSurveyPayload) => void;
     /** Se llama al cerrar el popup: desmonta el WebView. */
     onHide?: () => void;
+    /**
+     * Se llama cuando el survey ya está pintado dentro del WebView, o pasado el techo de espera.
+     *
+     * Sirve para no enseñar un WebView en blanco: monta el WebView en cuanto llegue `onShow` (fuera
+     * de pantalla o transparente) y ábrelo al recibir `onReady`. El HTML se revela solo de todas
+     * formas, así que el host que no lo use sigue funcionando igual.
+     */
+    onReady?: (payload: {
+        surveyId: string;
+    }) => void;
 }
 /**
  * Renderer de React Native: el SDK no puede pintar componentes RN, así que entrega el
  * HTML del survey al host (que lo monta en `react-native-webview`) y traduce los
  * mensajes del WebView a eventos de popup del SDK (→ `POST /sdk/popups`, Messaging #18–22).
  *
- * Uso:
+ * Uso: monta el WebView con `onShow` y enséñalo con `onReady`, para que el usuario no vea el
+ * WebView arrancando en blanco (motor + bundle del CDN + fetch del survey).
  * ```tsx
  * const renderer = new ReactNativePopupRenderer({
- *   onShow: (p) => setSurvey({ ...p, visible: true }),
- *   onHide: () => setSurvey((s) => ({ ...s, visible: false })),
+ *   onShow: (p) => setSurvey({ ...p, ready: false }),
+ *   onReady: () => setSurvey((s) => (s ? { ...s, ready: true } : s)),
+ *   onHide: () => setSurvey(null),
  * });
  * sdk.setRenderer(renderer);
  * // …
- * <WebView source={{ html: survey.html }}
- *          onMessage={(e) => renderer.handleMessage(e.nativeEvent.data)} />
+ * // ⚠️ Con `<Modal visible={survey.ready}>` esto NO funciona: React Native no monta los hijos
+ * // de un Modal cerrado, así que el WebView no empezaría a cargar y `ready` no llegaría nunca.
+ * // El WebView tiene que estar montado y solo invisible.
+ * {survey ? (
+ *   <View style={[StyleSheet.absoluteFill, { opacity: survey.ready ? 1 : 0 }]}
+ *         pointerEvents={survey.ready ? 'auto' : 'none'}>
+ *     <WebView source={{ html: survey.html }}
+ *              onMessage={(e) => renderer.handleMessage(e.nativeEvent.data)} />
+ *   </View>
+ * ) : null}
  * ```
+ *
+ * Quien prefiera no complicarse puede ignorar `onReady` y abrir su Modal en `onShow`: el HTML se
+ * revela solo igualmente, así que el usuario verá el contenedor del host unos cientos de ms antes
+ * que la tarjeta, pero nunca el spinner.
  */
 declare class ReactNativePopupRenderer implements PopupRenderer {
     private options;
@@ -676,10 +725,17 @@ declare class ReactNativePopupRenderer implements PopupRenderer {
     private onCloseFn;
     private currentSurveyId;
     private partialEmitted;
+    private readyEmitted;
+    private readyTimer;
     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, renderChrome?: boolean, options?: PopupRenderOptions): void;
     hide(): void;
+    /** Respaldo del aviso de listo por si el WebView no llega a ejecutar el HTML. */
+    private armReadyFallback;
+    private clearReadyFallback;
+    /** Idempotente: el WebView puede avisar a la vez que vence el respaldo. */
+    private emitReady;
     /**
      * El host la conecta al `onMessage` del WebView. Traduce los mensajes del survey a
      * eventos del SDK: primera interacción → `popup_clicked` (PARTIAL), completado →

package/dist/react-native.d.ts

@@ -286,6 +286,11 @@ interface PopupRenderOptions {
 interface PopupRenderer {
     /** Preparar recursos si aplica */
     init?(): void;
+    /**
+     * Traer por adelantado lo que la apertura necesitará, en idle. Opcional: solo lo implementan
+     * los renderers cuyo coste de apertura se paga delante del usuario.
+     */
+    preload?(): void;
     /** Mostrar popup */
     show(surveyId: string, productId: string, actions: PopupActions | undefined, emit: (type: DeepdotsEventType, surveyId: string, data?: Record<string, unknown>) => void, onClose: () => void, env?: string, userId?: string, style?: PopupStyle, sessionId?: string, miniService?: string, analyticsFeedbackSessionId?: string, renderChrome?: boolean, options?: PopupRenderOptions): void;
     /** Ocultar popup */
@@ -533,7 +538,27 @@ declare class DeepdotsPopups {
     private showDefinition;
     private shouldShow;
     private matchesSegmentsLang;
+    /** `segments.path`: rutas donde el popup PUEDE mostrarse. Sin lista, en todas. */
     private matchesSegmentsPath;
+    /**
+     * `segments.excludedPaths`: rutas donde el popup NO debe mostrarse. Gana sobre
+     * `segments.path` (`path: ['/']` + `excludedPaths: ['/cart']` = en todas menos el
+     * carrito) y se aplica también cuando no hay `path` (= en todas menos las excluidas).
+     */
+    private isPathExcluded;
+    /**
+     * Compara UN candidato de `segments.path`/`segments.excludedPaths` con la ruta
+     * actual. Mismas reglas para incluir y para excluir:
+     *  - URL absoluta  → href completo exacto
+     *  - empieza por / → subcadena del href (así entran las rutas con hash: `/#/home`)
+     *  - resto         → pathname exacto
+     * Ignora entradas que no sean string: el backend puede colar un `null` en la lista
+     * y no puede tumbar la evaluación del trigger entero (mismo fallo que hubo con
+     * `segments.lang`).
+     */
+    private matchesPathCandidate;
+    /** href + pathname normalizados de la ruta a evaluar, o null si no hay `window.location`. */
+    private resolveCurrentLocation;
     private evaluateCooldown;
     private evaluateLegacyCondition;
     private hasCooldownElapsed;
@@ -652,23 +677,47 @@ interface ReactNativeRendererOptions {
     onShow?: (payload: ReactNativeSurveyPayload) => void;
     /** Se llama al cerrar el popup: desmonta el WebView. */
     onHide?: () => void;
+    /**
+     * Se llama cuando el survey ya está pintado dentro del WebView, o pasado el techo de espera.
+     *
+     * Sirve para no enseñar un WebView en blanco: monta el WebView en cuanto llegue `onShow` (fuera
+     * de pantalla o transparente) y ábrelo al recibir `onReady`. El HTML se revela solo de todas
+     * formas, así que el host que no lo use sigue funcionando igual.
+     */
+    onReady?: (payload: {
+        surveyId: string;
+    }) => void;
 }
 /**
  * Renderer de React Native: el SDK no puede pintar componentes RN, así que entrega el
  * HTML del survey al host (que lo monta en `react-native-webview`) y traduce los
  * mensajes del WebView a eventos de popup del SDK (→ `POST /sdk/popups`, Messaging #18–22).
  *
- * Uso:
+ * Uso: monta el WebView con `onShow` y enséñalo con `onReady`, para que el usuario no vea el
+ * WebView arrancando en blanco (motor + bundle del CDN + fetch del survey).
  * ```tsx
  * const renderer = new ReactNativePopupRenderer({
- *   onShow: (p) => setSurvey({ ...p, visible: true }),
- *   onHide: () => setSurvey((s) => ({ ...s, visible: false })),
+ *   onShow: (p) => setSurvey({ ...p, ready: false }),
+ *   onReady: () => setSurvey((s) => (s ? { ...s, ready: true } : s)),
+ *   onHide: () => setSurvey(null),
  * });
  * sdk.setRenderer(renderer);
  * // …
- * <WebView source={{ html: survey.html }}
- *          onMessage={(e) => renderer.handleMessage(e.nativeEvent.data)} />
+ * // ⚠️ Con `<Modal visible={survey.ready}>` esto NO funciona: React Native no monta los hijos
+ * // de un Modal cerrado, así que el WebView no empezaría a cargar y `ready` no llegaría nunca.
+ * // El WebView tiene que estar montado y solo invisible.
+ * {survey ? (
+ *   <View style={[StyleSheet.absoluteFill, { opacity: survey.ready ? 1 : 0 }]}
+ *         pointerEvents={survey.ready ? 'auto' : 'none'}>
+ *     <WebView source={{ html: survey.html }}
+ *              onMessage={(e) => renderer.handleMessage(e.nativeEvent.data)} />
+ *   </View>
+ * ) : null}
  * ```
+ *
+ * Quien prefiera no complicarse puede ignorar `onReady` y abrir su Modal en `onShow`: el HTML se
+ * revela solo igualmente, así que el usuario verá el contenedor del host unos cientos de ms antes
+ * que la tarjeta, pero nunca el spinner.
  */
 declare class ReactNativePopupRenderer implements PopupRenderer {
     private options;
@@ -676,10 +725,17 @@ declare class ReactNativePopupRenderer implements PopupRenderer {
     private onCloseFn;
     private currentSurveyId;
     private partialEmitted;
+    private readyEmitted;
+    private readyTimer;
     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, renderChrome?: boolean, options?: PopupRenderOptions): void;
     hide(): void;
+    /** Respaldo del aviso de listo por si el WebView no llega a ejecutar el HTML. */
+    private armReadyFallback;
+    private clearReadyFallback;
+    /** Idempotente: el WebView puede avisar a la vez que vence el respaldo. */
+    private emitReady;
     /**
      * El host la conecta al `onMessage` del WebView. Traduce los mensajes del survey a
      * eventos del SDK: primera interacción → `popup_clicked` (PARTIAL), completado →