tracking-crm-core

Framework modular de tracking y CRM para aplicaciones web. Completamente agnóstico respecto al backend - envía datos estructurados a cualquier endpoint que configures: tu propia API, N8N, Zapier, base de datos directa, o cualquier webhook.

🚀 Instalación

npm install tracking-crm-core

🎯 Filosofía del Framework

Este framework se enfoca en capturar y estructurar datos de tracking correctamente, dejando que tú decidas dónde y cómo procesarlos. No estás limitado a ninguna herramienta específica.

✅ Lo que hace el framework:

• Captura eventos de usuarios (clicks, formularios, navegación)
• Gestiona sesiones y tracking de comportamiento
• Estructura payloads de datos consistentes
• Envía datos a los endpoints que configures
• Proporciona APIs simples y tipadas

🎨 Lo que decides tú:

• Dónde enviar los datos (tu API, N8N, webhooks, etc.)
• Cómo procesar y almacenar la información
• Qué hacer con los datos (CRM, analytics, etc.)
• Integración con tu stack tecnológico

📦 Uso Básico

Con tu propia API

import { createTrackingFramework, PRESET_CONFIGS } from 'tracking-crm-core';

const tracker = createTrackingFramework({
  businessId: 'mi-empresa',
  environment: 'production',
  endpoints: {
    baseUrl: 'https://mi-api.com',
    sessionTracking: '/api/tracking/session',
    leadCapture: '/api/tracking/leads',
    immediateEvents: '/api/tracking/events'
  }
});

// El framework enviará datos estructurados a tus endpoints
tracker.trackPageView();
tracker.trackClick('boton-cta', { section: 'hero' });
tracker.trackFormSubmit('contacto', { source: 'landing' });

Con N8N (si lo prefieres)

import { PRESET_CONFIGS, createTrackingFramework } from '@tracking-crm/core';

const tracker = createTrackingFramework(
  PRESET_CONFIGS.localWithN8N('mi-negocio')
);

Con webhooks externos

import { PRESET_CONFIGS, createTrackingFramework } from '@tracking-crm/core';

const tracker = createTrackingFramework(
  PRESET_CONFIGS.webhook('mi-negocio', 'https://hooks.zapier.com/hooks/catch/...')
);

📋 Estructura de Datos

El framework envía payloads estructurados que puedes procesar como prefieras:

Payload de Sesión

{
  "businessId": "mi-empresa",
  "sessionId": "sess_123456789",
  "visitorId": "visitor_987654321",
  "events": [
    {
      "eventType": "page_view",
      "eventName": "page_view",
      "eventData": {
        "url": "https://mi-sitio.com/landing",
        "title": "Landing Page"
      },
      "createdAt": "2024-01-01T12:00:00Z",
      "pageUrl": "https://mi-sitio.com/landing"
    }
  ],
  "deviceInfo": {
    "deviceType": "desktop",
    "browser": "Chrome",
    "operatingSystem": "Windows"
  },
  "sessionDuration": 120,
  "scrollDepth": 75
}

Payload de Lead

{
  "businessId": "mi-empresa",
  "visitorId": "visitor_987654321",
  "leadData": {
    "name": "Juan Pérez",
    "email": "[email protected]",
    "phone": "+1234567890"
  },
  "source": "landing_page",
  "utmParams": {
    "source": "google",
    "medium": "cpc",
    "campaign": "verano2024"
  },
  "createdAt": "2024-01-01T12:00:00Z"
}

🔧 Configuraciones Predefinidas

import { PRESET_CONFIGS } from '@tracking-crm/core';

// Para desarrollo con tu propia API
PRESET_CONFIGS.localDevelopment('mi-negocio')

// Para desarrollo con N8N
PRESET_CONFIGS.localWithN8N('mi-negocio')

// Para producción personalizada
PRESET_CONFIGS.custom('mi-negocio', 'https://mi-api.com')

// Para webhooks externos
PRESET_CONFIGS.webhook('mi-negocio', 'https://webhook-url.com')

🏗️ Ejemplos de Implementación Backend

Con Express.js + Prisma

// routes/tracking.js
app.post('/api/tracking/session', async (req, res) => {
  const { businessId, sessionId, visitorId, events } = req.body;
  
  // Guardar en tu base de datos
  await prisma.session.create({
    data: {
      sessionId,
      visitorId,
      businessId,
      events: {
        create: events.map(event => ({
          type: event.eventType,
          name: event.eventName,
          data: event.eventData,
          createdAt: event.createdAt
        }))
      }
    }
  });
  
  res.json({ success: true });
});

Con Next.js API Routes

// pages/api/tracking/leads.ts
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  const leadData = req.body;
  
  // Procesar lead como prefieras
  await saveLead(leadData);
  await sendToEmailMarketing(leadData);
  await notifySlack(leadData);
  
  res.json({ success: true, leadId: 'lead_123' });
}

Con Serverless Functions

// netlify/functions/tracking.ts
export const handler = async (event, context) => {
  const data = JSON.parse(event.body);
  
  // Enviar a tu CRM, base de datos, etc.
  await processTrackingData(data);
  
  return {
    statusCode: 200,
    body: JSON.stringify({ success: true })
  };
};

🎨 Componentes React Incluidos

import { ConsentBanner, LeadForm, TrackingDashboard } from '@tracking-crm/core';

function App() {
  return (
    <div>
      <ConsentBanner onAccept={() => tracker.trackEvent('consent', 'accepted')} />
      <LeadForm onSubmit={(data) => tracker.trackFormSubmit('lead-form', data)} />
      <TrackingDashboard /> {/* Para debug en desarrollo */}
    </div>
  );
}

🔍 API Completa

createTrackingFramework(config)

Función principal que inicializa el framework.

Retorna objeto con:

• trackEvent(type, name, data) - Trackear evento personalizado
• trackPageView(url?, title?) - Trackear vista de página
• trackClick(elementId, metadata?) - Trackear click en elemento
• trackFormSubmit(formId, formData?) - Trackear envío de formulario
• getStatus() - Obtener estado del tracking
• cleanup() - Limpiar listeners y recursos

Configuración

interface TrackingConfig {
  businessId: string;
  environment?: 'development' | 'production' | 'staging';
  endpoints?: {
    baseUrl?: string;
    sessionTracking?: string;
    leadCapture?: string;
    immediateEvents?: string;
    heartbeat?: string;
    custom?: Record<string, string>;
  };
  timing?: {
    heartbeatInterval?: number;
    inactivityTimeout?: number;
    bufferFlushInterval?: number;
  };
  debug?: {
    enabled?: boolean;
    sessionDebug?: boolean;
    apiDebug?: boolean;
  };
}

🚀 Ventajas de este Enfoque

• 🔧 Flexibilidad Total: Usa cualquier backend, no estás limitado
• 📊 Datos Estructurados: Payloads consistentes y bien tipados
• 🎯 Enfoque Simple: El framework hace tracking, tú decides qué hacer con los datos
• 🔄 Fácil Migración: Cambia de backend sin cambiar el código frontend
• 📈 Escalable: Desde prototipos hasta aplicaciones enterprise

📝 Licencia

MIT - Úsalo como quieras, donde quieras.

¿Preguntas? Este framework está diseñado para ser simple y flexible. Si necesitas ayuda integrándolo con tu stack específico, revisa los ejemplos o crea un issue.