Analytics - VIVLA Docs

Vision general

La app utiliza PostHog React Native SDK (v4.57+) para product analytics, conectandose a la instancia EU (eu.i.posthog.com).

Autocapture esta deshabilitado: todos los eventos se capturan de forma explicita mediante la API publica. Session replay esta habilitado — ver Session replay.

Arquitectura

Cliente singleton

Definido en src/core/analytics/client.posthog.ts. Inicializa y exporta la instancia unica de PostHog.

API publica

Expuesta desde src/core/analytics/index.ts. Todas las interacciones con analytics pasan por esta capa.

Eventos

Catalogo de eventos definido en src/core/analytics/events.ts.

Configuracion

Parametros de conexion en src/core/config/posthog.ts.

API publica

La API se exporta desde src/core/analytics/index.ts y expone los siguientes metodos:

Metodo	Descripcion
`capture(event, properties)`	Captura un evento con propiedades opcionales
`screen(name, properties)`	Registra una vista de pantalla
`identify(userId, properties)`	Identifica al usuario autenticado
`reset()`	Resetea la sesion (al hacer logout)
`set(properties)`	Establece propiedades del perfil del usuario

Capturar evento
Identificar usuario
Registrar pantalla

import { analytics, analyticsEvents } from '@core/analytics';

analytics.capture(analyticsEvents.booking.completed, {
  booking_type: 'exchange',
  booking_id: '123',
  property_id: 'abc',
});

import { analytics } from '@core/analytics';

analytics.identify(user.id, {
  email: user.email,
});

analytics.profile.set({ home_types: ['beach', 'city'] });

import { analytics } from '@core/analytics';

analytics.screen('StayDetail', {
  stayId: '123',
});

Convencion de nombres

Todos los eventos de la app usan la convencion {category}_{action}:

{category}_{action}

Ejemplos:

app_opened — evento de ciclo de vida de la app
tab_viewed — navegacion entre tabs principales
booking_started — accion en el flujo de booking
home_nps_survey_opened — evento del NPS de home review

Las constantes se definen en src/core/analytics/events.ts y se referencian siempre via analyticsEvents.* — nunca se usan strings hardcodeados.

Eventos generales de la app

Estos eventos se disparan automaticamente a nivel global y no requieren integracion manual en cada pantalla.

Ciclo de vida

Evento	Trigger	Propiedades
`app_opened`	App se abre (cold start) o vuelve a primer plano	`trigger: 'cold_start' \| 'foreground'`

Implementacion: Hook useAppOpenedTracking en app/_layout.tsx. Usa AppState de React Native para detectar transiciones entre background/inactive y active.

Navegacion entre tabs

Evento	Trigger	Propiedades
`tab_viewed`	Usuario cambia de tab principal	`tab_name: 'Home' \| 'Book' \| 'Inbox' \| 'Stays' \| 'Profile'`

Implementacion: screenListeners.focus en app/(tabs)/_layout.tsx.

Vistas de pantalla

Evento	Trigger	Propiedades
`screen_viewed`	Cada cambio de ruta en la app	`screen_name: pathname`

Implementacion: usePathname() de expo-router con useEffect en RootLayoutNav (app/_layout.tsx).

Cambio de propiedad

Evento	Trigger	Propiedades
`property_switched`	Usuario cambia la propiedad activa en el selector Home	`property_id`, `property_type`

Implementacion: En HomePropertySelector.tsx, se captura en ambos paths (iOS bottom sheet y Android modal).

Eventos de booking

Eventos relacionados con el flujo de reservas, intercambios y alquileres. Todos en la seccion analyticsEvents.booking.*.

Navegacion en booking

Evento	Trigger	Propiedades
`booking_tab_viewed`	Cambio entre sub-tabs Book/Exchange/Rent	`sub_tab_name: 'Book' \| 'Exchange' \| 'Rent'`

Seleccion de calendario

Evento	Trigger	Propiedades
`calendar_date_selected`	Usuario selecciona fecha en el calendario	`date`, `selection_type: 'check_in' \| 'check_out'`, `property_id`

Flujo de creacion de reserva

Evento	Trigger	Propiedades
`booking_started`	Usuario inicia creacion de reserva	`booking_type: 'book' \| 'exchange' \| 'rent'`, `property_id`, `check_in`, `check_out`
`booking_completed`	Reserva creada exitosamente	`booking_type`, `booking_id`, `property_id`, `check_in`, `check_out`

Filtros

Evento	Trigger	Propiedades
`filter_applied`	Usuario aplica filtros en Exchange/Rent	`filter_type: 'city' \| 'date'`, `screen_type`, `values`

Gestion de reservas

Evento	Trigger	Propiedades
`booking_cancelled`	Reserva cancelada exitosamente	`booking_id`
`booking_type_changed`	Tipo de reserva modificado	`booking_id`, `new_type`

Eventos del Home NPS

El flujo del Home Annual Review (NPS) tiene su propio conjunto de 7 eventos con el prefijo home_nps_*. Estos eventos trackean el funnel completo desde la exposicion (card) hasta la finalizacion del survey y la visualizacion de resultados. Entry points: home card y deep link.

Documentacion completa de eventos NPS

Ver la referencia detallada de los 7 eventos del Home NPS, propiedades, flujos y guia de dashboard en PostHog.

Eventos del Version Gate

Eventos relacionados con el flujo de version gate (actualizaciones de la app). Seccion analyticsEvents.versionGate.*.

Evento	Trigger	Propiedades
`version_update_dismissed`	Usuario toca “Maybe later” en el banner de actualización recomendada	—

Implementacion: En el hook useVersionCheck (src/shared/services/versionGate/useVersionCheck.ts), la función dismiss() captura el evento antes de ocultar el banner.

El evento solo se dispara para actualizaciones recomendadas. Las actualizaciones obligatorias no tienen opción de dismiss y por tanto no generan este evento.

Eventos del Financial Report

Evento	Trigger	Propiedades
`financial_report_2025_card_rendering`	Card del reporte financiero visible	`mode`
`financial_report_2025_card_click`	Usuario toca el card	—
`financial_report_2025_link_rendering`	Link del reporte visible en PropertyActions	`mode`
`financial_report_2025_link_click`	Usuario toca el link	—

Identificacion de usuarios

Identify

Se llama a analytics.identify() en los siguientes momentos:

Durante la inicializacion de autenticacion
Tras login exitoso
Tras registro exitoso
En cada token refresh

Propiedades enviadas: email, name. Archivo: src/modules/auth/store/authStore.ts

Reset

Se llama a analytics.reset() al hacer logout o eliminar cuenta.

Sincronizacion de perfil

El hook useAnalyticsProfileSync sincroniza automaticamente home_types (array de tipos de propiedad del usuario) con el perfil de PostHog. Archivo: src/shared/hooks/useAnalyticsProfileSync.ts

Feature flags

PostHog gestiona los feature flags de la aplicacion. Se evaluan del lado del cliente y permiten activar o desactivar funcionalidades de forma remota.

import { useFeatureFlag } from 'posthog-react-native';

const isEnabled = useFeatureFlag('home-review');

Flags activos:

Flag	Descripcion
`home-review`	Home annual review card en home screen
`home-review-results`	Card de resultados del review
`financial-report-2025`	Reporte financiero 2025

Session replay

La grabacion de sesiones movil esta habilitada con enableSessionReplay: true en src/core/config/posthog.ts, junto al modulo nativo @posthog/react-native-plugin.

Usar @posthog/react-native-plugin, NO el paquete legacy posthog-react-native-session-replay: el legacy pina posthog-ios 3.58, que no reconoce las vistas de la New Architecture (Fabric) — RCTParagraphComponentView/RCTImageComponentView — y deja texto e imagenes SIN enmascarar en iOS. El plugin nuevo pina posthog-ios 3.69+, que si las enmascara.

Masking

Politica: masking minimo — solo credenciales. Texto e imagenes son visibles en las grabaciones.

Opcion	Valor	Efecto
`maskAllTextInputs`	`false`	El texto de la app se ve en la grabacion
`maskAllImages`	`false`	Las imagenes se ven en la grabacion

Lo unico enmascarado son los inputs de credenciales — email y password en LoginForm, ResetPasswordForm y ResendForm — envueltos en PostHogMaskView. Sin esa mascara, el email se grabaria en claro y la password tambien cuando el usuario activa el toggle de mostrarla (secureTextEntry solo protege mientras esta oculta). Contexto de la decision: las stores no exigen masking. Apple exige divulgar la grabacion de actividad (politica de privacidad y App Privacy label — precedente Glassbox 2019); las credenciales se enmascaran por seguridad basica. Chat e imagenes visibles es decision de producto. PostHogMaskView funciona tambien con New Architecture (usa accessibilityLabel="ph-no-capture", que el masker de posthog-ios 3.69+ respeta para cualquier vista).

Frecuencia de captura

La grabacion toma una captura de la jerarquia de vistas en el hilo principal. Por defecto el SDK lo hace cada 1000ms; en la app se sube a 2000ms con throttleDelayMs: 2000 en sessionReplayConfig, para reducir a la mitad ese coste y evitar el lag percibido en builds con replay. La timeline pasa a un frame cada 2s, suficiente para seguir la accion del usuario.

Control desde el dashboard

La grabacion efectiva se controla server-side en PostHog (Settings → Session replay), sin release:

Toggle de grabacion del proyecto (session_recording_opt_in, compartido entre web y movil)
Feature flag vinculado — el SDK lo reevalua en identify()/reset() sin reiniciar la app
Sampling y duracion minima de sesion
Event triggers (arrancar la grabacion al capturarse un evento concreto)

El proyecto de PostHog (“VIVLA”, id 126590) es unico y compartido con las webs de Vivla (tools.vivla.com, panel.vivla.dev, finance.vivla.com): estos controles aplican a web y movil a la vez. No configurar un flag vinculado para el movil — pausaria tambien las grabaciones de las webs. Mientras no haya proyecto separado, el movil se gobierna con el toggle general y el sampling.

Requisitos de build

@posthog/react-native-plugin es un modulo nativo: requiere build nueva de EAS y no se activa via OTA update. Las builds anteriores siguen funcionando con el replay silenciosamente desactivado.

Configuracion del SDK

Parametro	Valor
Instancia	`eu.i.posthog.com` (EU)
Session replay	Habilitado (texto e imagenes enmascarados)
Autocapture	Deshabilitado
SDK	`posthog-react-native` v4.57+

No incluyas la API key de PostHog en el codigo fuente directamente. La configuracion se gestiona a traves del archivo de configuracion en src/core/config/posthog.ts.

Archivos clave

Archivo	Responsabilidad
`src/core/analytics/client.posthog.ts`	Cliente singleton de PostHog
`src/core/analytics/index.ts`	API publica de analytics
`src/core/analytics/events.ts`	Definicion de eventos (con constantes)
`src/core/config/posthog.ts`	Configuracion de conexion
`src/shared/hooks/useAppOpenedTracking.ts`	Tracking de apertura de app
`src/shared/hooks/useAnalyticsProfileSync.ts`	Sincronizacion de perfil

Guia para agregar nuevos eventos

Definir la constante en src/core/analytics/events.ts dentro del grupo correspondiente
Usar siempre analyticsEvents.grupo.evento — nunca strings hardcodeados
Seguir la convencion {category}_{action}
Capturar en el lugar correcto: preferir callbacks de exito para acciones async, useEffect para exposiciones
Propiedades relevantes: incluir IDs de entidades, tipos/categorias, y contexto necesario para segmentacion

​Vision general

​Arquitectura

Cliente singleton

API publica

Eventos

Configuracion

​API publica

​Convencion de nombres

​Eventos generales de la app

​Ciclo de vida

​Navegacion entre tabs

​Vistas de pantalla

​Cambio de propiedad

​Eventos de booking

​Navegacion en booking

​Seleccion de calendario

​Flujo de creacion de reserva

​Filtros

​Gestion de reservas

​Eventos del Home NPS

Documentacion completa de eventos NPS

​Eventos del Version Gate

​Eventos del Financial Report

​Identificacion de usuarios

​Identify

​Reset

​Sincronizacion de perfil

​Feature flags

​Session replay

​Masking

​Frecuencia de captura

​Control desde el dashboard

​Requisitos de build

​Configuracion del SDK

​Archivos clave

​Guia para agregar nuevos eventos

Vision general

Arquitectura

API publica

Convencion de nombres

Eventos generales de la app

Ciclo de vida

Navegacion entre tabs

Vistas de pantalla

Cambio de propiedad

Eventos de booking

Navegacion en booking

Seleccion de calendario

Flujo de creacion de reserva

Filtros

Gestion de reservas

Eventos del Home NPS

Eventos del Version Gate

Eventos del Financial Report

Identificacion de usuarios

Identify

Reset

Sincronizacion de perfil

Feature flags

Session replay

Masking

Frecuencia de captura

Control desde el dashboard

Requisitos de build

Configuracion del SDK

Archivos clave

Guia para agregar nuevos eventos