Demographics Quick Start

🎯 Introducción

Esta guía te permitirá implementar y usar los analytics demográficos del CDP en menos de 5 minutos.

🚀 Implementación Rápida

1. Verificar API (30 segundos)

Confirma que tienes acceso al endpoint de demographics:

curl "https://nerdistan-datalake-production.up.railway.app/api/v2/cdp/analytics/demographics?tenant_id=22"

Respuesta esperada: JSON con datos demográficos del tenant 22.

2. Frontend Básico (2 minutos)

Crear un componente simple para mostrar demographics:

import React, { useState, useEffect } from 'react';
import { Card, CardContent, Typography, Grid } from '@mui/material';

const QuickDemographics = ({ tenantId }) => {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetch(`/api/v2/cdp/analytics/demographics?tenant_id=${tenantId}`)
      .then(res => res.json())
      .then(result => setData(result.data));
  }, [tenantId]);

  if (!data) return <div>Cargando...</div>;

  return (
    <Grid container spacing={2}>
      <Grid item xs={12} sm={6} md={3}>
        <Card>
          <CardContent>
            <Typography variant="h6">Total Clientes</Typography>
            <Typography variant="h4">
              {data.summary.total_customers.toLocaleString()}
            </Typography>
          </CardContent>
        </Card>
      </Grid>
      <Grid item xs={12} sm={6} md={3}>
        <Card>
          <CardContent>
            <Typography variant="h6">Edad Promedio</Typography>
            <Typography variant="h4">
              {data.summary.overall_avg_age} años
            </Typography>
          </CardContent>
        </Card>
      </Grid>
      <Grid item xs={12} sm={6} md={3}>
        <Card>
          <CardContent>
            <Typography variant="h6">Datos de Género</Typography>
            <Typography variant="h4">
              {data.summary.completion_rates.gender}%
            </Typography>
          </CardContent>
        </Card>
      </Grid>
      <Grid item xs={12} sm={6} md={3}>
        <Card>
          <CardContent>
            <Typography variant="h6">Datos de Ubicación</Typography>
            <Typography variant="h4">
              {data.summary.completion_rates.location}%
            </Typography>
          </CardContent>
        </Card>
      </Grid>
    </Grid>
  );
};

export default QuickDemographics;

3. Usar en tu App (1 minuto)

import QuickDemographics from './QuickDemographics';

function App() {
  return (
    <div>
      <h1>Analytics Demográficos</h1>
      <QuickDemographics tenantId={22} />
    </div>
  );
}

4. Ver Resultados (30 segundos)

Deberías ver 4 cards mostrando:

• Total Clientes: 4,671
• Edad Promedio: 32.3 años
• Datos de Género: 97.37%
• Datos de Ubicación: 100%

📊 Datos Disponibles

Endpoints Principales

Endpoint	Descripción	Tiempo Respuesta
/api/v2/cdp/analytics/demographics	Análisis completo	~2-3s
/api/cdp/v2/customers	Clientes con demografía	~1-2s
/api/v2/cdp/analytics/rfm	RFM + demografía	~2-3s

Datos Demográficos

• Edad: 18.09% cobertura, calculada desde DNI
• Género: 97.37% cobertura, inferido con IA
• Ubicación: 100% cobertura, validada geográficamente

Segmentos Disponibles

Segmento	Descripción	Count Ejemplo
18-24	Generación Z	104 clientes
25-34	Millennials	233 clientes
35-44	Millennials/Gen X	89 clientes
Masculino	Género M	2,330 clientes
Femenino	Género F	2,218 clientes

🎯 Casos de Uso Inmediatos

Marketing Digital

# Segmentos para Facebook/Google Ads
curl "/api/v2/cdp/analytics/demographics?tenant_id=22" | jq '.data.marketing_segments'

Análisis de Audiencias

// Mostrar distribución por generación
const generations = data.age_analysis.map(item => ({
  name: item.generation,
  value: item.customer_count
}));

Exportación de Datos

// Exportar segmento específico
const exportSegment = (ageRange, gender) => {
  const segment = data.marketing_segments.find(s =>
    s.google_age_range === ageRange && s.gender === gender
  );

  const csv = `Age,Gender,Customers,Spend
${segment.google_age_range},${segment.gender},${segment.targetable_customers},${segment.avg_spent}`;

  // Descargar CSV
  const blob = new Blob([csv], { type: 'text/csv' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `segment_${ageRange}_${gender}.csv`;
  a.click();
};

🔧 Troubleshooting

Problemas Comunes

Error 404 - Endpoint no encontrado

# Verificar URL base
curl "https://nerdistan-datalake-production.up.railway.app/health"

Sin datos demográficos

// Validar tenant
if (!data || !data.summary) {
  console.log('Tenant sin datos demográficos procesados');
}

Performance lenta

// Implementar loading states
const [loading, setLoading] = useState(true);
// Mostrar skeleton mientras carga

📱 Mobile-First Tips

// Responsive grid
<Grid container spacing={{ xs: 1, sm: 2 }}>
  <Grid item xs={12} sm={6} md={3}>
    {/* Cards responsive */}
  </Grid>
</Grid>

// Typography responsive
<Typography variant={{ xs: 'h6', md: 'h4' }}>
  {value}
</Typography>

// Spacing responsive
<Box sx={{ p: { xs: 1, sm: 2, md: 3 } }}>
  {content}
</Box>

🚀 Siguiente Nivel

Componentes Avanzados

• AgeDistributionChart
• GenderAnalysisCards
• MarketingSegmentsTable

API Completa

• Demographics Endpoints
• Customers Enriquecido
• RFM con Demographics

Casos de Uso Avanzados

• Análisis Demográfico
• Implementación Frontend

✅ Checklist de Validación

• ✅ API responde correctamente
• ✅ Frontend muestra datos básicos
• ✅ Responsive en mobile
• ✅ Manejo de errores
• ⚠️ Testing en múltiples tenants
• ⚠️ Performance optimizada

---

Tiempo total: ~5 minutos Nivel: Principiante Prerrequisitos: React + Material-UI Próximo paso: Implementación completa