Saltearse al contenido
Nappai Documentation

Google Analytics

Google Analytics es un componente de Nappai que te permite conectarte a la API de Google Analytics y extraer datos de tus cuentas y propiedades. Con él puedes generar informes personalizados, obtener métricas y dimensiones específicas, y usar los resultados dentro de tus flujos de trabajo de automatización.

¿Cómo funciona?

El componente se conecta a la API de Google Analytics mediante una credencial de tipo Analytics API que ya debe estar configurada en Nappai. Cuando lo activas, el componente envía una solicitud HTTP a los endpoints de Google Analytics, pasando los parámetros que configures (operación, rango de fechas, métricas, dimensiones, etc.). La respuesta se devuelve como un objeto de datos que puede ser usado en otros componentes o exportado a tu flujo de trabajo.

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: Genera un informe con datos de la cuenta seleccionada, como métricas de uso y límites de cuota.
  • Property Report: Genera un informe con datos de una propiedad específica, mostrando métricas y dimensiones relacionadas con esa propiedad.

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: Selecciona la operación que deseas ejecutar.

    • Visible en: Account Report, Property Report

  • Account Name: Elige la cuenta de Google Analytics que quieres consultar.

    • Visible en: Account Report, Property Report

  • Date Range End: Define la fecha final del rango de fechas para el informe.

    • Visible en: Account Report, Property Report
    • Formato: YYYY-MM-DD
    • La fecha final debe ser mayor que la fecha inicial.

  • Date Range Star: Define la fecha inicial del rango de fechas para el informe.

    • Visible en: Account Report, Property Report
    • Formato: YYYY-MM-DD
    • La fecha inicial debe ser menor que la fecha final.

  • Dimensions: Selecciona las dimensiones que quieres incluir en el informe.

    • Visible en: Account Report, Property Report
    • Ejemplos de dimensiones disponibles: accessDateHour, accessMechanism, accessedPropertyId, userCountry, userEmail, etc.

  • Last Operation: Guarda la última operación que se ejecutó.

    • Visible en: Account Report, Property Report

  • Last Url: Guarda la última URL utilizada para la solicitud.

    • Visible en: Account Report, Property Report

  • Limit: Establece el número máximo de registros que quieres devolver.

    • Visible en: Account Report, Property Report

  • Mapping Mode: Activa el modo de mapeo para procesar múltiples registros en lote.

    • Visible en: Account Report, Property Report

  • Metrics: Selecciona las métricas que quieres incluir en el informe.

    • Visible en: Account Report, Property Report
    • Métricas disponibles: dataApiQuotaPropertyTokensConsumed, accessCount, etc.

  • Order By: Define el criterio de ordenación de los registros devueltos.

    • Visible en: Account Report, Property Report
    • Debe ser el nombre de una dimensión incluida en Dimensions.

  • Property Name: Selecciona la propiedad de Google Analytics que quieres consultar.

    • Visible en: Property Report

  • Tool Name: El nombre que se mostrará al agente cuando el componente se use como herramienta.

    • Visible en: Account Report, Property Report

  • Tool Description: Descripción detallada de lo que hace esta herramienta.

    • Visible en: Account Report, Property Report

  • Tools arguments metadata: Define los metadatos de los argumentos que la herramienta aceptará.

    • Visible en: Account Report, Property Report

Nota: El componente requiere una credencial de tipo Analytics API. Configúrala primero en la sección de credenciales de Nappai y luego selecciónala en el campo Credential del componente.

Salidas

  • Data: Devuelve los datos del informe en formato estructurado (método: GetData).
  • Tool: Devuelve una herramienta que puede ser utilizada por agentes de IA (método: to_toolkit).

Ejemplo de Uso

Supongamos que quieres generar un informe de la cuenta que muestre cuántas veces se ha accedido a cada propiedad en el último mes.

  1. Operation: Selecciona Account Report.
  2. Account Name: Elige la cuenta deseada.
  3. Date Range Star: 2024-09-01
  4. Date Range End: 2024-09-30
  5. Dimensions: Añade accessedPropertyName y accessDateHour.
  6. Metrics: Añade accessCount.
  7. Limit: 1000
  8. Order By: accessDateHour

Con estos valores, el componente enviará la solicitud a Google Analytics y devolverá un conjunto de datos que puedes usar para crear un gráfico de barras en tu dashboard.

Componentes Relacionados

  • Google Analytics Custom – Versión base que contiene la lógica de conexión a la API.
  • Data Formatter – Permite transformar los datos devueltos en formatos más amigables.
  • Chart Builder – Convierte los datos en visualizaciones interactivas dentro de Nappai.

Consejos y Mejores Prácticas

  • Limita el rango de fechas: Cuanto más amplio sea el rango, más datos tendrás que procesar, lo que puede ralentizar el flujo.
  • Usa Limit sabiamente: Si solo necesitas un subconjunto de los resultados, establece un límite bajo para reducir la carga.
  • Activa Mapping Mode solo cuando sea necesario: Si vas a procesar varios registros a la vez, habilita el modo de mapeo para aprovechar la eficiencia.
  • Revisa las métricas disponibles: Algunas métricas solo están disponibles en Google Analytics 360; verifica que tu cuenta las soporte antes de usarlas.

Consideraciones de Seguridad

  • La credencial Analytics API contiene información sensible (Client Id, Client Secret). Asegúrate de que solo usuarios autorizados tengan acceso a la sección de credenciales.
  • Los campos Last Operation y Last Url pueden contener información de auditoría; evita exponerlos en logs públicos.