Google Analytics

1. Overview

Google Analytics is a web analytics service offered by Google that tracks and reports website and application traffic. It provides insights into user behavior, acquisition channels, and conversion performance.

The GoInsight Google Analytics node leverages the Google Analytics Data API (GA4) to allow you to seamlessly integrate your analytics data into your automated workflows. With this node, you can perform key data retrieval tasks, including:

• Generate Custom Reports: Fetch customized reports by specifying dimensions, metrics, and date ranges to analyze user engagement and performance.
• Search User Activity: Query detailed activity data for all users or a specific user ID over a given period.

2. Prerequisites

Before using this node, you must have a valid Google Analytics account. Specifically, you will need access to a Google Analytics 4 (GA4) property. You may also need appropriate permissions (e.g., Viewer role) on the GA4 property to access its data via the API.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node primarily operates on resources such as Report and User Data, allowing you to generate customized analytics and retrieve user activity records.

Operation Details

Get a Report

Generate customized Google Analytics 4 reports using the Data API runReport method.

Input Parameters:

• PropertyId: GA4 property ID (numeric string, e.g., "123456789"). How to find your Property ID: 1) Open Google Analytics 4, 2) Click 'Admin' (gear icon) in the bottom left, 3) Under 'Property' column, click 'Property Settings', 4) Copy the 'Property ID' number (9-digit number). Example: "123456789"

Options:

• Dimensions: Comma-separated dimension list (e.g., "country,city"). Each dimension represents a data attribute. Common dimensions: country (user's country), city (user's city), deviceCategory (desktop/mobile/tablet), browser (browser name), pagePath (page URL path), sessionSource (traffic source). Full list: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#dimensions. Leave empty for aggregated data without dimensions.
• Metrics: Comma-separated metric list (e.g., "activeUsers,sessions"). Each metric represents a quantitative measurement. Common metrics: activeUsers (number of distinct users), sessions (number of sessions), screenPageViews (total page views), eventCount (total events), conversions (number of conversions), totalRevenue (total revenue). Full list: https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema#metrics. Defaults to "activeUsers" if empty.
• StartDate: Start date for the report. Supports two formats: 1) Absolute date in YYYY-MM-DD format (e.g., "2025-01-01"), 2) Relative date using keywords: today (current day), yesterday (previous day), NdaysAgo (N days before today, e.g., "7daysAgo", "30daysAgo"). Example: "7daysAgo" (last 7 days)
• EndDate: End date for the report. Supports two formats: 1) Absolute date in YYYY-MM-DD format (e.g., "2025-01-31"), 2) Relative date using keywords: today (current day), yesterday (previous day), NdaysAgo (N days before today, e.g., "1daysAgo"). Example: "today" (up to current day)
• Limit: Maximum number of rows to return (default 10, max 250000)
• Offset: Number of rows to skip for pagination (default 0). Use with Limit to fetch subsequent pages. Example: Offset=10 with Limit=10 fetches rows 11-20.

Output:

• Rows (object-array): Array of report data rows. Each element is an object containing the dimension values and metric values for that row. The structure of each row depends on the dimensions and metrics requested. Field names in each object match the dimension and metric names specified in the request.
• DimensionHeaders (string-array): Array of dimension names in the order they appear in each row. These headers correspond to the dimension values in the Rows array. Empty array if no dimensions were requested.
• MetricHeaders (string-array): Array of metric names in the order they appear in each row. These headers correspond to the metric values in the Rows array. Defaults to 'activeUsers' if no metrics were specified.
• RowCount (number): The number of rows actually returned in this response. This may be less than TotalRows if the Limit parameter restricts the number of results.
• TotalRows (number): The total number of rows that match the query criteria, regardless of the Limit parameter. Use this to determine if there are more results available beyond the returned RowCount.
• OriginalStatusCode (number): The original HTTP status code returned by the Google Analytics API. Default 0 means the request did not reach upstream (e.g., timeout or exception). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout/connection failure).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

Search User Data

Search for user activity data in Google Analytics 4 using the Data API runReport method as an alternative to the legacy User Activity API.

Input Parameters:

• PropertyId: GA4 property ID (numeric string, e.g., "123456789"). This is the unique identifier for your Google Analytics 4 property. How to find it: 1) Go to Google Analytics → Admin (gear icon), 2) Select your Property, 3) Click 'Property Settings', 4) Copy the Property ID (numeric only, without 'properties/' prefix). Alternatively, call the List Properties action to get all available property IDs.

Options:

• UserId: User identifier to filter results (optional, leave empty to retrieve all users). Note: This requires custom user tracking to be set up in your GA4 property. If you haven't configured user tracking, leave this empty to retrieve all user activities without filtering by specific user.
• StartDate: Start date for the data query. Supports two formats: 1) Absolute date in YYYY-MM-DD format (e.g., "2025-01-15"), 2) Relative date using keywords: today, yesterday, NdaysAgo (e.g., "7daysAgo", "30daysAgo", "90daysAgo"). Note: N does not require leading zeros (e.g., '7daysAgo', not '07daysAgo').
• EndDate: End date for the data query. Supports two formats: 1) Absolute date in YYYY-MM-DD format (e.g., "2025-01-31"), 2) Relative date using keywords: today (current day), yesterday (previous day), NdaysAgo (N days before today, e.g., "1daysAgo"). Note: N does not require leading zeros.
• Limit: Maximum number of activity records to return (default 100, max 250000)
• Offset: Number of records to skip for pagination (default 0). Use with Limit to fetch subsequent pages. Example: Offset=100 with Limit=100 fetches records 101-200.

Output:

• UserActivities (object-array): Array of user activity records. ⚠️ Note: All metric values are returned as strings by the Google Analytics API (e.g., "2" not 2). Each record contains: Dimensions - userId (optional), date (YYYYMMDD), eventName, sessionSourceMedium, deviceCategory, platform. Metrics - sessions, screenPageViews, eventCount, engagementRate (0-1), userEngagementDuration (seconds).
• TotalCount (number): The total number of user activity records returned in the UserActivities array. This represents the actual number of matching records within the specified date range and limit constraints.
• HasMore (boolean): Boolean indicating whether there are more records available beyond the current result set. If true, use the Offset output value as the Offset parameter in the next request to fetch subsequent records.
• Offset (number): Next page offset for pagination. If HasMore=true, use this value as the Offset parameter in the next request to fetch subsequent records.
• OriginalStatusCode (number): The original HTTP status code returned by the Google Analytics API. Default 0 means the request did not reach upstream (e.g., timeout or exception). Use for debugging.
• StatusCode (number): Operation status code: 200=Success (check ErrorMessage for business errors), -1=Parameter validation error, 500=System error (network timeout/connection failure).
• ErrorMessage (string): Detailed error message if any error occurred. Empty string if the operation succeeded.

5. Example Usage

This section will guide you through creating a simple workflow to fetch a basic report of active users by country from your Google Analytics 4 property.

The workflow will consist of a Start node, a Google Analytics node, and an Answer node.

1. Add the Tool Node
   • In the workflow canvas, click the "+" button to add a new node.
   • In the pop-up panel, select the "Tools" tab.
   • Find and select "Google Analytics" from the list of tools.
   • In the "Google Analytics" supported operations list, click "Get a Report" to add the corresponding node to the canvas.
2. Configure the Node
   • Click on the newly added "Get a Report" node to open its configuration panel on the right.
   • Credentials: In the credentials field at the top of the panel, click the dropdown menu and select your pre-configured Google Analytics credential.
   • Parameters: Fill in the input parameters to define your report.
   • PropertyId: Enter your numeric GA4 Property ID, for example, 123456789.
   • Dimensions: To group the data by country, enter country.
   • Metrics: To count the number of active users, enter activeUsers.
   • StartDate: Leave the default value 7daysAgo to get data for the last week.
   • EndDate: Leave the default value today.
   • Limit: Leave the default value 10 to get the top 10 countries.
3. Run and Verify
   • Once all required parameters are correctly filled, the error indicator on the top right of the workflow canvas will disappear.
   • Click the "Run" button on the top right of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon in the top right corner to view the detailed inputs and outputs of the node, verifying that the operation was successful and the Rows output contains the expected data.

After completing these steps, your entire workflow is configured. When you run it, a report will be retrieved from Google Analytics showing the top 10 countries by active users over the last 7 days.

6. FAQs

Q: Why am I getting a permission denied (403) error?

A: This error usually indicates that the account used for the credential does not have sufficient permissions for the specified GA4 Property ID. Please check the following:

• Correct Property ID: Ensure the PropertyId you entered is correct.
• User Permissions: Verify that the user associated with your credentials has at least the 'Viewer' role for the property in the Google Analytics admin panel.

Q: What are some common dimensions and metrics I can use?

A: Google Analytics offers a wide range of options. Some common ones include:

• Dimensions: country, city, pagePath, eventName, deviceCategory, firstUserSource
• Metrics: activeUsers, sessions, conversions, totalUsers, eventCount, engagementRate

For a complete and up-to-date list, please refer to the official GA4 Data API documentation on dimensions and metrics.

Q: My report is empty (RowCount is 0). What should I check?

A: An empty report can be due to several reasons:

• Date Range: The selected date range (StartDate to EndDate) may have no data. Try using a wider range.
• Invalid Combination: The dimensions and metrics you requested might not be a valid combination or may have no data for the selected period.
• Data Processing Delay: There might be a data processing delay in Google Analytics itself. Data can sometimes take 24-48 hours to appear in reports.

7. Official Documentation

Google Analytics Data API (GA4) Official Documentation