heatmap-saas-sdk-rn

SDK de React Native para Heatmap SaaS — tracking offline-first de eventos táctiles, pantallas y gestos.

Instalación

npm install heatmap-saas-sdk-rn
npm install @react-native-async-storage/async-storage

iOS — enlazar dependencias nativas:

npx pod-install

Inicio rápido

1. Obtener credenciales

Regístrate en el dashboard → crea un proyecto → genera una API Key.
La API Key tiene el formato hm_live_xxxxxxxxxxxx.

2. Envolver el árbol de navegación

En tu App.tsx (o app/_layout.tsx si usas Expo Router):

import { HeatmapProvider } from "heatmap-saas-sdk-rn";
import { NavigationContainer } from "@react-navigation/native";

export default function App() {
  return (
    <HeatmapProvider
      apiKey="hm_live_xxxxxxxxxxxx"
      projectId="uuid-de-tu-proyecto"
    >
      <NavigationContainer>{/* Tu navegación aquí */}</NavigationContainer>
    </HeatmapProvider>
  );
}

3. Usar el hook en cualquier componente

import { useHeatmap } from "heatmap-saas-sdk-rn";

function HomeScreen() {
  const { track, trackScreen, flush } = useHeatmap();

  // Registrar vista de pantalla
  useEffect(() => {
    trackScreen("HomeScreen");
  }, []);

  // Registrar un tap con posición
  const onPress = (e) => {
    const { locationX, locationY } = e.nativeEvent;
    const { width, height } = Dimensions.get("window");
    track("tap", {
      x_pct: (locationX / width) * 100,
      y_pct: (locationY / height) * 100,
      screen: "HomeScreen",
    });
  };

  return <Button onPress={onPress} title="Comprar" />;
}

API

<HeatmapProvider>

Componente raíz que inicializa el SDK. Debe envolver toda la app.

| Prop | Tipo | Requerido | Descripción | | ----------- | -------- | --------- | -------------------------------- | | apiKey | string | ✅ | Tu API Key (hm_live_...) | | projectId | string | ✅ | UUID del proyecto | | config | object | — | Opciones adicionales (ver abajo) |

config opcional

| Opción | Tipo | Default | Descripción | | ------------------ | -------- | --------------------------------- | --------------------------------------------- | | endpoint | string | http://localhost:8000/v1/ingest | URL del backend | | flushInterval | number | 5000 | Intervalo de envío en ms | | maxBatchSize | number | 50 | Máximo de eventos por request | | platform | string | react-native | Plataforma (ios, android, react-native) | | offlineBufferKey | string | — | Key de AsyncStorage para la cola offline |

useHeatmap()

Hook para acceder al SDK desde cualquier componente dentro de <HeatmapProvider>.

const { track, trackScreen, flush } = useHeatmap();

track(eventType, payload?)

Registra un evento manualmente.

track("tap", {
  x_pct: 45.2,
  y_pct: 78.1,
  screen: "ProductScreen",
  metadata: { button: "comprar", productId: "123" },
});

track("swipe", {
  screen: "HomeScreen",
  metadata: { direction: "left" },
});

track("scroll", {
  scroll_pct: 60,
  screen: "ArticleScreen",
});

Tipos de evento disponibles: tap | swipe | scroll | screen_view | rage_click

trackScreen(screenName, metadata?)

Registra una vista de pantalla (screen_view).

trackScreen("CheckoutScreen");
trackScreen("ProductScreen", { productId: "123", category: "shoes" });

flush()

Envía inmediatamente todos los eventos en cola.

await flush();

Tracking de pantallas con React Navigation

Tracking automático al cambiar de ruta:

import { useNavigationContainerRef } from "@react-navigation/native";
import { useHeatmap } from "heatmap-saas-sdk-rn";
import { useRef } from "react";

function AppNavigator() {
  const { trackScreen } = useHeatmap();
  const navRef = useNavigationContainerRef();
  const currentRoute = useRef<string>();

  return (
    <NavigationContainer
      ref={navRef}
      onReady={() => {
        currentRoute.current = navRef.getCurrentRoute()?.name;
        trackScreen(currentRoute.current ?? "Unknown");
      }}
      onStateChange={() => {
        const next = navRef.getCurrentRoute()?.name ?? "Unknown";
        if (next !== currentRoute.current) {
          trackScreen(next);
          currentRoute.current = next;
        }
      }}
    >
      <Stack.Navigator>{/* ... */}</Stack.Navigator>
    </NavigationContainer>
  );
}

Integración con Expo Router

// app/_layout.tsx
import { HeatmapProvider } from "heatmap-saas-sdk-rn";
import { Slot } from "expo-router";

export default function RootLayout() {
  return (
    <HeatmapProvider
      apiKey={process.env.EXPO_PUBLIC_HEATMAP_API_KEY!}
      projectId={process.env.EXPO_PUBLIC_HEATMAP_PROJECT_ID!}
    >
      <Slot />
    </HeatmapProvider>
  );
}

# .env
EXPO_PUBLIC_HEATMAP_API_KEY=hm_live_xxxxxxxxxxxx
EXPO_PUBLIC_HEATMAP_PROJECT_ID=uuid-de-tu-proyecto

Comportamiento offline

El SDK guarda los eventos en AsyncStorage cuando no hay conexión. Al volver a estar online, los envía automáticamente en el próximo ciclo de flush.

También hace flush automático cuando la app pasa a background (AppState listener).

Peer Dependencies

| Paquete | Versión mínima | | ------------------------------------------- | -------------- | | react | >=18.0.0 | | react-native | >=0.72.0 | | @react-native-async-storage/async-storage | >=1.0.0 |

Licencia

MIT