apps/mobile_app/docs/analytics-catalog-technical.md

# Catálogo de Analíticas — SaveFamily (módulo legacy)

> Documento para el equipo de Marketing. Describe cada evento de Firebase
> Analytics que la app envía desde el módulo legacy: qué significa, cuándo se
> dispara, qué parámetros trae, y qué insight ofrece.
>
> **Ambiente:** Eventos visibles en vivo en Firebase Console Analytics
> **DebugView** (para builds debug/profile con el flag de debug activado).
> Los reportes históricos están en **Realtime**, **Engagement Events** y
> **Engagement Pages and screens**.
>
> **Parámetro común:** Cada evento incluye automáticamente un parámetro
> `consent_status` (`true` / `false`) para permitir filtrado por
> consentimiento GDPR cuando corresponda.

---

## Índice

1. [User Properties (propiedades del usuario)](#user-properties)
2. [Screen Views (vistas de pantalla automáticas)](#screen-views)
3. [Autenticación (`legacy_auth_*`)](#autenticación)
4. [Cuenta (`legacy_account_*`)](#cuenta)
5. [Dispositivo — Setup / alta (`legacy_device_setup_*`)](#dispositivo--setup)
6. [Dispositivo — Funciones (`legacy_device_*`)](#dispositivo--funciones)
7. [Contactos del dispositivo (`legacy_contacts_*`)](#contactos-del-dispositivo)
8. [Ajustes (`legacy_settings_*`)](#ajustes)
9. [Soporte (`legacy_support_*`)](#soporte)
10. [Onboarding (`legacy_onboarding_*`)](#onboarding)
11. [Panel principal (`legacy_control_panel_*`)](#panel-principal)
12. [Ubicación y mapa (`legacy_location_*`)](#ubicación-y-mapa)

---

## User Properties

Son propiedades que se setean una sola vez por usuario (al hacer login) y
sirven para **segmentar** a los usuarios en los reportes. Cualquier evento
puede cruzarse por estas dimensiones en Firebase Analytics.

| Propiedad | Descripción | Valores ejemplo | Cuándo se setea |
|---|---|---|---|
| `env` | Ambiente de la app | `development`, `staging`, `production` | Al arrancar la app |
| `user_id` (interna) | Identificador único del usuario | UUID del backend | Al confirmar el login (después del 2FA) |
| `user_role` | Rol del usuario en el backend | `client`, `admin`, etc. | Al login |
| `user_language` | Idioma preferido del usuario | `es`, `en`, `fr`, `de`, `it`, `pt` | Al login |
| `user_signup_date` | Fecha de creación de la cuenta (ISO 8601 UTC) | `2024-04-07T10:34:42.000Z` | Al login |
| `user_has_phone` | Si tiene teléfono registrado | `true` / `false` | Al login |
| `user_has_api_key` | Si tiene una API key asignada (usuario técnico) | `true` / `false` | Al login |

> **Nota futura:** Cuando se lance el plan premium, se agregará
> `user_plan` (`free` / `premium` / `family`) para segmentar la base por
> plan.

---

## Screen Views

Cada vez que el usuario navega a una pantalla, Firebase recibe un evento
automático `screen_view` con el parámetro `screen_name` igual al nombre
lógico de la ruta (no el nombre de clase Flutter).

**Esto se captura automáticamente**, sin instrumentación manual en cada
pantalla, mediante un listener del router. **También captura los cambios de
tab del bottom navigation** (home device functions mapa chat).

### Pantallas del módulo legacy que se trackean

| Screen name | Pantalla |
|---|---|
| `splash` | Pantalla de carga inicial |
| `legacy_onboarding` | Intro/onboarding |
| `legacy_login` | Pantalla de login |
| `legacy_signup` | Alta de cuenta |
| `legacy_recover_password` | Recuperación de contraseña |
| `legacy_device_setup` | Wizard de alta de reloj/dispositivo |
| `legacy_request_link_phone` | Inicio de vinculación de teléfono |
| `legacy_verify_link_phone_code` | Verificación del código OTP |
| `control_panel` | Dashboard principal (home del legacy) |
| `customer_service` | Pantalla de soporte |
| `account_settings` | Menú de cuenta |
| `personal_data` | Editar datos personales |
| `change_password` | Cambiar contraseña |
| `linked_devices` | Dispositivos vinculados a la cuenta |
| `app_users` | Sub-usuarios de la app |
| `delete_account` | Flujo de eliminación de cuenta |
| `device_management` | Menú de gestión del dispositivo |
| `scheduled_activities` | Actividades programadas |
| `contacts` | Contactos del dispositivo |
| `edit_contact` | Editar un contacto |
| `health` | Salud (ritmo cardíaco, SpO2) |
| `remote_connection` | Conexión remota (cámara, llamada) |
| `locate_device` | Localizar dispositivo |
| `rewards` | Recompensas |
| `activity_meter` | Medidor de actividad (pasos) |
| `apps_use` | Uso de apps |
| `volume_control` | Control de volumen |
| `call_history` | Historial de llamadas |
| `background_image` | Imagen de fondo del dispositivo |
| `legacy_location` | Mapa de ubicación |
| `legacy_chat` | Chat (placeholder) |
| `settings` | Menú de ajustes |
| `alarm` | Alarmas |
| `remote_management` | Gestión remota |
| `sos_agenda` | Contactos SOS |
| `sound` | Sonido del dispositivo |
| `sync_clock` | Sincronización de reloj |
| `app_store` | Gestión de apps instaladas |
| `battery` | Batería / modo nocturno |
| `block_phone` | Bloqueo de teléfono (whitelist) |
| `disable_functions` | Desactivar funciones (teclado, GPS) |
| `language` | Idioma del dispositivo |
| `legacy_notifications` | Notificaciones del dispositivo |
| `remote_on_off` | Encendido/apagado remoto |
| `alerts` | Alertas |
| `timezone` | Zona horaria |
| `wifi_settings` | Configuración WiFi |

**Insight para marketing:** Con estas screen_view podés construir funnels
(ej: `legacy_login control_panel device_management locate_device`) y
medir tiempos entre pantallas, rebotes y pantallas más visitadas.

---

## Autenticación

Prefijo `legacy_auth_*` — cubre login, 2FA, signup, recuperación de
contraseña, vinculación de teléfono y logout.

### Login

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_auth_login_attempt` | El usuario pulsa "Iniciar sesión" después de validar el formulario en el cliente. | — | Tope del funnel de login. Usar como base del "100 %" del funnel. |
| `legacy_auth_login_success` | El backend aceptó email + contraseña. Aún falta el 2FA. | — | Credenciales válidas. Usar para medir la calidad de la contraseña/email. |
| `legacy_auth_login_failure` | El backend rechazó las credenciales o hubo un error de red. | `reason` (mensaje de error) | Fricción. Analizar los `reason` más frecuentes para detectar problemas. |

### 2FA (doble factor)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_auth_2fa_requested` | El backend envió el código 2FA al usuario. | — | Usuario pasó el primer paso del login. |
| `legacy_auth_2fa_verified` | El código 2FA fue verificado y la sesión está activa. | — | Login exitoso. Fin del funnel de login. |
| `legacy_auth_2fa_failure` | El código 2FA fue rechazado (incorrecto, expirado). | `reason` | Fricción en el 2FA. Si es muy alto, puede indicar problemas con la entrega del código. |
| `legacy_auth_2fa_resend` | El usuario pidió reenviar el código. | — | Indica que no le llegó el primero. Útil para medir problemas de entrega. |

### Signup

El signup es un wizard de **3 pasos** (`step_index` 0, 1, 2). Los eventos
de step permiten construir el funnel detallado del alta.

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_auth_signup_started` | El usuario envió el formulario final (submit del paso 2). | — | Top del funnel de request al backend. |
| `legacy_auth_signup_completed` | El backend creó la cuenta exitosamente. | — | Conversión de nueva cuenta. |
| `legacy_auth_signup_failed` | Error en el alta (email ya existe, datos inválidos, error de red). | `reason` | Drop-off del signup. Analizar `reason` para ver si hay patrones. |
| `legacy_auth_signup_step_completed` | El usuario avanzó a un paso siguiente (validación pasó). | `step_index` (0, 1, 2) — el paso que JUSTO terminó | Funnel interno del signup. Permite ver cuántos completan paso 0, 1, 2. |
| `legacy_auth_signup_step_back` | El usuario tocó "atrás" dentro del wizard. | `step_index` — el paso del que vuelve | Indica que el usuario quiere corregir algo — fricción. |
| `legacy_auth_signup_step_validation_failed` | El usuario tocó "siguiente" pero la validación del formulario lo rechazó. | `step_index` | **Muy valioso:** dice en qué paso hay más problemas de validación. Si step 0 tiene muchos fails, puede ser el email; step 1 puede ser la dirección; etc. |

### Recuperación de contraseña

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_auth_password_reset_requested` | El usuario inició el flujo de recuperar contraseña. | — | Fricción: alguien no recuerda su contraseña. |
| `legacy_auth_password_reset_email_sent` | El backend confirmó el envío del email de recuperación. | — | Confirma que el email salió. Cruzar con `reset_requested` para medir fallas. |
| `legacy_auth_password_reset_completed` | El usuario guardó la nueva contraseña exitosamente. | — | **Conversión final** del funnel de recuperación. |
| `legacy_auth_password_reset_failed` | Error al intentar guardar la nueva contraseña. | `reason` (`unequal_passwords`, `too_short`, `no_capitals`, `no_numbers`, `no_special_chars`, o mensaje del backend) | Permite ver qué reglas de validación molestan más a los usuarios. |

### Vinculación de teléfono

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_auth_link_phone_code_requested` | El usuario envió su número y pidió el código OTP. | — | Inicio del flujo de linking. |
| `legacy_auth_link_phone_code_request_failed` | Falló el pedido del código al backend. | `reason` | Fricción inicial. |
| `legacy_auth_link_phone_code_verified` | El código OTP fue verificado con éxito. | — | Número vinculado. |
| `legacy_auth_link_phone_code_verification_failed` | Falló la verificación (código incorrecto o expirado). | `reason` | Fricción en el segundo paso. |

### Logout

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_auth_logout` | El usuario cerró sesión y la app limpió la sesión local. | — | Señal de fin de sesión. Cruzar con duración de sesión para ver patrones de uso. |

---

## Cuenta

Prefijo `legacy_account_*` — cubre edición de perfil, contraseña,
dispositivos vinculados, usuarios de la app y **eliminación de cuenta
(señal crítica de churn)**.

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_account_personal_data_edited` | El usuario guardó cambios en sus datos personales (nombre, apellido, teléfono). | — | Engagement con la cuenta. |
| `legacy_account_password_changed` | Cambio de contraseña exitoso. | — | Señal de buen hábito de seguridad. |
| `legacy_account_password_change_failed` | El cambio de contraseña falló. | `reason` | Fricción. |
| `legacy_account_linked_device_unlinked` | El usuario quitó un dispositivo vinculado de su cuenta. | — | Posible señal temprana de desuso del dispositivo. |
| `legacy_account_linked_device_renamed` | El usuario renombró un dispositivo vinculado (editó el carrier name). | — | Personalización / engagement con la gestión de dispositivos. |
| `legacy_account_app_user_delete_triggered` | El usuario tocó "eliminar" en la pantalla de app users. | — |  Nota técnica: la implementación actual borra al usuario logueado (parece ser placeholder). El evento se mantiene para medir demanda del feature. |
| `legacy_account_deletion_initiated` |  **CHURN SIGNAL** — El usuario entró al flujo "Eliminar cuenta". | — | Top del funnel de churn. |
| `legacy_account_deletion_confirmed` | El usuario confirmó la eliminación y la API call está en progreso. | — | El usuario quiere realmente irse. |
| `legacy_account_deletion_completed` | El backend confirmó la eliminación. | — | Usuario perdido. |
| `legacy_account_deletion_cancelled` | El usuario canceló antes de confirmar la eliminación. | — | Save: el usuario se arrepintió. Útil para medir efectividad de pantallas de retención. |

---

## Dispositivo — Setup

Prefijo `legacy_device_setup_*` — **el momento aha del producto**: vincular
un reloj/dispositivo del hijo a la cuenta del padre/madre.

### Funnel del wizard

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_setup_started` | El usuario entró al wizard de alta de dispositivo. | — | Top del funnel de activación. |
| `legacy_device_setup_step_completed` | El usuario completó un paso del wizard. | `step` (`intro`, `link_info`, `scan_watch`, `profile`), `duration_seconds` (cuánto tardó en ese paso) | Permite ver dónde se abandona más el wizard **Y cuánto tiempo pasan los usuarios en cada paso** — fricción directa. |
| `legacy_device_setup_completed` | El dispositivo se creó exitosamente y está vinculado. | `child_gender` (M/F/other), `relation_type` (mother/father/etc), `child_age_years` | **Conversión de activación + demográficos del usuario final**. Marketing puede construir **personas reales** con estos 3 params: género, edad y relación con el adulto que compró. |
| `legacy_device_setup_failed` | Falló un paso del wizard. | `at_step` (en qué paso falló), `reason` (error) | Señal para el equipo técnico de dónde hay problemas. |
| `legacy_device_setup_cancelled` | El usuario volvió atrás y abandonó el wizard. | `at_step` | Drop-off del wizard. |

### Entrada del código del reloj (QR vs. manual)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_setup_qr_scanned` | El usuario escaneó exitosamente el código QR del reloj. | — | Método "rápido". Si su ratio baja, el QR scanner puede estar fallando. |
| `legacy_device_setup_manual_code_entered` | El usuario avanzó con el código tipeado manualmente (no escaneó). | — | Fallback. Si crece mucho el ratio vs QR, invertir en mejorar la UX del scanner. |

### Familias con múltiples hijos

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_setup_reset_for_new_kid` | Después de terminar un alta, el usuario tocó "agregar otro hijo". | — | **Señal de familia con múltiples hijos**. Estos usuarios típicamente tienen mayor retention y LTV — son el mejor segmento. |

---

## Dispositivo — Funciones

Prefijo `legacy_device_*` — acciones sobre el dispositivo ya vinculado.
Mide qué features del producto se usan más.

### Localización del dispositivo (comando "find")

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_locate_requested` | El usuario pulsó el botón de localizar (intento). | — | Uso del feature principal del producto. Top del mini-funnel de localización. |
| `legacy_device_locate_success` | El comando de localizar fue enviado con éxito al backend. | — | El dispositivo va a sonar. Conversión del mini-funnel. |
| `legacy_device_locate_failure` | El comando de localizar falló (error del backend o de red). | `reason` | Problema técnico al localizar. Drop-off del mini-funnel. |

### Conexión remota (cámara + llamadas)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_remote_connection_started` | El usuario entró a la pantalla de conexión remota. | — | Intención de interactuar remotamente. |
| `legacy_device_remote_connection_photo_taken` | El usuario pidió una foto de la cámara remota. | — | Feature avanzada. Permite medir uso de la cámara del reloj. |
| `legacy_device_remote_connection_call_initiated` | El usuario inició una llamada bidireccional. | — | Feature crítica: llamar al niño. |
| `legacy_device_remote_connection_picture_viewed` | El usuario navegó entre fotos de la cámara remota. | `direction` (`next`, `prev`, `direct`) | Engagement con la galería: cuántas fotos revisa el padre después de pedirlas. |

### Volumen del dispositivo

Cada envío del formulario dispara **un evento por tipo de volumen que
efectivamente cambió** (media, ringtone, alarm) — si el usuario movió solo
el media, solo se manda ese. Permite medir qué tipo de sonido configuran
más los padres.

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_volume_control_changed` | El usuario guardó un cambio de volumen en el dispositivo, se emite 1 vez por cada tipo modificado. | `type` (`media`, `ringtone`, `alarm`), `level` (0-100) | Configuración. Cruzar `type` para ver cuál se ajusta más. |

### Imagen de fondo del reloj

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_background_image_changed` | El usuario seleccionó una imagen existente como fondo. | — | Personalización. |
| `legacy_device_background_image_uploaded` | El usuario subió una foto personal como fondo. | — | Alta personalización — indicador de engagement. |

### Actividades programadas (alarmas personalizadas del dispositivo)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_scheduled_activity_added` | El usuario agregó una actividad programada. | `week_day` (0-6, 0 = domingo), `period` (`HH:mm-HH:mm`) | **Dato muy útil:** permite ver qué horarios programan los padres (desayuno, colegio, deberes, etc) y qué días. |
| `legacy_device_scheduled_activity_updated` | El usuario editó una actividad programada. | `week_day`, `period` | Refinamiento de configuración. |
| `legacy_device_scheduled_activity_removed` | El usuario eliminó una actividad programada. | — | |

### Recompensas

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_rewards_granted` | El usuario asignó minutos de recompensa al dispositivo. | `amount` (cantidad de minutos) | Gamificación / recompensas de uso. |

### Podómetro (Activity Meter)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_activity_pedometer_toggled` | El usuario activó/desactivó el contador de pasos. | `enabled` (`true` / `false`) | |
| `legacy_device_activity_meter_time_range_changed` | El usuario cambió el rango de fechas en la pantalla de pasos. | `range` (`today`, `seven_days`, `thirty_days`, `custom`) | **Engagement profundo:** el padre no solo abre la pantalla, sino que investiga distintos períodos. |

### Salud (ritmo cardíaco / SpO2)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_health_heart_rate_frequency_changed` | El usuario cambió la frecuencia de medición del ritmo cardíaco. | `frequency_seconds` | Personalización de monitoreo de salud. |
| `legacy_device_health_measurement_started` | El usuario inició una medición manual de ritmo cardíaco. | — | Interés en datos de salud del niño. |
| `legacy_device_health_time_range_changed` | El usuario cambió el rango de fechas en la pantalla de salud. | `range` | Engagement profundo: padres revisando el historial de salud. |

### Uso de aplicaciones (Apps Use)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_apps_use_time_range_changed` | El usuario cambió el rango de fechas en la pantalla de uso de apps. | `range`, `total_duration_seconds` (total acumulado del período), `top_app_name` (app más usada en ese período) | **El evento más rico del módulo.** Permite a marketing segmentar directo: "padres cuyos hijos usan más TikTok que YouTube", "familias con uso > 4hs/día", etc. |

### Historial de llamadas

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_device_call_history_filter_changed` | El usuario cambió el filtro del historial. | `filter` (`all`, `incoming`, `outgoing`, `missed`) | **Cuando se filtra `missed` es señal de preocupación** del padre: busca llamadas perdidas del hijo. |

---

## Contactos del dispositivo

Prefijo `legacy_contacts_*` — contactos permitidos para llamadas desde el
dispositivo del niño.

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_contacts_added` | El usuario agregó un contacto al dispositivo. | `total_count` (cantidad total de contactos DESPUÉS del add) | Configuración inicial o expansión de la agenda. El `total_count` permite segmentar "padres con agenda chica vs grande". |
| `legacy_contacts_edited` | El usuario editó un contacto existente. | — | |
| `legacy_contacts_deleted` | El usuario eliminó un contacto del dispositivo. | `total_count` (cantidad total DESPUÉS del delete) | |

---

## Ajustes

Prefijo `legacy_settings_*` — configuración general del dispositivo
(alarmas, SOS, bloqueos, idioma, red, etc).

### Alarmas

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_settings_alarm_added` | Alarma nueva creada. | `time` (`HH:mm`) | Uso del feature de alarma. El `time` permite ver qué horarios son más populares (despertador matutino, hora del colegio, etc). |
| `legacy_settings_alarm_updated` | Alarma existente editada. | `time` (el NUEVO `HH:mm`) | Refinamiento. |
| `legacy_settings_alarm_removed` | Alarma eliminada. | — | |

### Contactos SOS

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_settings_sos_contact_added` | Contacto SOS agregado. | `total_count` | Configuración de seguridad. Muy importante. |
| `legacy_settings_sos_contact_removed` | Contacto SOS removido. | `total_count` | |

### Whitelist del teléfono (bloqueo de llamadas)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_settings_block_phone_contact_added` | Contacto agregado a la whitelist de llamadas permitidas. | `total_count` | Control parental. |
| `legacy_settings_block_phone_contact_removed` | Contacto removido de la whitelist. | `total_count` | |

### Control parental (funciones desactivadas)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_settings_disable_functions_changed` | El usuario guardó cambios en la pantalla de funciones desactivadas. | — | Engagement con control parental (evento agregado). |
| `legacy_settings_disable_functions_keyboard_toggled` | Se guardó con el teclado habilitado/deshabilitado. | `enabled` | Control granular. |
| `legacy_settings_disable_functions_gps_toggled` | Se guardó con el GPS habilitado/deshabilitado. | `enabled` | Control granular. |

### Otros ajustes del dispositivo

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_settings_language_changed` | Se cambió el idioma del dispositivo. | `language` (ej. `es`, `en`) | |
| `legacy_settings_alerts_configured` | El usuario guardó cambios en las alertas. | `alert_count` (cuántas alertas activas), `alerts_enabled` (lista separada por comas truncada a 100 chars) | Permite ver qué alertas son más populares y cuántas alertas promedio configuran los padres. |
| `legacy_settings_timezone_changed` | Se cambió la zona horaria. | `timezone` | |
| `legacy_settings_wifi_added` | Se agregó una red WiFi permitida. | `total_count` | |
| `legacy_settings_wifi_removed` | Se eliminó una red WiFi permitida. | `total_count` | |
| `legacy_settings_sound_changed` | Se cambió el modo de sonido del dispositivo. | `mode` (`normal` / `silent` / `vibrate`) | Preferencia de perfil sonoro del niño. |
| `legacy_settings_sync_clock_triggered` | El usuario disparó una sincronización manual del reloj del dispositivo. | — | |
| `legacy_settings_battery_night_mode_toggled` | El usuario activó/desactivó el modo nocturno (ahorro de batería). | `enabled` | |

### Gestión remota del dispositivo (comandos destructivos)

 Estos eventos son **muy importantes** para churn analysis. Un
`factory_reset` típicamente precede a un desvinculado y potencial churn.

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_settings_remote_management_shutdown` | El usuario apagó el dispositivo remotamente. | — | Acción poco frecuente. |
| `legacy_settings_remote_management_restart` | El usuario reinició el dispositivo remotamente. | — | Típicamente usado cuando hay problemas técnicos. |
| `legacy_settings_remote_management_factory_reset` |  **CHURN SIGNAL** — El usuario reseteó el dispositivo a fábrica. | — | Borra el dispositivo. Frecuentemente precede un `legacy_account_linked_device_unlinked` y luego `legacy_account_deletion_*`. Cruzar para medir correlación. |

---

## Soporte

Prefijo `legacy_support_*` — solo 1 evento hoy, medirá la demanda de
soporte.

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_support_contact_initiated` | El usuario tocó el botón para contactar soporte (ej. abrir el cliente de email). | `channel` (`email` hoy; en el futuro también `phone`, `whatsapp`), `country` (país seleccionado en el formulario) | Demanda de soporte **por país**: permite ver dónde se originan más tickets. Nota: mide la **intención** de contactar, no confirma envío. |

---

## Onboarding

Prefijo `legacy_onboarding_*` — los slides de intro iniciales de la app.

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_onboarding_step_changed` | El usuario pasó a un nuevo slide del intro. | `step_index` (número de slide, empieza en 0) | Medir cuántos slides el usuario ve antes de empezar. |

---

## Panel principal

Prefijo `legacy_control_panel_*` — acciones en el home del legacy.

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_control_panel_device_selected` | El usuario cambió el dispositivo activo (útil cuando hay varios hijos). | `total_devices` (cuántos dispositivos tiene vinculados) | Qué dispositivo está monitoreando activamente. El `total_devices` permite **segmentar por tamaño de familia** (1 hijo, 2 hijos, 3+). |
| `legacy_control_panel_positions_refreshed` | El usuario tiró del pull-to-refresh o tocó "actualizar" en el dashboard. | — | Preocupación activa del usuario. Indicador de engagement alto. |

---

## Ubicación y mapa

Prefijo `legacy_location_*` — **el feature más rico del producto**. Acá
capturamos toda la interacción del usuario con el mapa: ver el trayecto,
crear zonas seguras, ver lugares frecuentes, cambiar frecuencia de
actualización, etc.

### Geofences (zonas seguras) — CRUD básico

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_geofence_created` | Se creó una geofence (API confirmó). | — | **Conversión final** del funnel de creación. |
| `legacy_location_geofence_updated` | Se actualizó una geofence existente. | — | Refinamiento de configuración de zonas. |
| `legacy_location_geofence_deleted` | Se eliminó una geofence. | — | |

### Lugares frecuentes — CRUD básico

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_frequent_place_created` | Se creó un lugar frecuente (API confirmó). | — | **Conversión final** del funnel. |
| `legacy_location_frequent_place_updated` | Se actualizó un lugar frecuente. | — | |
| `legacy_location_frequent_place_deleted` | Se eliminó un lugar frecuente. | — | |

### Funnel de creación de lugares (geofences y frequent places)

Este es el funnel más valioso del módulo de ubicación. Permite medir
**cuánta gente empieza a crear una zona vs. cuánta termina**.

```
legacy_location_place_creation_started (top: 100 %)

legacy_location_point_confirmed (paso 1 completado)

legacy_location_radius_confirmed (solo geofences — paso 2)

legacy_location_geofence_created (bottom: API OK)
 o legacy_location_frequent_place_created
```

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_place_creation_started` | El usuario tocó "agregar zona" o "agregar lugar frecuente". | `mode` (`geofence` / `frequent_place`) | Top del funnel. |
| `legacy_location_point_confirmed` | El usuario tocó el mapa para fijar el centro del lugar. | `mode` | Paso 1 del funnel completado. |
| `legacy_location_radius_confirmed` | El usuario confirmó el radio de la geofence (solo aplica a geofences). | `radius` (metros), `is_editing` (`true` si estaba editando una existente, `false` si es nueva) | Paso 2 del funnel completado. Permite también **analizar qué tamaños de zonas eligen los usuarios** (radios más comunes casa, escuela, etc.). |
| `legacy_location_place_creation_cancelled` | El usuario salió del flujo de creación/edición antes de terminar. | `mode`, `at_step` (`picking_point` o `adjusting_radius`) | **Drop-off del funnel**. El `at_step` dice exactamente dónde lo perdimos. |

### Exploración y edición

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_geofence_selected` | El usuario tocó una geofence del mapa para verla. | — | Engagement: el usuario está mirando sus zonas. |
| `legacy_location_geofence_dismissed` | El usuario cerró el popup de la geofence sin hacer nada. | — | "Miró pero no editó". Indicador de exploración. |
| `legacy_location_geofence_edit_started` | El usuario tocó "editar" en una geofence seleccionada. | — | Intención de editar. Mid-funnel de edición. |
| `legacy_location_frequent_place_selected` | El usuario tocó un lugar frecuente para verlo. | — | Engagement. |
| `legacy_location_frequent_place_dismissed` | El usuario cerró el popup del lugar frecuente. | — | |
| `legacy_location_history_position_selected` | El usuario tocó un punto del historial de ubicaciones en el mapa. | — | Inspección detallada del trayecto. |
| `legacy_location_history_position_dismissed` | El usuario cerró el detalle del punto de historial. | — | |

### Historial de ubicaciones

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_history_loaded` | El usuario cargó el historial para un rango de fechas. | — | Interés en el historial. |
| `legacy_location_history_cleared` | El usuario limpió el trayecto del mapa. | — | |

### Frecuencia de ubicación (privacidad vs. precisión)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_frequency_updated` | El usuario cambió cada cuánto el dispositivo manda su posición. | `frequency_seconds` (ej. `60`, `300`, `900`) | **Dato súper útil:** indica preferencia entre privacidad y precisión/batería. Correlacionar con retention. |

### Capas del mapa (toggles de visibilidad)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_map_geofences_toggled` | El usuario mostró/ocultó las geofences en el mapa. | `visible` (`true` / `false`) | |
| `legacy_location_map_frequent_places_toggled` | El usuario mostró/ocultó los lugares frecuentes. | `visible` | |
| `legacy_location_map_route_trail_toggled` | El usuario mostró/ocultó la línea del trayecto histórico. | `visible` | |

### Modo "seguir en vivo"

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_following_toggled` | El usuario activó/desactivó el modo "seguir dispositivo" (el mapa se re-centra automáticamente). | `enabled` (`true` / `false`) | **Engagement alto:** el usuario está viendo al hijo en tiempo real. Correlacionar con horarios (ej. entrada/salida del cole). |

### UI del mapa (chrome)

| Evento | Cuándo se dispara | Parámetros | Qué significa para marketing |
|---|---|---|---|
| `legacy_location_map_actions_expanded` | El usuario abrió/cerró el drawer de acciones del mapa. | `expanded` (`true` / `false`) | Indica conocimiento de la UI. |
| `legacy_location_map_zoomed` | El usuario hizo zoom in/out y se quedó en ese nivel (con debounce de 1 segundo para no spamear). | `zoom` (nivel de zoom final) | Nivel de detalle con el que los usuarios miran el mapa. Un zoom alto indica "me importa ver dónde exactamente está". |
| `legacy_location_map_style_changed` | El usuario eligió otro estilo visual para el mapa desde el selector de capas. | `style` (`standard` / `voyager` / `light` / `dark` / `satellite`) | Personalización de la experiencia. **Satellite** es el más usado por padres que quieren ver edificios reales. |
| `legacy_location_map_center_tapped` | El usuario tocó el botón "centrar en el dispositivo" del mapa. | — | Acción de re-centrado manual. Indica que el mapa se desplazó y el usuario quiere volver al hijo. |
| `legacy_location_map_refresh_tapped` | El usuario tocó el botón de refresco dentro del mapa (distinto del pull-to-refresh del control panel). | — | **Engagement intenso:** el usuario quiere la posición más reciente AHORA. Suele dispararse en momentos de ansiedad. |
| `legacy_location_shared` | El usuario tocó "compartir ubicación" — abre el share sheet nativo para mandar la posición del hijo a otra app. | — | **Acción viral del producto.** Es la más importante para crecimiento orgánico: indica que el usuario está mandando data del producto a contactos fuera de la app (familia, pareja, abuelos). |
| `legacy_location_list_sheet_opened` | El usuario abrió el bottom sheet con la lista de geofences, lugares frecuentes e historial. | — | Quiere explorar todo lo que tiene configurado. Mid-funnel de gestión. |
| `legacy_location_history_type_filter_changed` | El usuario filtró el historial por tipo de posición. | `type` (`gps` / `wifi` / `sos` / `all` cuando limpia el filtro) | Indica interés en una fuente de datos específica. **`sos`** filtrado es señal de un evento crítico que el usuario está investigando. |

---

## Cómo usar este catálogo

### Para construir funnels
Tomá un evento "inicio" y uno "fin" en Firebase Analytics Engagement
**Funnels** y comparalos:
- **Signup:** `legacy_auth_signup_started _completed`
- **Login:** `legacy_auth_login_attempt _2fa_verified`
- **Activación (aha moment):** `legacy_device_setup_started _completed`
- **Creación de zona segura:** `legacy_location_place_creation_started _geofence_created`
- **Churn:** `legacy_account_deletion_initiated _deletion_completed`

### Para segmentar audiencias
En **Audiences** podés filtrar por user properties (`user_language`,
`user_has_phone`, etc.) y cruzarlo con cualquiera de estos eventos.

### Para detectar problemas
Filtrar por los eventos con `_failed` o `_failure` y mirar los `reason`
más frecuentes en la pestaña Events Parameter.

### Para medir engagement diario
Los eventos `legacy_control_panel_positions_refreshed`,
`legacy_location_following_toggled` y las screen_views del mapa son los
indicadores más fuertes de usuarios activos y preocupados.

---

## Eventos propuestos para el futuro (NO implementados aún)

Esta sección es la **wishlist** para cuando existan los features o lleguen
las decisiones pendientes.

### Cuando exista el plan premium/suscripción
- `purchase` / `purchase_subscription` (con `value`, `currency`, `transaction_id`)
- `action_click_gopremium` (botón de upgrade)
- `subscription_error_payment` / `subscription_canceled_payment`
- User property `user_plan` (`free` / `premium` / `family`)

### Limit popups / free-tier walls
- `legacy_limit_hit` con `limit_type` (max_devices, max_contacts, etc.)
- `legacy_limit_popup_shown`
- `legacy_limit_popup_upgrade_clicked`

### Referral / invitación
- `legacy_referral_screen_viewed`
- `legacy_referral_code_shared` (con `channel`)
- `legacy_referral_signup_completed`

### NPS / rating
- `legacy_nps_prompt_shown`
- `legacy_nps_score_submitted` (con `score` 0–10)
- `legacy_app_rating_submitted`

### Push notification engagement
- `legacy_notification_received` (background)
- `legacy_notification_opened` (tap app abre)
- `legacy_notification_dismissed`

### Aha moments
- `legacy_first_device_connected` (primera vez que el usuario vincula un dispositivo — requiere persistencia de "primera vez")
- `legacy_first_session_completed`

### A/B testing
- `ab_test_<experiment_name>` (cuando empecemos experimentos con Remote Config)

### Errores de API / health técnica
- `legacy_api_error` con `endpoint`, `status_code` (detectar endpoints flakey)
- `legacy_session_expired`

---

## Referencias técnicas

- **Proyecto Firebase:** `sf-platform-pre` (para dev+staging) / `sf-platform-prod` (pendiente de crear)
- **Package Dart:** `packages/sf_tracking/`
- **Mixins:** Cada grupo de eventos vive en un mixin aparte dentro del package (`auth_tracking.dart`, `location_tracking.dart`, etc).
- **GDPR:** Cada evento incluye automáticamente el parámetro `consent_status` para permitir filtrado post-hoc en BigQuery cuando se implemente el consent screen.
- **Ambiente:** `env` se setea como user property (`development` / `staging` / `production`), por lo que **todos los reportes pueden filtrarse por ambiente** y producción no se va a mezclar con testing.

---

## Changelog del catálogo

- **2026-04-07** — Creación inicial. 61 eventos del módulo legacy implementados y validados en device físico (iPhone 14 Pro iOS 18 + Samsung Galaxy A55 Android 15).
- **2026-04-07** — Se agregaron 16 eventos nuevos al módulo de ubicación (funnel de creación, exploración, edición, follow mode, map zoom debounced, history).
- **2026-04-07** — Se expandió el tracking de `device_management` con 8 eventos nuevos y 3 enriquecimientos de parámetros:
 - NUEVOS: `legacy_device_locate_success/failure`, `legacy_device_remote_connection_picture_viewed`, `legacy_device_activity_meter_time_range_changed`, `legacy_device_health_time_range_changed`, `legacy_device_apps_use_time_range_changed` (con total_duration_seconds y top_app_name), `legacy_device_call_history_filter_changed`.
 - ENRIQUECIDOS: `legacy_device_volume_control_changed` ahora dispara un evento por cada tipo (media/ringtone/alarm) que efectivamente cambió; `legacy_device_scheduled_activity_added/updated` ahora incluyen `week_day` y `period`; `legacy_contacts_added/deleted` ahora incluyen `total_count`.
- **2026-04-07** — Se expandió el tracking de `settings` con 3 eventos nuevos y 7 enriquecimientos de parámetros:
 - NUEVOS: `legacy_settings_remote_management_shutdown/restart/factory_reset` (churn signal crítico).
 - ENRIQUECIDOS: `legacy_settings_alarm_added/updated` ahora incluyen `time`; `legacy_settings_sos_contact_added/removed` incluyen `total_count`; `legacy_settings_block_phone_contact_added/removed` incluyen `total_count`; `legacy_settings_wifi_added/removed` incluyen `total_count`; `legacy_settings_sound_changed` incluye `mode`; `legacy_settings_alerts_configured` incluye `alert_count` y `alerts_enabled`.
- **2026-04-07** — Se expandió el tracking de `device_setup` con 3 eventos nuevos y 2 enriquecimientos críticos:
 - NUEVOS: `legacy_device_setup_qr_scanned`, `legacy_device_setup_manual_code_entered`, `legacy_device_setup_reset_for_new_kid` (señal de familias con múltiples hijos).
 - ENRIQUECIDOS: `legacy_device_setup_step_completed` ahora incluye `duration_seconds` (tiempo por paso — fricción directa); `legacy_device_setup_completed` ahora incluye `child_gender`, `relation_type`, `child_age_years` ( demográficos del usuario final para personas de marketing).
- **2026-04-07** — Se expandió el tracking de `legacy_auth` con 3 eventos nuevos para el funnel interno del signup:
 - NUEVOS: `legacy_auth_signup_step_completed`, `legacy_auth_signup_step_back`, `legacy_auth_signup_step_validation_failed` (todos con `step_index` 0-2).
- **2026-04-07** — Pasada final de cobertura en `legacy_auth`, `account`, `support`, `control_panel`: 6 eventos nuevos y 2 enriquecimientos.
 - NUEVOS AUTH: `legacy_auth_password_reset_completed`, `legacy_auth_password_reset_failed` (con `reason` granular), `legacy_auth_link_phone_code_request_failed`, `legacy_auth_link_phone_code_verification_failed`.
 - NUEVOS ACCOUNT: `legacy_account_linked_device_renamed`, `legacy_account_app_user_delete_triggered`.
 - ENRIQUECIDOS: `legacy_support_contact_initiated` ahora incluye `country` además de `channel`; `legacy_control_panel_device_selected` ahora incluye `total_devices` (proxy de tamaño de familia).
- **2026-04-07** — Se expandió la cobertura de los widgets del módulo `location` con 6 eventos nuevos sobre acciones top-level del mapa:
 - NUEVOS: `legacy_location_map_style_changed` (selector de capas), `legacy_location_map_center_tapped`, `legacy_location_map_refresh_tapped`, `legacy_location_shared` ( acción viral del producto), `legacy_location_list_sheet_opened`, `legacy_location_history_type_filter_changed` (con `type` para detectar interés en posiciones SOS).