> ## Documentation Index
> Fetch the complete documentation index at: https://firespark.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Usar analítica en el SDK

> Configura @fire-spark/analytics, registra eventos y controla cuándo se envía la cola, quién es el usuario y qué consintió.

`@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](https://firespark.cloud/docs/es/guides/analytics/destinations.md) para ver sus opciones.

## Instalar

```bash theme={null}
pnpm add @fire-spark/analytics @fire-spark/analytics-ga4
```

## Configurar

```typescript theme={null}
import { analytics } from "@fire-spark/analytics";
import { ga4 } from "@fire-spark/analytics-ga4";

await analytics.configure({
  channel_id: "web",
  platform: "web",
  storage: window.localStorage,
  getCustomer: () => session.customer, // { id, is_anonymous } o null
  getScope: () => ({ store_id, brand_id, fulfillment_id }),
  adapters: [ga4({ measurementId: "G-XXXXXXX" })],
  onError: issue => logger.error(issue.message, issue),
  onWarning: issue => logger.warn(issue.message, issue)
});
```

| Opción | Qué hace |
| - | - |
| `channel_id`, `platform`, `storage`, `getCustomer` | Obligatorias. `storage` puede ser asíncrono (AsyncStorage en React Native). |
| `currency` | Código ISO 4217. Un código inválido se informa con `onWarning` y se ignora. Sin él, se usa la moneda del merchant de sus preferencias. No hay `USD` por defecto. |
| `sessionMs` | Duración de la sesión. La moneda del merchant se lee igual cuando la pasas. |
| `consent` | Función que se lee en cada evento hasta que llamas a `setConsent()`. |
| `onError`, `onWarning` | Reciben los fallos de los destinos y los eventos descartados. Por defecto usan `console.error` y `console.warn`. |
| `flushAt`, `flushIntervalMs`, `flushOnHide`, `appState` | Cuándo se envía la cola. Consulta [Enviar la cola](#enviar-la-cola). |
| `hash` | SHA-256 para los datos personales que se envían a Meta y TikTok. |
| `storagePrefix` | Prefijo de las claves de almacenamiento. Usa uno distinto para cada instancia de `Analytics`. |

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

```typescript theme={null}
await analytics.track("add_to_cart", { product_id: "p1", quantity: 2, value: 2.3 });
await analytics.track({ name: "purchase", properties: { order_id, value, items } });
```

Los eventos del catálogo (por ejemplo `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_cart` y `purchase`.
* Eventos de interacción: `product_visited` y `category_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

```typescript theme={null}
await analytics.track("login", { method: "google" }, { only: ["ga4"] });
```

`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 `flushAt` eventos (20 por defecto).
* `flushIntervalMs` después de encolar un evento (30 segundos por defecto). `0` lo desactiva.
* En web, cuando la página se oculta (`visibilitychange` y `pagehide`), con `keepalive`. Desactívalo con `flushOnHide: false`.
* En React Native, cuando la app pasa a segundo plano, si pasas `appState`:

```typescript theme={null}
import { AppState } from "react-native";

await analytics.configure({ ...options, appState: AppState });
```

`purchase` se envía de inmediato. Llama a `analytics.flush()` cuando necesites enviar la cola en un momento puntual.

## Usuario y consentimiento

```typescript theme={null}
analytics.setUser({ id: "user_123", properties: { plan: "gold" } });
analytics.setUser(null); // lo borra, por ejemplo al cerrar sesión

analytics.setConsent({ analytics: true, ads: false });
```

`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:

* `analytics` controla GA4 y Masivo.
* `ads` controla Meta y TikTok.
* Fire Spark es first-party y no depende del consentimiento.

Si pasas `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 rechazan `track()`. 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 usa `crypto.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 un `Analytics` cuando necesites una independiente, con su propia cola, sesión, temporizadores y destinos:

```typescript theme={null}
import { Analytics } from "@fire-spark/analytics";

const kiosk = new Analytics({ ...options, storagePrefix: "kiosk" });
await kiosk.ready; // se rechaza si configure() falla
await kiosk.track("menu_viewed");
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.