@magicfeedback/popup-sdk 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,29 +1,183 @@
1
+ /**
2
+ * Identidad + sesión para el tracking de navegación (Fase 1).
3
+ * Implementa el "Contrato común Web+KMP".
4
+ *
5
+ * Modelo: el SDK gestiona el `user_id` (persistente). El `session_id` es propiedad
6
+ * del BACKEND: llega en la respuesta de `POST /sdk/popups` y se cachea; el backend
7
+ * cose sesiones por `user_id` + ventana. El SDK NO genera ni expira sesiones.
8
+ *
9
+ * Sin dependencias de DOM: recibe el storage y (opcionalmente) el reloj y el
10
+ * generador de uuid por inyección. El binding a `localStorage` vive en `createDefaultStorage`.
11
+ */
12
+ /** Store clave/valor mínimo (espejo conceptual del `KeyValueStorage` de KMP). */
13
+ interface KeyValueStorage {
14
+ getItem(key: string): string | null;
15
+ setItem(key: string, value: string): void;
16
+ removeItem(key: string): void;
17
+ }
18
+ /** Impl en memoria — usada en tests y como fallback sin `localStorage`. */
19
+ declare class InMemoryStorage implements KeyValueStorage {
20
+ private map;
21
+ getItem(key: string): string | null;
22
+ setItem(key: string, value: string): void;
23
+ removeItem(key: string): void;
24
+ }
25
+ /** Par clave/valor con el formato `NativeAnswer` que espera `@magicfeedback/native`. */
26
+ interface IdentityAnswer {
27
+ key: string;
28
+ value: string[];
29
+ }
30
+
31
+ /**
32
+ * Device info para el context de analytics (Technology #11–13).
33
+ *
34
+ * En Web enviamos `device_type` (heurística fiable) + `user_agent` crudo, y dejamos
35
+ * que el backend derive OS/modelo/navegador del UA (como hace GA) — el parseo de UA en
36
+ * cliente es frágil. `app_version` lo provee el cliente (una web no tiene versión de app
37
+ * nativa). En KMP las APIs nativas dan os_version/device_model reales.
38
+ */
39
+ interface DeviceInfo {
40
+ device_type: 'mobile' | 'tablet' | 'desktop';
41
+ os_version?: string;
42
+ device_model?: string;
43
+ app_version?: string;
44
+ user_agent?: string;
45
+ }
46
+
47
+ /**
48
+ * Capa de Analytics (eventos GA-style) — canal SEPARADO del feedback de survey.
49
+ *
50
+ * El feedback de survey se envía con `magicfeedback.send()`. La analítica de
51
+ * navegación/comportamiento (page views, mini-services, tasks/funnels, meaningful
52
+ * interactions, findability…) va por un ENDPOINT PROPIO, vinculada por `user_id`.
53
+ *
54
+ * De momento NO se hace la llamada: el `sink` por defecto hace `console.log` del
55
+ * payload exacto que se enviaría (dry-run), para poder verificarlo. Cuando el
56
+ * endpoint exista, se sustituye el sink por un POST.
57
+ */
58
+
59
+ interface AnalyticsEvent {
60
+ name: string;
61
+ timestamp: number;
62
+ params?: Record<string, unknown>;
63
+ }
64
+ interface AnalyticsEnvelope {
65
+ /** Clave pública del cliente (auth). */
66
+ publicKey?: string;
67
+ /** Id que vincula la analítica al usuario (el backend cose por aquí). */
68
+ userId: string | null;
69
+ /** Session id del backend si ya se conoce (puede ir null). */
70
+ sessionId: string | null;
71
+ context: {
72
+ platform: string;
73
+ language?: string;
74
+ /** Info de dispositivo (Technology #11–13). */
75
+ device?: DeviceInfo;
76
+ /** User attributes del cliente, usados para breakdowns (registration_status, pass_type, …). */
77
+ attributes: Record<string, string>;
78
+ };
79
+ events: AnalyticsEvent[];
80
+ }
81
+ type AnalyticsSink = (payload: AnalyticsEnvelope) => void;
82
+
83
+ /**
84
+ * Mapeo del envelope de analytics → body de `POST /sdk/feedback`.
85
+ *
86
+ * La analítica se envía como un Feedback del modelo del Surveys SDK, agrupado por una
87
+ * INTEGRACIÓN creada en la plataforma. Se manda en streaming con `completed:false` y
88
+ * `finished:false` (nunca se "cierra"); el backend cose por `sessionId` + `user_id`.
89
+ *
90
+ * Encoding (decisión 2026-06-22):
91
+ * - cada evento (dato recabado) → una `metric` {key: nombre_evento, value: JSON(timestamp + params)}
92
+ * - identidad (user_id) → `profile` como `external-user-id`
93
+ * - contexto (user_id, session_id, platform, language, device, attributes) → `metadata`
94
+ * - `answers` vacío
95
+ * - `text` vacío
96
+ */
97
+
98
+ interface AnalyticsKeys {
99
+ publicKey: string;
100
+ integration: string;
101
+ }
102
+ interface FeedbackKV {
103
+ key: string;
104
+ value: string;
105
+ }
106
+ interface AnalyticsFeedbackBody {
107
+ feedback: {
108
+ text: string;
109
+ answers?: FeedbackKV[];
110
+ metadata: FeedbackKV[];
111
+ metrics: FeedbackKV[];
112
+ profile?: FeedbackKV[];
113
+ finished: boolean;
114
+ };
115
+ publicKey: string;
116
+ integration: string;
117
+ completed: boolean;
118
+ finished?: boolean;
119
+ /** sessionId devuelto por el primer POST; permite que el backend agrupe todos los eventos en un solo registro. */
120
+ sessionId?: string;
121
+ }
122
+ declare function buildAnalyticsFeedbackBody(envelope: AnalyticsEnvelope, keys: AnalyticsKeys, feedbackSessionId?: string): AnalyticsFeedbackBody;
123
+ interface FeedbackSinkOptions {
124
+ /** Base URL del backend (api(.|-dev.)deepdots.com) ya resuelta por el entorno. */
125
+ baseUrl: string;
126
+ keys: AnalyticsKeys;
127
+ /** Logger opcional (gated por debug). */
128
+ log?: (...args: unknown[]) => void;
129
+ /** fetch inyectable (tests / RN). */
130
+ fetchImpl?: typeof fetch;
131
+ }
132
+ /**
133
+ * Sink real: transforma el envelope y hace `POST {baseUrl}/sdk/feedback`.
134
+ * Fire-and-forget (no bloquea el flush); errores solo se loguean.
135
+ * Stateful: cachea el `sessionId` que devuelve el backend en la primera respuesta
136
+ * y lo envía en los siguientes POSTs para que el backend agrupe todos los eventos
137
+ * en un único registro de feedback.
138
+ */
139
+ declare function createFeedbackSink(options: FeedbackSinkOptions): AnalyticsSink;
140
+
1
141
  /**
2
142
  * Configuration options for initializing the DeepdotsPopups SDK
3
143
  */
144
+
4
145
  interface DeepdotsInitParams {
5
146
  /** API key for authentication */
6
147
  apiKey?: string;
7
148
  /** Node environment: 'development' or 'production' */
8
149
  nodeEnv?: 'development' | 'production';
9
- /** Execution mode: 'server' or 'client' */
10
- mode?: 'server' | 'client';
11
150
  /** Enable debug logging */
12
151
  debug?: boolean;
13
- /** Lista de definiciones de popups precargadas */
14
- popups?: PopupDefinition[];
15
152
  /** Optional user id to send with popup events */
16
153
  userId?: string;
154
+ /** Starts tracking enabled (default) or disabled (e.g. until consent is granted). Equivalent to calling `setTrackingEnabled` after init. */
155
+ trackingEnabled?: boolean;
156
+ /** Host app version (for analytics device info / Technology #11). */
157
+ appVersion?: string;
158
+ /** Injectable persistent storage (RN: adapter over AsyncStorage). If missing, uses localStorage/in-memory. */
159
+ storage?: KeyValueStorage;
160
+ /** Platform used in the analytics envelope. Default is 'web'; in RN pass 'android'/'ios'. */
161
+ platform?: 'web' | 'android' | 'ios';
162
+ /** Injectable device info (RN: from react-native-device-info). If missing, it is derived from the browser. */
163
+ device?: DeviceInfo;
164
+ /**
165
+ * Analytics channel keys (`POST /sdk/feedback`). If provided, analytics is SENT
166
+ * to the configured integration; if missing, it stays in dry-run mode (console.log only).
167
+ */
168
+ analytics?: AnalyticsKeys;
169
+ /**
170
+ * Internal user attributes known only by the host (language, age, plan, ...), sent
171
+ * to the backend Contact for segmentation/targeting. Requires `userId`. Equivalent to calling
172
+ * `setContactAttributes` after init (sends only when values changed from the last sync).
173
+ */
174
+ contactAttributes?: Record<string, string | number | boolean>;
17
175
  }
18
176
  interface DeepdotsConfig {
19
177
  /** API key for authentication */
20
178
  apiKey?: string;
21
- /** Execution mode: 'server' or 'client' */
22
- mode?: 'server' | 'client';
23
179
  /** Enable debug logging */
24
180
  debug?: boolean;
25
- /** Lista de definiciones de popups precargadas */
26
- popups?: PopupDefinition[];
27
181
  /** Optional user id to send with popup events */
28
182
  userId?: string;
29
183
  }
@@ -40,17 +194,6 @@ interface TriggerConfig {
40
194
  /** Optional popup definition id (used to disambiguate repeated survey ids) */
41
195
  popupId?: string;
42
196
  }
43
- /**
44
- * Options for showing a popup
45
- */
46
- interface ShowOptions {
47
- /** Survey ID to display */
48
- surveyId: string;
49
- /** Product ID associated with the survey */
50
- productId: string;
51
- /** Additional data to pass with the survey */
52
- data?: Record<string, unknown>;
53
- }
54
197
  /**
55
198
  * Event types emitted by the SDK
56
199
  */
@@ -68,26 +211,26 @@ interface DeepdotsEvent {
68
211
  * Event listener callback
69
212
  */
70
213
  type EventListener = (event: DeepdotsEvent) => void;
71
- /** Tipo de trigger específico para definiciones de popup remotas */
214
+ /** Trigger type used by remote popup definitions */
72
215
  type PopupTriggerType = 'time_on_page' | 'scroll' | 'exit' | 'click' | 'event';
73
216
  type PopupTriggerConditionStatus = 'SHOWED' | 'PARTIAL' | 'COMPLETED';
74
217
  declare const POPUP_TRIGGER_CONDITION_STATUSES: PopupTriggerConditionStatus[];
75
- /** Condición adicional para la activación del popup */
218
+ /** Extra condition used to activate the popup */
76
219
  interface PopupTriggerCondition {
77
220
  answered: PopupTriggerConditionStatus;
78
221
  cooldownDays: number;
79
222
  }
80
- /** Trigger asociado a la definición del popup */
223
+ /** Trigger attached to the popup definition */
81
224
  interface PopupTrigger {
82
225
  type: PopupTriggerType;
83
226
  value: number | string;
84
227
  }
85
- /** Acción de aceptar (abrir encuesta) */
228
+ /** Accept action (open survey) */
86
229
  interface PopupActionAccept {
87
230
  label: string;
88
231
  surveyId: string;
89
232
  }
90
- /** Acción de declinar */
233
+ /** Decline action */
91
234
  interface PopupActionDecline {
92
235
  label: string;
93
236
  cooldownDays?: number;
@@ -96,14 +239,14 @@ interface PopupActionDecline {
96
239
  interface PopupActionStart {
97
240
  label: string;
98
241
  }
99
- /** Acción de completar (aceptar y completar encuesta automáticamente) */
242
+ /** Complete action (accept and auto-complete survey) */
100
243
  interface PopupActionComplete {
101
244
  label: string;
102
245
  surveyId: string;
103
246
  autoCompleteParams: Record<string, unknown>;
104
247
  cooldownDays?: number;
105
248
  }
106
- /** Conjunto de acciones disponibles en el popup */
249
+ /** Set of actions available in the popup */
107
250
  interface PopupActions {
108
251
  accept?: PopupActionAccept;
109
252
  decline?: PopupActionDecline;
@@ -111,20 +254,20 @@ interface PopupActions {
111
254
  start?: PopupActionStart;
112
255
  back?: PopupActionDecline;
113
256
  }
114
- /** Estilos configurables del popup */
257
+ /** Configurable popup styles */
115
258
  interface PopupStyle {
116
259
  theme: 'light' | 'dark';
117
260
  position: 'bottom' | 'bottom-right' | 'bottom-left' | 'top' | 'top-right' | 'top-left' | 'center';
118
- /** @deprecated No usado por el SDK — solo se conserva por compatibilidad con la API */
261
+ /** @deprecated Not used by the SDK; kept only for API compatibility */
119
262
  imageUrl?: string | null;
120
263
  }
121
- /** Segmentos o targeting para mostrar el popup */
264
+ /** Segments/targeting rules for showing the popup */
122
265
  interface PopupSegments {
123
266
  lang?: string[];
124
267
  path?: string[];
125
268
  [key: string]: unknown;
126
269
  }
127
- /** Definición completa de un popup */
270
+ /** Full popup definition */
128
271
  interface PopupDefinition {
129
272
  id: string;
130
273
  title: string;
@@ -142,10 +285,59 @@ interface PopupRenderer {
142
285
  /** Preparar recursos si aplica */
143
286
  init?(): void;
144
287
  /** Mostrar popup */
145
- 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): void;
288
+ 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): void;
146
289
  /** Ocultar popup */
147
290
  hide(): void;
148
291
  }
292
+ /** Renderer que no hace nada (SSR / entornos sin DOM) */
293
+ declare class NoopPopupRenderer implements PopupRenderer {
294
+ show(): void;
295
+ hide(): void;
296
+ }
297
+ /** Renderer para navegadores usando la implementación actual basada en renderPopup */
298
+ declare class BrowserPopupRenderer implements PopupRenderer {
299
+ private container;
300
+ private visible;
301
+ init(): void;
302
+ 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): void;
303
+ hide(): void;
304
+ }
305
+ /** Factoría para obtener renderer por defecto */
306
+ declare function createDefaultRenderer(): PopupRenderer;
307
+
308
+ /** Valor de un atributo de contact (info interna del usuario que solo conoce el host). */
309
+ type ContactAttributeValue = string | number | boolean;
310
+ type ContactAttributes = Record<string, ContactAttributeValue>;
311
+ /** Body de `POST /sdk/popups/contact`. */
312
+ interface ContactBody {
313
+ publicKey: string;
314
+ userId: string;
315
+ userAttributes: ContactAttributes;
316
+ }
317
+ interface ContactManagerOptions {
318
+ storage: KeyValueStorage;
319
+ publicKey: string;
320
+ userId: string;
321
+ /** Envío real (inyectable para tests): hace el `POST /sdk/popups/contact`. */
322
+ post: (body: ContactBody) => Promise<void>;
323
+ }
324
+ /**
325
+ * Gestiona los atributos de contact del usuario identificado (`userId` del init).
326
+ * Solo envía cuando cambian respecto a lo último persistido en storage, para ahorrar
327
+ * peticiones (el host puede llamar `setAttributes` en cada identificación sin miedo).
328
+ */
329
+ declare class ContactManager {
330
+ private readonly storage;
331
+ private readonly publicKey;
332
+ private readonly userId;
333
+ private readonly post;
334
+ constructor(options: ContactManagerOptions);
335
+ /**
336
+ * Envía los atributos si cambiaron respecto a lo último enviado.
337
+ * @returns `true` si se envió, `false` si no hubo cambios.
338
+ */
339
+ setAttributes(attributes: ContactAttributes): Promise<boolean>;
340
+ }
149
341
 
150
342
  /**
151
343
  * Main class for managing survey popups
@@ -167,20 +359,72 @@ declare class DeepdotsPopups {
167
359
  private deferredExitTimers;
168
360
  private baseUrl;
169
361
  private env;
362
+ /** Identidad + sesión (Fase 1 tracking). Null hasta init(). */
363
+ private tracking;
364
+ /** Capa de analytics (canal separado del feedback). Null hasta init(). */
365
+ private analytics;
366
+ /** Observador de navegación (Fase 2): emite page_view por el canal de analytics. */
367
+ private navObserver;
368
+ /** Tiempo activo (engagement time, #8). */
369
+ private engagement;
370
+ /** Atributos internos del usuario identificado → POST /sdk/popups/contact. Null si no hay userId. */
371
+ private contact;
372
+ /** Marca si ya se inició la navegación manual (setScreen) — para RN sin History API. */
373
+ private navStarted;
170
374
  /** Initialize the SDK with configuration */
171
375
  init(config: DeepdotsInitParams): void;
376
+ /** User id actual (generado por el SDK o provisto por el cliente). Null si tracking off. */
377
+ getUserId(): string | null;
378
+ /** Session id de navegación actual. Null si tracking off. */
379
+ getSessionId(): string | null;
380
+ /** Activa/desactiva el tracking (identidad + sesión + analytics). Kill-switch del contrato §7bis. */
381
+ setTrackingEnabled(enabled: boolean): void;
382
+ /** Registra un evento de analítica (modelo GA: nombre + params). No-op si tracking off. */
383
+ track(name: string, params?: Record<string, unknown>): void;
384
+ /** User attributes para breakdowns (registration_status, pass_type, sector, pass_status…). */
385
+ setUserAttributes(attributes: Record<string, string | number | boolean>): void;
386
+ /**
387
+ * Info interna del usuario que solo conoce el host (idioma, edad, plan…), persistida en el
388
+ * Contact del backend para segmentación/targeting de popups. Identificada por el `userId` del
389
+ * init. Solo envía si los atributos cambiaron (diff en storage). No-op si tracking off o sin userId.
390
+ * @returns `true` si se envió al backend, `false` si no hubo cambios o está deshabilitado.
391
+ */
392
+ setContactAttributes(attributes: ContactAttributes): Promise<boolean>;
393
+ /** Marca el inicio de un mini-service; etiqueta los eventos siguientes. No-op si tracking off. */
394
+ enterMiniService(name: string, entryPointType?: string): void;
395
+ /** Cierra el mini-service activo (emite `mini_service_exit` con duración, #27). No-op si tracking off. */
396
+ exitMiniService(): void;
397
+ /** Findability (#31/#35): registra una búsqueda. `has_results` se deriva de `resultsCount`. */
398
+ trackSearch(query: string, resultsCount: number, params?: Record<string, unknown>): void;
399
+ /** Findability friction (#34/#35): señal de fricción con su `friction_topic`. */
400
+ trackFindabilityFriction(frictionTopic: string, params?: Record<string, unknown>): void;
401
+ /** Funnel: un paso del embudo, correlacionado por `taskId`. El backend reconstruye conversión/drop-off/tiempo. */
402
+ trackFunnelStep(funnel: string, step: string, taskId: string, params?: Record<string, unknown>): void;
403
+ /**
404
+ * Navegación MANUAL (entornos sin History API, p. ej. React Native con React Navigation).
405
+ * El host la llama en cada cambio de pantalla; emite `page_view` al salir de la anterior.
406
+ */
407
+ setScreen(name: string): void;
408
+ /** App a foreground (RN: AppState 'active'): reanuda el engagement time. */
409
+ onForeground(): void;
410
+ /**
411
+ * App a background (RN: AppState 'background'): cierra pantalla actual (page_view),
412
+ * mini-service (mini_service_exit), emite engagement y hace flush del lote.
413
+ */
414
+ onBackground(): void;
415
+ /** Payload que se ENVIARÍA al endpoint de analytics (no envía ni vacía el buffer). */
416
+ previewAnalytics(): AnalyticsEnvelope;
417
+ /** Envía (hoy dry-run → console.log) el lote acumulado de analytics y vacía el buffer. */
418
+ flushAnalytics(): void;
419
+ /** Emite un evento `user_engagement` con el tiempo activo acumulado (#8). */
420
+ private flushEngagement;
421
+ private analyticsIdentity;
422
+ /** Flush automático al ocultar/cerrar la página (no perder el lote pendiente). */
423
+ private setupAnalyticsFlush;
172
424
  /** Enable auto-launch functionality with configured triggers */
173
425
  autoLaunch(): void;
174
426
  /** Inicia los triggers configurados */
175
427
  private startTriggers;
176
- /** Show a popup immediately (supports legacy ShowOptions and new PopupDefinition) */
177
- show(options: PopupDefinition | {
178
- surveyId: string;
179
- productId: string;
180
- data?: Record<string, unknown>;
181
- }): void;
182
- /** Mostrar popup por id de definición (usa surveyId interno) */
183
- showByPopupId(popupId: string): void;
184
428
  /** Configure triggers for auto-launching popups (manual) */
185
429
  configureTriggers(triggers: TriggerConfig[]): void;
186
430
  /** Deriva triggers desde las definiciones de popup */
@@ -209,6 +453,8 @@ declare class DeepdotsPopups {
209
453
  private setDeferredExitQueue;
210
454
  /** Fetch al servidor para obtener popups */
211
455
  private fetchPopupsFromServer;
456
+ /** Envía los atributos de contact a la API (`POST /sdk/popups/contact`). */
457
+ private postContact;
212
458
  /** Notifica eventos de popup a la API */
213
459
  private postPopupEvent;
214
460
  /** Add an event listener */
@@ -245,4 +491,118 @@ declare class DeepdotsPopups {
245
491
  private validatePopupDefinitions;
246
492
  }
247
493
 
248
- export { type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, DeepdotsPopups, type EventListener, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, type ShowOptions, type TriggerConfig };
494
+ type EmitFn = (type: DeepdotsEventType, surveyId: string, data?: Record<string, unknown>) => void;
495
+ /** Payload que recibe el host para montar el WebView del survey. */
496
+ interface ReactNativeSurveyPayload {
497
+ surveyId: string;
498
+ productId: string;
499
+ /** HTML autocontenido para `<WebView source={{ html }}>`. */
500
+ html: string;
501
+ }
502
+ interface ReactNativeRendererOptions {
503
+ /** Se llama al mostrar un popup: monta el WebView con `payload.html`. */
504
+ onShow?: (payload: ReactNativeSurveyPayload) => void;
505
+ /** Se llama al cerrar el popup: desmonta el WebView. */
506
+ onHide?: () => void;
507
+ }
508
+ /**
509
+ * Renderer de React Native: el SDK no puede pintar componentes RN, así que entrega el
510
+ * HTML del survey al host (que lo monta en `react-native-webview`) y traduce los
511
+ * mensajes del WebView a eventos de popup del SDK (→ `POST /sdk/popups`, Messaging #18–22).
512
+ *
513
+ * Uso:
514
+ * ```tsx
515
+ * const renderer = new ReactNativePopupRenderer({
516
+ * onShow: (p) => setSurvey({ ...p, visible: true }),
517
+ * onHide: () => setSurvey((s) => ({ ...s, visible: false })),
518
+ * });
519
+ * sdk.setRenderer(renderer);
520
+ * // …
521
+ * <WebView source={{ html: survey.html }}
522
+ * onMessage={(e) => renderer.handleMessage(e.nativeEvent.data)} />
523
+ * ```
524
+ */
525
+ declare class ReactNativePopupRenderer implements PopupRenderer {
526
+ private options;
527
+ private emitFn;
528
+ private onCloseFn;
529
+ private currentSurveyId;
530
+ private partialEmitted;
531
+ constructor(options?: ReactNativeRendererOptions);
532
+ init(): void;
533
+ show(surveyId: string, productId: string, _actions: PopupActions | undefined, emit: EmitFn, onClose: () => void, env?: string, userId?: string, _style?: PopupStyle, sessionId?: string, miniService?: string): void;
534
+ hide(): void;
535
+ /**
536
+ * El host la conecta al `onMessage` del WebView. Traduce los mensajes del survey a
537
+ * eventos del SDK: primera interacción → `popup_clicked` (PARTIAL), completado →
538
+ * `survey_completed` (COMPLETED) y cierra el popup.
539
+ */
540
+ handleMessage(raw: string): void;
541
+ }
542
+
543
+ /**
544
+ * Construye un HTML autocontenido que renderiza el survey de `@magicfeedback/native`
545
+ * dentro de un WebView (React Native). Carga el bundle desde CDN, crea el form con la
546
+ * identidad inyectada (`profile`/`metadata`) y reenvía los eventos del survey al host
547
+ * vía el puente de react-native-webview: `window.ReactNativeWebView.postMessage`.
548
+ *
549
+ * Mensajes emitidos (JSON `{name, payload}`): `loaded`, `before_submit`, `after_submit`,
550
+ * `survey_completed`, `back`, `popup_close`.
551
+ */
552
+ interface BuildSurveyHtmlOptions {
553
+ surveyId: string;
554
+ productId: string;
555
+ env?: string;
556
+ profile?: IdentityAnswer[];
557
+ metadata?: IdentityAnswer[];
558
+ version?: string;
559
+ }
560
+ declare function buildSurveyHtml(opts: BuildSurveyHtmlOptions): string;
561
+
562
+ /**
563
+ * Auto-wiring de React Native: concentra TODA la configuración en el SDK para que el
564
+ * host solo tenga que envolver su app en un `<DeepdotsProvider config={...}>`.
565
+ *
566
+ * No importa React ni librerías nativas: el host (o el Provider) le pasa los módulos
567
+ * nativos que tenga instalados (MMKV, device-info, AppState). Todo es opcional y degrada
568
+ * con elegancia (sin MMKV → in-memory; sin device-info → sin device info).
569
+ */
570
+
571
+ /** Forma mínima de `react-native-mmkv` (instancia MMKV). */
572
+ interface MmkvLike {
573
+ getString(key: string): string | undefined | null;
574
+ set(key: string, value: string): void;
575
+ delete(key: string): void;
576
+ }
577
+ /** Forma mínima de `react-native-device-info`. */
578
+ interface DeviceInfoLike {
579
+ isTablet?: () => boolean;
580
+ getSystemVersion?: () => string;
581
+ getDeviceId?: () => string;
582
+ getVersion?: () => string;
583
+ }
584
+ /** Forma mínima de `AppState` de react-native. */
585
+ interface AppStateLike {
586
+ addEventListener(type: 'change', listener: (state: string) => void): {
587
+ remove: () => void;
588
+ } | void;
589
+ }
590
+ interface ReactNativeSetupDeps {
591
+ mmkv?: MmkvLike | null;
592
+ deviceInfo?: DeviceInfoLike | null;
593
+ appState?: AppStateLike | null;
594
+ platform?: 'web' | 'android' | 'ios';
595
+ renderer?: PopupRenderer;
596
+ }
597
+ /** Adaptador KeyValueStorage (síncrono) sobre una instancia de MMKV. */
598
+ declare function mmkvStorage(mmkv: MmkvLike): KeyValueStorage;
599
+ /** Recoge device info desde react-native-device-info (Technology #11–13). */
600
+ declare function collectRnDevice(d: DeviceInfoLike): DeviceInfo;
601
+ /**
602
+ * Configura el SDK para React Native en una sola llamada: storage persistente (MMKV),
603
+ * device info, platform, init y lifecycle (AppState → onForeground/onBackground).
604
+ * Devuelve una función de limpieza (quita el listener de AppState).
605
+ */
606
+ declare function setupReactNative(sdk: DeepdotsPopups, config: DeepdotsInitParams, deps?: ReactNativeSetupDeps): () => void;
607
+
608
+ export { type AnalyticsFeedbackBody, type AnalyticsKeys, type AppStateLike, BrowserPopupRenderer, type ContactAttributeValue, type ContactAttributes, type ContactBody, ContactManager, type DeepdotsConfig, type DeepdotsEvent, type DeepdotsEventType, DeepdotsPopups, type DeviceInfo, type DeviceInfoLike, type EventListener, type FeedbackKV, InMemoryStorage, type KeyValueStorage, type MmkvLike, NoopPopupRenderer, POPUP_TRIGGER_CONDITION_STATUSES, type PopupDefinition, type PopupRenderer, type PopupTrigger, type PopupTriggerCondition, type PopupTriggerConditionStatus, ReactNativePopupRenderer, type ReactNativeRendererOptions, type ReactNativeSetupDeps, type ReactNativeSurveyPayload, type TriggerConfig, buildAnalyticsFeedbackBody, buildSurveyHtml, collectRnDevice, createDefaultRenderer, createFeedbackSink, mmkvStorage, setupReactNative };