Google Analytics Viewtool

The $googleAnalytics Velocity Viewtool provides a simple, developer-controlled way to inject Google Analytics 4 (GA4) tracking code into your dotCMS Velocity templates. Rather than relying on automatic HTML injection, this tool gives you explicit control over where the tracking script is placed, making it straightforward to support consent management flows, multi-environment setups, and multi-tenant sites.

The tool is able to read the googleAnalytics tracking ID stored on the current site's Host content type, if present, and renders the full GA4 <script> snippet ready for inclusion in your template's <head>. You can also pass a custom tracking ID at call time to override the site-level configuration.

GA4 only. Universal Analytics (UA) was sunset by Google in July 2023. This tool supports GA4 measurement IDs (format: G-XXXXXXXXXX) exclusively.

The following example shows how the Google Analytics Viewtool is mapped in the toolbox.xml file:

<tool>
	<key>googleAnalytics</key>
	<scope>request</scope>
	<class>com.dotcms.analytics.viewtool.GoogleAnalyticsTool</class>
</tool>

The ViewTool is registered with request scope, so it resolves the current site context on every page request.

Methods #

Method	Argument	Description
`trackingCode()`	(none)	Generates and returns the full GA4 `<script>` HTML block using the tracking ID configured on the current site's `googleAnalytics` field. Returns an empty string if no tracking ID is set.
`trackingCode(customId)`	`String`: A GA4 measurement ID, e.g. `G-XXXXXXXXXX`	Generates and returns the full GA4 `<script>` HTML block using the supplied `customId`. Falls back to the site-configured tracking ID if `customId` is `null` or empty.
`getTrackingId()`	(none)	Returns the raw GA4 tracking ID string from the current site's `googleAnalytics` field, without generating any HTML. Useful when you need the ID value itself.

Generated Output #

Each trackingCode() call produces a script block in the following format:

<!-- 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>

Usage Examples #

This tool does not auto-inject tracking code into pages. You must explicitly call $googleAnalytics.trackingCode() in your Velocity template wherever you want the script to appear.

Basic: Site-Configured Tracking ID #

Place this in your template's <head> to render the GA4 snippet using whatever tracking ID is saved on the current site:

<head>
  <meta charset="UTF-8">
  <title>$page.title</title>
  $googleAnalytics.trackingCode()
</head>

Placing the script in <head>, rather than before </body>, is recommended for GA4.

Consent-Based Conditional Rendering (GDPR)#

Only inject the tracking script after the user has accepted analytics cookies:

<head>
  <meta charset="UTF-8">
  <title>$page.title</title>
  #if($session.getAttribute("analyticsConsent") == "accepted")
    $googleAnalytics.trackingCode()
  #end
</head>

Multi-Environment Override #

Use different tracking IDs for production and non-production environments by passing a custom ID:

<head>
  #if($config.get("ENVIRONMENT") == "production")
    $googleAnalytics.trackingCode("G-PROD12345")
  #else
    $googleAnalytics.trackingCode("G-DEV67890")
  #end
</head>

Multi-Tenant Support #

In a multi-site setup where you need to route traffic to different GA4 properties per host:

<head>
  ## Falls back to the site's own googleAnalytics field automatically
  $googleAnalytics.trackingCode()
</head>

Because each site stores its own googleAnalytics value, no extra configuration is needed — the tool resolves the correct ID for the current host at render time.

Accessing the Raw Tracking ID #

If you need the measurement ID itself (e.g., to pass it to a third-party tag manager or render it in a data- attribute):

#set($gaId = $googleAnalytics.getTrackingId())
#if($gaId)
  <div data-ga-id="$gaId">...</div>
#end