Contao Analytics Integrations: Setup Guide | OpsBlu Docs

Contao Analytics Integrations: Setup Guide

Integrate GA4, GTM, and Meta Pixel with Contao CMS using page layouts, custom elements, and Contao Manager extensions.

Contao is a Symfony-based open-source CMS popular in Germany and Europe. It uses a unique page layout system where analytics scripts are configured per-layout rather than per-template. Understanding Contao's layout hierarchy is essential for correct tracking implementation.

Integration Architecture

Contao provides four integration paths:

  1. Page Layouts -- Contao's primary configuration unit. Navigate to Layout > Page Layouts and add scripts to the "Custom head tags" or "Custom body tags" sections. Each layout can have different tracking configurations.
  2. Custom Elements -- Create reusable content elements at Content > Custom Elements that include tracking scripts. Insert them into any page's article area.
  3. Contao Manager / Composer -- Install extensions via the Contao Manager (/contao/install) or Composer. Extensions like contao-google-tag-manager provide admin-configurable GTM integration.
  4. Template Overrides -- Copy core templates to /templates/ and modify them. Override fe_page.html5 (the master page template) for global script injection.

Available Integrations

Analytics Platforms

Google Analytics 4

  • Page layout head tags (direct gtag.js)
  • GTM-based GA4 (recommended)
  • Contao Analytics module (basic tracking)

Tag Management

Google Tag Manager

  • Page layout custom head/body tags
  • Template override of fe_page.html5
  • Contao Manager extension

Marketing Pixels

Meta Pixel

  • Via GTM container (recommended)
  • Page layout head tag injection

Page Layout Integration (Recommended)

Navigate to Layout > Page Layouts > [your layout] > Custom layout sections. Contao provides fields for additional head and body content:

In the Additional <head> tags field:

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;
j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
f.parentNode.insertBefore(j,f);})(window,document,'script','dataLayer','GTM-XXXX');</script>
<!-- End Google Tag Manager -->

Template Override with Data Layer

Copy the master page template to your project's /templates/ directory and add a data layer:

<?php // templates/fe_page.html5 ?>
<!DOCTYPE html>
<html lang="<?= $this->language ?>">
<head>
  <script>
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    'pageTitle': '<?= $this->escape($this->pageTitle, 'js') ?>',
    'pageId': '<?= $this->id ?>',
    'pageType': '<?= $this->type ?>',
    'pageAlias': '<?= $this->alias ?>',
    'language': '<?= $this->language ?>',
    'layout': '<?= $this->layout ?>',
    'isLoggedIn': <?= $this->isLoggedIn ? 'true' : 'false' ?>
  });
  </script>
  <?= $this->head ?>
</head>
<body class="<?= $this->class ?>"<?= $this->onload ?>>
  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXX"
  height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
  <?= $this->body ?>
</body>
</html>

Platform Limitations

Layout-based scoping. Tracking code added to a page layout only applies to pages using that layout. If your site uses multiple layouts (e.g., different layouts for blog, landing pages, and shop), you must add tracking code to each layout individually -- or override the fe_page.html5 template for global coverage.

Insert tag rendering. Contao uses insert tags ({{page::title}}) for dynamic values. These are rendered server-side but are not available in JavaScript context. To pass Contao data to a JavaScript data layer, use the template override approach with PHP variables.

GDPR focus. Contao's European user base means most installations require cookie consent before analytics scripts load. Extensions like klaro-consent-manager or onetrust-contao are commonly used. GTM's consent mode integration is essential.

Contao Manager vs Composer. The Contao Manager provides a web-based package installer, but not all Composer packages are compatible. Verify extension compatibility with your Contao version (4.x or 5.x) before installation.

No native ecommerce. Contao does not include ecommerce. The Isotope eCommerce extension adds shopping functionality but has its own template system for checkout tracking.

Performance Considerations

  • Symfony-based. Contao 4.x/5.x runs on Symfony, with HTTP caching and Symfony profiler. Enable Symfony's HTTP cache for static pages to reduce server-side rendering overhead.
  • Multiple layouts. If each layout includes its own set of tracking scripts (rather than using a single GTM container), the maintenance burden and potential for inconsistent tracking increases. Consolidate all tracking into one GTM container added to every layout.
  • Asset combination. Contao combines and minifies CSS/JS assets via its page layout settings. Third-party tracking scripts bypass this optimization. Use GTM to manage loading priority.
  1. Override fe_page.html5 -- Add GTM and data layer globally, independent of individual page layouts
  2. Build server-side data layer -- Use Contao's PHP template variables for page metadata
  3. Configure GA4 via GTM -- Map Contao page types and layouts to GA4 content groups
  4. Add Meta Pixel via GTM -- Implement with consent mode for GDPR compliance

Next Steps

For general integration concepts, see the integrations overview.

返回顶部