Skip to content
Nappai Documentation

Analytics

The Analytics component in Nappai acts as a bridge between your automation workflows and Google Analytics. It allows you to retrieve reports, metrics, and user data from Google Analytics and make them available for downstream processing. Whether you need to generate daily performance reports, analyze user behavior, or feed data into an AI agent, this component simplifies the interaction with the Google Analytics API by providing a visual interface for configuration and data extraction.

How it Works

When you execute this component, it connects to the Google Analytics API using the credentials you have configured. You define what data you want by selecting an operation, setting date ranges, choosing specific metrics (like page views or sessions), and applying dimensions (like country or device type). The component sends a request to Google, retrieves the structured data, and outputs it as a message or data object. This output can then be passed to other nodes in your workflow for visualization, analysis, or further automation. The component also supports dynamic data handling through Mapping Mode, allowing you to connect inputs to outputs from other parts of your workflow.

Connection & Credentials

This component requires configuring a credential in the Nappai panel before interacting with the external service:

  1. Go to the Credentials section in your Nappai panel.
  2. Create a new credential of the type Google Analytics and fill in the required fields:
    • Select Project: Choose your Google Cloud project.
    • Client Id: Enter your Google Cloud Project Client Id.
    • Client Secret: Enter your Google Cloud Project Client Secret.
    • Google analytics access: Select your analytics access level.
    • Analytics Server Connection URL: Provide the connection URL.
  3. In your workflow, select the saved credential in the Credential input field of this node.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

  • Account Report: Retrieves reports based on the account level, aggregating data across properties associated with the account.
  • Property Report: Retrieves reports specific to a single property, providing detailed metrics for that particular property.

To use the component, first select the operation you need in the “Operation” field.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

  • Operation: Selects the type of report to generate.
    • Visible in: Account Report, Property Report
  • Account Name: Select the Google Analytics account to retrieve data from.
    • Visible in: Account Report, Property Report
  • Date Range End: Define the end date needed to run the report. Format: YYYY-MM-DD. Must be greater than Date Range Star.
    • Visible in: Account Report, Property Report
  • Date Range Star: Define the start date needed to run the report. Format: YYYY-MM-DD. Must be less than Date Range End.
    • Visible in: Account Report, Property Report
  • Dimensions: Define the dimensions needed to run the report. Available dimensions include accessDateHour, accessMechanism, accessedPropertyId, userCountry, userEmail, userIP, and more. Note: Google Analytics 360 Properties are only returned if your account is a 360 property.
    • Visible in: Account Report, Property Report
  • Last Operation: Shows the last operation used for your Google Analytics.
    • Visible in: Account Report, Property Report
  • Last Url: Shows the last URL used for your Google Analytics.
    • Visible in: Account Report, Property Report
  • Limit: Define the number of records to return in the report.
    • Visible in: Account Report, Property Report
  • Mapping Mode: Enable mapping mode to process multiple data records in batch.
    • Visible in: Account Report, Property Report
  • Metrics: Define the metrics needed to run the report. Available metrics include dataApiQuotaPropertyTokensConsumed and accessCount. Note: Google Analytics 360 Properties are only returned if your account is a 360 property.
    • Visible in: Account Report, Property Report
  • Order By: Define conditions to order the records returned by the API. You must define one of the dimensions name passed in the dimensions data.
    • Visible in: Account Report, Property Report
  • Property Name: Select the specific property name for the report.
    • Visible in: Property Report
  • Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
    • Visible in: Account Report, Property Report
  • Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
    • Visible in: Account Report, Property Report
  • Tools arguments metadata: Defines the arguments metadata for the tools.
    • Visible in: Account Report, Property Report

Outputs

This component produces two types of outputs:

  • Data: Returns the structured analytics result from the Google Analytics API. This output contains the metrics and dimensions data, which can be used by subsequent nodes for visualization, analysis, or storage.
  • Tool: Exposes the component as a tool that can be used by AI agents within the workflow for automated decision-making.

Output Data Example (JSON)json

{ “data”: { “rows”: [ { “dimensions”: [“2023-10-01”, “US”], “metrics”: [ { “values”: [“1250”, “300”] } ] } ], “totals”: { “values”: [“12500”, “3000”] }, “columnHeaders”: [ { “name”: “ga:date”, “dataType”: “STRING” }, { “name”: “ga:country”, “dataType”: “STRING” } ] } }

Connectivity

Typically, this component is connected to other nodes in the following ways:

  • To Data Visualization Nodes: Connect the Data output to visualization components to create charts, dashboards, or reports based on the retrieved analytics.
  • To LLM or Text Processing Nodes: Connect the Data output to AI models to summarize reports, extract insights, or generate natural language descriptions of the analytics.
  • To Storage Nodes: Connect the Data output to save analytics results to a database or file for long-term analysis.
  • To AI Agent Tools: Use the Tool output to allow an AI agent to automatically invoke this component for fetching data during its execution.

Usage Example

Scenario: Generating a Monthly Traffic Report

  1. Set Operation to Property Report.
  2. Select Account Name and Property Name corresponding to your website.
  3. Set Date Range Star to 2023-10-01 and Date Range End to 2023-10-31.
  4. In Metrics, select accessCount to get total visits.
  5. In Dimensions, select ga:country to see traffic by country.
  6. Connect the Data output to a visualization node to display a bar chart of traffic per country.

Important Notes

🔒 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.

Tips and Best Practices

  • Use the Mapping Mode to dynamically set dates or metrics based on data from other nodes, making your workflows more flexible.
  • Always define a Limit if you only need a sample of data to prevent large payloads that could slow down your workflow.
  • When using Order By, ensure you select a dimension that exists in your Dimensions list to avoid errors.
  • For Property Report, remember to select the Property Name field, which is only visible in this operation.
  • Monitor your API usage to stay within Google’s daily quotas and avoid temporary access restrictions.

Security Considerations

Ensure that your Google Analytics credentials are stored securely in the Nappai credentials manager. Never expose sensitive information like Client IDs or Secrets in workflow files or logs. The component is designed to handle credentials securely, but user configuration must follow best practices for secret management.