@fire-spark/analytics envía cada evento a Fire Spark y a los destinos que agregues: GA4, Meta, TikTok y Masivo. Cada destino es su propio paquete. Consulta Destinos para ver sus opciones.
Instalar
Configurar
Las llamadas a
track() hechas antes de configure() se guardan (hasta 100) y se envían cuando se ejecuta, con su hora original.
Registrar eventos
add_to_cart, purchase o login) reciben el nombre que espera cada destino (view_item en GA4, AddToCart en Meta). Todos los parámetros que pasas llegan a los destinos, no solo los campos de ecommerce. Si pasas product_id sin items, el SDK arma items por ti. Los montos se envían tal como los pasas: el SDK nunca redondea value ni los precios.
Un evento del catálogo que un destino no recibe (por ejemplo page_view en React Native) se omite para ese destino.
Qué guarda Fire Spark
Todos los eventos llegan a los destinos. Fire Spark guarda estos:- Eventos de funnel:
menu_viewed,product_viewed,add_to_cartypurchase. - Eventos de interacción:
product_visitedycategory_visited. - Cualquier evento enviado con la forma de objeto,
track({ name, properties }).
track("nombre", params) con cualquier otro nombre va solo a los destinos. Esto es intencional: usa la forma de objeto cuando también quieras el evento en Fire Spark.
Fire Spark guarda un evento por paso del funnel por sesión, porque sus métricas de funnel cuentan las sesiones que llegaron a cada paso. Los destinos reciben igual cada ocurrencia. Por ejemplo, dos product_viewed en la misma sesión son dos view_item en GA4 y un evento guardado.
Los eventos registrados antes de que haya un cliente llegan a los destinos de inmediato y quedan en la cola. Se envían a Fire Spark cuando getCustomer() devuelve uno.
Elegir destinos por llamada
only y exclude reciben ids de proveedor. Un proveedor en only que no agregaste se informa con onWarning; la llamada no se rechaza.
Enviar la cola
El SDK envía la cola a Fire Spark por su cuenta:- Cuando tiene
flushAteventos (20 por defecto). flushIntervalMsdespués de encolar un evento (30 segundos por defecto).0lo desactiva.- En web, cuando la página se oculta (
visibilitychangeypagehide), conkeepalive. Desactívalo conflushOnHide: false. - En React Native, cuando la app pasa a segundo plano, si pasas
appState:
purchase se envía de inmediato. Llama a analytics.flush() cuando necesites enviar la cola en un momento puntual.
Usuario y consentimiento
setUser() llega a todos los destinos: GA4 recibe el id como user_id y las propiedades como user properties; Meta y TikTok reciben el SHA-256 del id como external_id. Sin setUser(), se usa como usuario un cliente que no es anónimo.
setConsent() reemplaza la opción consent y se envía a todos los destinos, también cuando se revoca el consentimiento:
analyticscontrola GA4 y Masivo.adscontrola Meta y TikTok.- Fire Spark es first-party y no depende del consentimiento.
consent a configure(), se envía a los destinos al configurar. Si no pasas ninguno, el SDK no envía un valor por defecto, así tu plataforma de consentimiento mantiene el control.
Errores
Los fallos de los destinos nunca rechazantrack(). Van a onError con el proveedor y el nombre del evento. Un destino que falla no detiene a los demás.
Datos personales y polyfills
Meta y TikTok reciben el correo y el teléfono con hash SHA-256. El SDK usacrypto.subtle y, si no existe (Hermes, o una página sin HTTPS), una implementación propia. Pasa hash para usar la tuya. Si el hash falla, el campo se omite y se informa con onWarning.
Los ids de evento usan crypto.randomUUID o crypto.getRandomValues cuando existen y una alternativa si no, así track() funciona en React Native sin polyfill.
Varias instancias
Las funciones que exporta el paquete comparten una instancia por defecto. Crea unAnalytics cuando necesites una independiente, con su propia cola, sesión, temporizadores y destinos: