Add Google Analytics ViewTool for manual GA4 tracking code injection by Copilot · Pull Request #34667 · dotCMS/core

Copilot · 2026-02-16T20:44:33Z

Proposed Changes

Implements $googleAnalytics ViewTool for explicit GA4 tracking code placement in Velocity templates. Replaces auto-injection approach after feedback that it produced "bad results."

Created GoogleAnalyticsTool ViewTool with function-style API
- trackingCode() - uses site's googleAnalytics field
- trackingCode(String customId) - overrides with custom tracking ID
- getTrackingId() - returns configured tracking ID
Registered in toolbox.xml as request-scoped tool
Removed unused GoogleAnalyticsWebInterceptor and auto-inject registration from InterceptorFilter

Usage:

## Basic - site configuration
$googleAnalytics.trackingCode()

## Custom tracking ID (multi-environment/multi-tenant)
#if($config.get("ENVIRONMENT") == "production")
    $googleAnalytics.trackingCode("G-PROD12345")
#else
    $googleAnalytics.trackingCode("G-DEV890")
#end

Generated output:

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-ABC123XYZ"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-ABC123XYZ');
</script>

Checklist

Tests (21 unit tests: site config, custom IDs, null/empty fallback, backward compatibility)
Translations (N/A - no user-facing strings)
Security Implications Contemplated
- Tracking ID from database, not user input (no XSS risk)
- Enables consent-based conditional rendering for GDPR compliance

Additional Info

Implementation notes:

Method overloading: trackingCode() and trackingCode(String) for optional parameter
Falls back to site config if custom ID is null/empty
Deprecated getTrackingCode() for backward compatibility
All documentation in source JavaDoc (temporary markdown docs removed)

Benefits over auto-injection:

Developer control over placement
Conditional inclusion for consent management
No HTML parsing overhead
Multi-environment and multi-tenant support via custom IDs

Screenshots

N/A - Backend feature, no UI changes

Original prompt

This section details on the original issue you should resolve

<issue_title>Implement Google Analytics tracking code injection for sites</issue_title>
<issue_description>## Description

The googleAnalytics field exists in dotCMS sites (Host content type) but is currently only used for storage. The field is exposed via the REST API (SiteResource, SiteForm, SiteView) but has no functional implementation to automatically inject Google Analytics tracking codes into pages.

Current State:

Field defined in SiteResource.GOOGLE_ANALYTICS constant
Stored and retrieved via REST API endpoints
No automatic injection into page templates or HTML output
No Velocity/VTL template usage found
Users must manually implement GA tracking if they want to use this field

Proposed Implementation:
Automatically inject Google Analytics (GA4) tracking code into pages when the googleAnalytics field is populated on a site.

Acceptance Criteria

Read googleAnalytics field value from current site/host context
Automatically inject GA4 tracking code into page <head> when field is populated
Support both Universal Analytics (UA) and GA4 tracking ID formats
Provide configuration option to disable auto-injection if needed
Make tracking code available in Velocity context (e.g., $site.googleAnalytics)
Update documentation on how to use the Google Analytics field
Add integration tests for GA code injection
Verify tracking code injection works across different page types (templates, pages, content)

Additional Context

Related Files:

dotCMS/src/main/java/com/dotcms/rest/api/v1/site/SiteResource.java:100 - Field constant
dotCMS/src/main/java/com/dotcms/rest/api/v1/site/SiteHelper.java:328 - Field mapping
dotCMS/src/main/java/com/dotcms/rest/api/v1/site/SiteForm.java:33 - Form binding
dotCMS/src/main/java/com/dotcms/rest/api/v1/site/SiteView.java:28 - API response

Implementation Options:

Server-side injection: Intercept HTML output and inject GA script before </body>
Template-level: Provide Velocity macro/variable for manual placement
Hybrid: Auto-inject by default with option to use manual placement

GA4 Tracking Code Example:

<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
  window.dataLayer = window.dataLayer || [];
  function gtag(){dataLayer.push(arguments);}
  gtag('js', new Date());
  gtag('config', 'G-XXXXXXXXXX');
</script>

Considerations:

Privacy/GDPR compliance (consider consent management integration)
Performance impact of auto-injection
Support for Google Tag Manager as alternative
Backwards compatibility with existing custom implementations</issue_description>

<agent_instructions>Make sure you use the environment variable, because some customers might not want this enable by default.</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@fmontes ## 🔧 Technical Implementation Details

Server-Side HTML Generation & Injection Points

Based on analysis of the dotCMS codebase, here are the key classes and patterns for implementing Google Analytics tracking code injection:

Key Architecture Components

1. WebInterceptor Pattern (Recommended Approach)

The cleanest implementation would use dotCMS's WebInterceptor system, which provides a pluggable way to intercept and modify HTTP responses.

Key Interface:

com.dotcms.filters.interceptor.WebInterceptor - Core interface for request/response interception

Existing Interceptor Examples:

com.dotcms.filters.interceptor.meta.ResponseMetaDataWebInterceptor - Adds headers to responses
com.dotcms.analytics.track.AnalyticsTrackWebInterceptor - Injects analytics tracking (perfect reference!)

Registration:

com.dotmarketing.filters.InterceptorFilter - Main filter that manages all web interceptors
Interceptors are registered in the filter chain and execute on every request

2. HTML Page Rendering Pipeline

Where HTML pages are actually rendered and assembled:

Core Rendering Classes:

com.dotmarketing.portlets.htmlpageasset.business.render.HTMLPageAssetRenderedAPIImpl - Main page rendering API
com.dotmarketing.portlets.htmlpageasset.business.render.page.HTMLPageAssetRenderedBuilder - Builds page metadata and HTML
com.dotmarketing.portlets.htmlpageasset.business.render.page.PageView - Page view object containing rendered HTML

3. Request/Response Flow

Main filter chain entry point:

com.dotmarketing.filters.CMSFilter - Primary CMS filter (line 59: doFilter)
- Gets current site/host context (line 85)
- Executes rules engine
- Delegates to page rendering

📋 Recommended Implementation Approach

Option A: WebInterceptor (Cleanest & Most Maintainable)

Create a new class: `com.dotcms...

Fixes Implement Google Analytics tracking code injection for sites #34665

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

…ceptor - Created GoogleAnalyticsWebInterceptor to automatically inject GA tracking code - Supports both GA4 (G-XXXXXXXXXX) and UA (UA-XXXXXXXXXX) formats - Injects before </body> tag for optimal performance - Configuration via GOOGLE_ANALYTICS_AUTO_INJECT environment variable - Skips injection in EDIT_MODE and PREVIEW_MODE - Only processes HTML responses (text/html content type) - Registered interceptor in InterceptorFilter - Added comprehensive unit tests Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Added afterIntercept method to properly finalize response modification - Enhanced GAResponseWrapper with finishResponse method - Improved error handling and logging in response finalization - Follows WebInterceptor best practices for response modification Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Added comprehensive documentation for GA auto-injection feature - Created simple standalone tests that don't require PowerMock - Tests cover GA4/UA format detection, HTML injection logic, edge cases - Documentation covers setup, configuration, troubleshooting, and privacy Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Created IMPLEMENTATION_SUMMARY.md with complete overview - Documents architecture, design decisions, and testing strategy - Includes acceptance criteria status and next steps - Provides support considerations and common questions Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Removed Universal Analytics (UA) script template and logic - Simplified generateTrackingScript to only support GA4 format - Updated all tests to remove UA-specific test cases - Updated documentation to reflect GA4-only support - Added note about UA sunset (July 2023) - Simplified implementation (40+ lines removed) Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

docs/google-analytics-auto-injection.md

IMPLEMENTATION_SUMMARY.md

@fmontes

- Removed IMPLEMENTATION_SUMMARY.md (content can be in PR description if needed) - Removed docs/google-analytics-auto-injection.md (not needed in repo) - Addresses review comments from @fmontes Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

wezell

I would go back to the LLM and ask it to use the streaming response, rather than reading in the entire response into memory.

Also, I would add the tracking code to the viewtool and not use auto-inject at all - we have seen the shitshow auto-injecting can create. It is not too much to ask to have people add 1 tag to their template.

- Removed GoogleAnalyticsWebInterceptor and auto-injection mechanism - Removed interceptor registration from InterceptorFilter - Created GoogleAnalyticsTool ViewTool for manual template inclusion - Registered googleAnalytics tool in toolbox.xml with request scope - Added comprehensive unit tests for GoogleAnalyticsTool - Provides $googleAnalytics.trackingCode for Velocity templates Benefits: - Developers have full control over tracking code placement - Can be conditionally included based on user consent - No automatic HTML parsing/modification overhead - More transparent and easier to debug - Addresses concerns about auto-injection approach Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Added GOOGLE_ANALYTICS_VIEWTOOL.md with comprehensive usage guide - Added example-ga-template.vtl showing practical implementation - Includes common patterns, troubleshooting, and migration guide - Documents consent management and GDPR considerations Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Added IMPLEMENTATION_COMPLETE.md summarizing all changes - Documents removed auto-inject vs added ViewTool approach - Shows net reduction of 150 lines (simpler implementation) - Lists all benefits and migration steps Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Changed from property access to method calls: trackingCode() - Added overloaded trackingCode(String) to accept custom tracking ID - Kept getTrackingCode() as deprecated for backward compatibility - Added 8 new test cases for function-style methods - Tests cover: no params, custom ID, null/empty fallback, different formats - Total tests: 21 (13 original + 8 new) Usage: - Site config: $googleAnalytics.trackingCode() - Custom ID: $googleAnalytics.trackingCode("G-CUSTOM123") - Backward compatible: $googleAnalytics.trackingCode still works Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Updated GOOGLE_ANALYTICS_VIEWTOOL.md with trackingCode() syntax - Added examples for custom tracking ID parameter - Added Pattern 5 (multi-environment) and Pattern 6 (multi-tenant) - Updated example-ga-template.vtl to show both basic and advanced usage - Updated API reference table with new methods - All examples now use function call syntax: trackingCode() - Documented backward compatibility with deprecated getTrackingCode() Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Added FUNCTION_STYLE_SUMMARY.md with complete overview - Documents both requirements met: function call and optional parameter - Includes all usage examples and patterns - Shows API reference and backward compatibility - Lists all files modified and test coverage - Migration guide for existing users Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

- Removed example-ga-template.vtl (example template, not needed in repo) - Removed FUNCTION_STYLE_SUMMARY.md (implementation notes, not needed) - Removed GOOGLE_ANALYTICS_VIEWTOOL.md (usage guide, not needed) - Removed IMPLEMENTATION_COMPLETE.md (implementation summary, not needed) The GoogleAnalyticsTool implementation is complete and documented in source code JavaDoc. These temporary documentation files are no longer needed. Co-authored-by: fmontes <751424+fmontes@users.noreply.github.com>

wezell

Looks good - I'm pretty confident that the compiler will fix the string format/concatenation.

Is me.

- Lazy-load HostWebAPI to prevent framework bootstrap (JNDI/DB) during unit tests, which caused the forked VM to crash via System.exit - Replace SiteResource.GOOGLE_ANALYTICS reference with local constant to avoid loading heavy JAX-RS class in test context - Fix test assertions to use correct gtag URL path (gtag/js not gtag.js) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Initial plan

2d5adfb

Copilot AI assigned Copilot and fmontes Feb 16, 2026

github-project-automation bot added this to dotCMS - Product Planning Feb 16, 2026

Copilot started work on behalf of fmontes February 16, 2026 20:44 View session

Copilot AI and others added 5 commits February 16, 2026 20:50

Copilot AI changed the title ~~[WIP] Add Google Analytics tracking code injection for sites~~ Implement automatic Google Analytics 4 tracking code injection Feb 16, 2026

Copilot AI requested a review from fmontes February 16, 2026 21:00

Copilot finished work on behalf of fmontes February 16, 2026 21:00

fmontes previously requested changes Feb 16, 2026

View reviewed changes

docs/google-analytics-auto-injection.md Outdated Show resolved Hide resolved

IMPLEMENTATION_SUMMARY.md Outdated Show resolved Hide resolved

Copilot started work on behalf of fmontes February 16, 2026 21:04 View session

Copilot AI requested a review from fmontes February 16, 2026 21:07

Copilot finished work on behalf of fmontes February 16, 2026 21:07

wezell requested changes Feb 17, 2026

View reviewed changes

Merge branch 'main' into copilot/add-google-analytics-injection

2e5435c

github-actions bot added Area : Backend PR changes Java/Maven backend code Area : CI/CD PR changes GitHub Actions/workflows labels Feb 17, 2026

Copilot started work on behalf of fmontes February 17, 2026 11:59 View session

Copilot AI and others added 3 commits February 17, 2026 12:03

Copilot AI changed the title ~~Implement automatic Google Analytics 4 tracking code injection~~ Replace GA4 auto-injection with ViewTool for explicit template control Feb 17, 2026

Copilot finished work on behalf of fmontes February 17, 2026 12:07

Copilot started work on behalf of fmontes February 17, 2026 12:15 View session

Copilot AI and others added 2 commits February 17, 2026 12:20

Copilot AI changed the title ~~Replace GA4 auto-injection with ViewTool for explicit template control~~ Add Google Analytics ViewTool with function-style API and optional tracking ID override Feb 17, 2026

Copilot finished work on behalf of fmontes February 17, 2026 12:23

spbolton removed the Area : CI/CD PR changes GitHub Actions/workflows label Feb 17, 2026

Copilot started work on behalf of fmontes February 17, 2026 16:08 View session

Copilot AI changed the title ~~Add Google Analytics ViewTool with function-style API and optional tracking ID override~~ Add Google Analytics ViewTool for manual GA4 tracking code injection Feb 17, 2026

Copilot finished work on behalf of fmontes February 17, 2026 16:12

wezell approved these changes Feb 17, 2026

View reviewed changes

fmontes marked this pull request as ready for review February 17, 2026 17:21

Merge branch 'main' into copilot/add-google-analytics-injection

5b3728a

github-actions bot added the Area : CI/CD PR changes GitHub Actions/workflows label Feb 17, 2026

spbolton removed the Area : CI/CD PR changes GitHub Actions/workflows label Feb 17, 2026

Merge branch 'main' into copilot/add-google-analytics-injection

e0eea9a

nollymar approved these changes Feb 18, 2026

View reviewed changes

Merge branch 'main' into copilot/add-google-analytics-injection

2a60006

fmontes added this pull request to the merge queue Feb 19, 2026

Merged via the queue into main with commit 8889252 Feb 19, 2026
39 checks passed

fmontes deleted the copilot/add-google-analytics-injection branch February 19, 2026 16:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Google Analytics ViewTool for manual GA4 tracking code injection#34667

Add Google Analytics ViewTool for manual GA4 tracking code injection#34667
fmontes merged 19 commits intomainfrom
copilot/add-google-analytics-injection

Copilot AI commented Feb 16, 2026 •

edited by fmontes

Loading

Uh oh!

Uh oh!

Uh oh!

wezell left a comment

Uh oh!

wezell left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Comments

Conversation

Copilot AI commented Feb 16, 2026 • edited by fmontes Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed Changes

Checklist

Additional Info

Screenshots

Acceptance Criteria

Additional Context

Comments on the Issue (you are @copilot in this section)

Server-Side HTML Generation & Injection Points

Key Architecture Components

1. WebInterceptor Pattern (Recommended Approach)

2. HTML Page Rendering Pipeline

3. Request/Response Flow

📋 Recommended Implementation Approach

Option A: WebInterceptor (Cleanest & Most Maintainable)

Uh oh!

Uh oh!

Uh oh!

wezell left a comment

Choose a reason for hiding this comment

Uh oh!

wezell left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Comments

Copilot AI commented Feb 16, 2026 •

edited by fmontes

Loading