drupal / ai_google_analytics

1.0.x-dev 2026-10-08 18:14 UTC

Requires

• php: >=8.2
• drupal/ai: ^1.4
• drupal/ai_agents: ^1.3
• drupal/ai_content_review: ^1.0@alpha
• drupal/chromium_tool: ^1.0.2
• drupal/core: ^10.5 || ^11.2
• drupal/tool: ^1.0@beta
• google/analytics-data: ^0.26

GPL-2.0-or-later

Published on Packagist.org on 2026-10-09 00:26 UTC

README

Reviews content against Google Analytics 4 (GA4) benchmarks through AI Content Review.

The module provides:

• A Google Analytics Page Metrics tool that fetches GA4 engagement metrics for one or more page paths.
• An Analytics Review Agent that fetches a page's metrics, captures a full-page screenshot of it, relates the numbers to what is on the page, and reports a scored result with suggestions.
• An Analytics performance review rule that attaches the agent to node content so editors can run it from the AI Review tab.

Requirements

Modules:

• AI and its AI Agents submodule
• AI Content Review
• Tool and its AI connector submodule
• Chromium Tool with the Tool API screenshot plugin from #3563217. Earlier releases return screenshots as base64 text, which the model cannot see and which is very expensive in tokens.

Libraries and binaries:

• The google/analytics-data PHP library. Composer installs it with the module.
• A Chromium or Chrome binary on the web server, reachable by PHP.
• A chat model with vision support configured as the site default for the "chat with tools" operation. The agent sends the screenshot as an image.

A GA4 property and a Google Cloud service account with read access to it.

The private file system must be configured ($settings['file_private_path'] in settings.php). The service account key is stored there, and the upload field is disabled until it exists. A key uploaded to public:// by an earlier version is moved by drush updatedb, or by saving the settings form once the private file system is configured. Until then the status report shows an error. Rotate a key that was ever publicly accessible.

Installation

composer require drupal/ai_google_analytics
drush pm:enable --yes ai_google_analytics
drush cache:rebuild

Composer installs the module's dependencies, including the google/analytics-data library. If you place the module in the codebase without Composer, for example as a custom module, require the library in the site's composer.json yourself:

composer require google/analytics-data:^0.26

Enabling the module installs the Analytics Review Agent. The Analytics performance review rule is optional config: it installs when the node module is enabled and is skipped otherwise.

Configuration

Google Analytics

Go to Administration → Configuration → Web services → Google Analytics Settings (/admin/config/services/ai-google-analytics) and set:

• GA4 Property ID: the numeric property ID.
• Service Account Credentials JSON: upload the service account key file. The service account's email must be granted Viewer access on the GA4 property.
• Analytics time frame: the reporting window used when a caller does not specify dates. Presets are GA4 relative dates; a custom range stores exact dates.

Chromium

Go to the Chromium Tool settings form (/admin/config/system/chrome-executable-path-config) and set:

• Chromium executable path: the absolute path to the binary, for example /usr/bin/chromium.
• Image style: select the shipped Chromium Tool Max 1500 style. It scales screenshots before they reach the model, which keeps a full-page capture to roughly the token cost of one image.

Chromium must be able to load the site's own URLs. In local environments with self-signed certificates, add the certificate authority to Chromium's trust store or the capture will show a browser privacy warning instead of the page.

Permissions

The role that runs reviews needs, in addition to AI Content Review's own "Run AI content reviews" permission:

• View Google Analytics data (this module), for the metrics tool.
• Use the Chromium screenshot tool (Chromium Tool), for the screenshot.

Both tools check the current user, so a review triggered by a user without these permissions fails at the tool step.

Review rule

The shipped rule targets all node bundles with one agent-based criterion, pass threshold 70 and warn threshold 10, running in polling mode. Edit it at Administration → Configuration → AI → Tools & Automation → AI Content Review (/admin/config/ai/content-review/rules) to change bundles, thresholds, or the prompt template.

The prompt template is where site-specific benchmarks belong. The shipped template gives example thresholds for engaged sessions, bounce rate and key event rate, plus page expectations such as a visible call to action in the first screen. Adjust the numbers to the property; without benchmarks the agent falls back to its own judgment, which makes scores drift between runs.

How a review runs

1. AI Content Review hands the agent the entity type, bundle, label and field names of the content under review, with the rule's prompt template prepended. The agent's system prompt receives the page URL through the [node:url] token.
2. The agent derives the page path and calls the Google Analytics Page Metrics tool, which runs one GA4 report filtered on the pagePath dimension and returns engaged sessions, bounce rate (%) and key event rate (%) per path.
3. The agent calls the Chromium screenshot tool with the page URL in full_page mode. The image is attached to the next model turn.
4. The agent compares the metrics with the benchmarks, connects each weak metric to something visible on the page, and reports through AI Content Review's result and suggestion tools.

Outcomes:

• Complete: metrics were found. The explanation restates the values, the benchmarks, and the page observations behind the score.
• Skipped: GA4 has no rows for the path in the configured time frame.
• Failed: the metrics tool errored, for example missing credentials.

If the screenshot tool fails the review still completes on metrics alone and the explanation says the screenshot was unavailable.

Using the metrics tool directly

The tool ai_google_analytics_page_metrics can be added to any AI Agent through the Tool AI connector. Inputs:

• paths (required, multiple): page paths as recorded in GA4, e.g. /about.
• start_date, end_date (optional): YYYY-MM-DD or GA4 relative values such as 30daysAgo, yesterday, today. Omit both to use the configured time frame.

Output metrics: a map keyed by path with engagedSessions, bounceRate and keyEventRate. Paths with no data are absent.

Known limitations

• The agent's system prompt uses the [node:url] token, so the page URL only resolves for node content. For other entity types the agent has no URL and guesses the path from the label, which usually results in a skipped review.
• Path matching against GA4 is exact apart from case. Trailing slashes, query strings, language prefixes and old aliases cause a path to be reported as having no data.
• Headless Chromium browses anonymously. Unpublished content renders as an access denied page, which is what the agent will describe.
• The screenshot is not stored. Editors see the agent's description of the page, not the image.
• The three metrics are fixed. Making them configurable is a planned enhancement.