Analytics

Este componente actúa como un puente directo con Google Analytics. Su objetivo principal es ayudarte a extraer, organizar y enviar datos analíticos (como visitas, métricas de conversión o dimensiones de usuarios) directamente a tus automatizaciones en Nappai. Al configurarlo, podrás crear reportes automáticos y alimentar otros nodos de tu flujo de trabajo con información precisa y actualizada.

¿Cómo funciona?

Internamente, este componente se conecta a la API oficial de Google Analytics (v4) mediante Langflow. Cuando ejecutas el nodo, el sistema recopila los parámetros que configuraste (rango de fechas, métricas, dimensiones, credenciales, etc.), construye una solicitud segura y la envía a los servidores de Google. Una vez que Google procesa la petición, el componente recibe los datos en formato estructurado, los organiza y los devuelve como una salida lista para ser consumida por otros nodos. Si ocurre algún error (como credenciales inválidas o límites de cuota superados), el sistema capturará el mensaje y te permitirá revisarlo sin interrumpir todo el flujo.

Conexión y Credenciales

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con el servicio externo:

1. Dirígete a la sección de Credenciales en tu panel de Nappai.
2. Crea una nueva credencial del tipo Google Analytics y guarda los campos requeridos (claves de API, tokens, URL de conexión, etc.). Puedes encontrar las credenciales en la Google Cloud Console.
3. En tu flujo de trabajo, selecciona la credencial guardada en el campo de entrada Credential de este nodo.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

• Account Report: Consulta datos a nivel de cuenta de Google Analytics. Ideal cuando necesitas un resumen consolidado que abarque todas las propiedades de tu organización.
• Property Report: Consulta datos a nivel de propiedad específica. Se utiliza cuando deseas métricas detalladas de un solo sitio web o aplicación concreta.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

• Fixed (Fijo): Escribes el valor directamente en el campo.
• Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
• Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

• Operation: Permite seleccionar qué tipo de reporte deseas ejecutar.
  • Visible en: Account Report, Property Report
• Account Name: Campo para elegir la cuenta de Google Analytics a la que deseas conectarte.
  • Visible en: Account Report, Property Report
• Date Range End: Define la fecha final del periodo que deseas analizar.
  • Visible en: Account Report, Property Report
• Date Range Star: Define la fecha inicial del periodo que deseas analizar.
  • Visible en: Account Report, Property Report
• Dimensions: Te permite seleccionar las categorías de datos que deseas agrupar en el reporte (ej. país, dispositivo, origen de tráfico).
  • Visible en: Account Report, Property Report
• Last Operation: Registra automáticamente la última operación que ejecutaste para mantener un historial de uso.
  • Visible en: Account Report, Property Report
• Last Url: Guarda la última URL utilizada durante la consulta para referencia rápida.
  • Visible en: Account Report, Property Report
• Limit: Establece la cantidad máxima de registros que deseas recuperar en una sola consulta.
  • Visible en: Account Report, Property Report
• Metrics: Permite elegir las métricas específicas que deseas medir (ej. número de accesos, tokens de cuota consumidos).
  • Visible en: Account Report, Property Report
• Order By: Define en qué orden se mostrarán los resultados (ascendente o descendente según la dimensión seleccionada).
  • Visible en: Account Report, Property Report
• Property Name: Permite seleccionar una propiedad concreta dentro de la cuenta.
  • Visible en: Property Report
• Tool Name: Asigna un nombre al nodo para que el asistente de IA lo identifique cuando decida usarlo.
  • Visible en: Account Report, Property Report
• Tool Description: Proporciona una descripción detallada que ayuda al asistente a entender cuándo y cómo debe usar este componente.
  • Visible en: Account Report, Property Report
• Tools arguments metadata: Define metadatos adicionales que ayudarán al sistema a procesar los argumentos de la herramienta de forma más eficiente.
  • Visible en: Account Report, Property Report

Salidas

El componente devuelve principalmente dos tipos de resultado:

• Data: Contiene la información analítica estructurada en formato tabla o lista, lista para ser visualizada, procesada por IA o almacenada.
• Tool: Expone el componente como una herramienta utilizable directamente por los asistentes de IA dentro de Nappai.

Ejemplo de Respuesta JSONjson

{ “reports”: [ { “columnName”: “accessDateHour”, “data”: [ { “metricValues”: [ { “value”: “150” } ], “dimensionValues”: [ { “value”: “2024010114” } ] } ] } ], “rowCount”: 1, “totalRows”: 1 } Nota: Este formato es un ejemplo simplificado. La estructura real puede variar según las métricas y dimensiones seleccionadas.

Conectividad

La salida Data de este componente está diseñada para conectarse lógicamente con nodos de visualización (gráficos, tableros), procesadores de lenguaje natural (asistentes IA, generadores de texto) o almacenamiento de datos (bases de datos, hojas de cálculo). Su estructura tipada garantiza que los siguientes nodos reciban un formato coherente, lo que facilita la automatización de reportes periódicos, la generación de insights con IA o la sincronización con otras plataformas de gestión.

Ejemplo de Uso

Escenario: Automatizar un reporte semanal de visitas y enviarlo a un asistente para generar un resumen ejecutivo.

1. Configura la operación en Property Report.
2. Selecciona tu propiedad en Property Name.
3. Define el Date Range Star y Date Range End con la semana anterior.
4. Agrega métricas como accessCount en Metrics y userCountry en Dimensions.
5. Conecta la salida Data a un nodo de “Asistente IA” y configura un prompt como: “Analiza estos datos y genera un resumen ejecutivo en español con tendencias clave y recomendaciones.”
6. Ejecuta el flujo y el sistema entregará automáticamente el reporte estructurado y el resumen redactado.

Notas Importantes

🔒 Secure Storage of Credentials 🔴 Never hard‑code your Google credentials in scripts or version control. Store them in environment variables or a secrets manager to prevent unauthorized access.

⚠️ Daily Request Quotas 🟡 The component is subject to Google Analytics API quotas. Exceeding the daily limit may result in temporary access blocks.

⚠️ Supported API Versions 🟢 This component currently supports the GA Data API (v4). Data from older Universal Analytics properties may not be fully supported.

📋 Google Analytics Credentials Required 🔴 You must provide valid OAuth credentials and the GA property ID to connect. Without these, the component will not be able to retrieve data.

📋 Enable GA API in Google Cloud 🔴 Before using the component, enable the Google Analytics API in your Google Cloud project. The component will fail if the API is not enabled.

💡 Use Narrow Date Ranges 🟢 Limiting the date range for your queries reduces the amount of data retrieved, improving performance and avoiding quota issues.

💡 Filter Dimensions and Metrics 🟢 Applying dimension and metric filters helps narrow results to relevant data, speeding up queries and making the output easier to analyze.

⚙️ Match GA Property Timezone 🟡 Ensure the timezone set in the GA property matches your reporting expectations; otherwise, date ranges may shift unexpectedly.

⚙️ Correct Data Scope 🟢 Select the appropriate scope (e.g., user, session, event) when querying data to match your analytics goals and avoid misinterpretation.

Consejos y Mejores Prácticas

• Mantén tus rangos de fechas lo más ajustados posible para optimizar el rendimiento y evitar límites de cuota.
• Usa el modo Mapping Mode cuando necesites que las fechas o métricas varíen dinámicamente según datos de otros nodos.
• Revisa constantemente los metadatos de salida para asegurar que los valores numéricos se estén interpretando correctamente en los siguientes pasos del flujo.
• Si un reporte tarda en cargar, verifica primero que las dimensiones seleccionadas sean compatibles con tu tipo de propiedad (GA360 vs estándar).
• Desactiva la ejecución automática en ciclos muy cortos si trabajas con grandes volúmenes de datos para evitar bloqueos temporales por parte de Google.

Consideraciones de Seguridad

Todas las credenciales de Google Analytics deben manejarse con cuidado. Nunca compartas los archivos de configuración ni las claves de acceso con terceros. Asegúrate de que tu proyecto en Google Cloud tenga solo los permisos necesarios (solo lectura de datos analíticos si tu flujo es solo de consulta). Revisa regularmente el historial de actividad en la consola de Google para detectar accesos no autorizados y mantén actualizados los tokens de OAuth según las políticas de seguridad de tu organización.