@magicfeedback/popup-sdk 1.7.0 → 1.7.2

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 */
@@ -576,6 +581,13 @@ declare class DeepdotsPopups {
     private safeParseUrl;
     private mapPopupTriggerType;
     private markSurveyProgress;
+    /**
+     * Rehidrata el estado de redisplay desde el storage. `answeredSurveys` se reconstruye
+     * desde las entradas COMPLETED: es exactamente lo que persiste `markSurveyAnswered`.
+     */
+    private loadPopupState;
+    /** Vuelca el estado de redisplay al storage. Sin storage (o bloqueado) degrada a memoria. */
+    private persistPopupState;
     private isPopupDefinition;
     private isPopupTrigger;
     private isPopupTriggerType;
@@ -645,23 +657,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;
@@ -669,10 +705,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 */
@@ -576,6 +581,13 @@ declare class DeepdotsPopups {
     private safeParseUrl;
     private mapPopupTriggerType;
     private markSurveyProgress;
+    /**
+     * Rehidrata el estado de redisplay desde el storage. `answeredSurveys` se reconstruye
+     * desde las entradas COMPLETED: es exactamente lo que persiste `markSurveyAnswered`.
+     */
+    private loadPopupState;
+    /** Vuelca el estado de redisplay al storage. Sin storage (o bloqueado) degrada a memoria. */
+    private persistPopupState;
     private isPopupDefinition;
     private isPopupTrigger;
     private isPopupTriggerType;
@@ -645,23 +657,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;
@@ -669,10 +705,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 →