Articles on: Troubleshooting & Common Issues

Installing the Hyvä Compatibility Bridge for GA4 PRO

When you install GA4 PRO on a Magento store running the Hyvä theme, you need to install one additional compatibility bridge module. The right bridge depends on which Hyvä theme variant you're running.

Identify your Hyvä theme variant first

Hyvä ships two parallel theme variants:

Hyvä theme package	Theme name	Use case
`hyva-themes/magento2-default-theme`	`Hyva/default`	Standard Hyvä
`hyva-themes/magento2-default-theme-csp`	`Hyva/default-csp`	CSP-compatible variant for PCI-DSS 4.0 strict-mode compliance

Check which one your store is using before installing. Either look in composer.json for the Hyvä theme package name, or open app/design/frontend/<vendor>/<theme>/theme.xml and read the <parent> value (it will be Hyva/default or Hyva/default-csp). For background on the variants and when each applies, see Hyvä's own documentation under Content Security Policy at docs.hyva.io/hyva-themes/writing-code/csp/.

Pick the matching bridge

Your Hyvä theme	Bridge module to install	Notes
`Hyva/default` (standard)	`weltpixel/module-hyva-ga4`	Single Composer require. No extra dependency.
`Hyva/default-csp` (CSP variant)	`weltpixel/module-hyva-ga4-csp`	Requires `Hyva_Csp` from your Hyvä license to already be installed.

Do not install both bridges on the same theme variant. Installing module-hyva-ga4-csp on a non-CSP Hyvä store throws an Undefined variable $hyvaCsp template error because Hyva_Csp is not present. Installing module-hyva-ga4 on a CSP Hyvä store leaves your tracking outside Hyvä's strict-CSP wrapper.

Standard Hyvä — installation

Run from your Magento root:

composer require weltpixel/module-hyva-ga4
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

No further configuration is required. Once enabled, the compatibility layer applies automatically.

CSP Hyvä — installation

Prerequisite: Hyva_Csp must be installed first, from your Hyvä license repository. Hyvä's documentation covers this at docs.hyva.io/hyva-themes/writing-code/csp/hyva-default-theme-csp-installation.html. If Hyva_Csp is missing, our bridge will throw Undefined variable $hyvaCsp on any frontend page.

After Hyva_Csp is in place, run from your Magento root:

composer require weltpixel/module-hyva-ga4-csp
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

Verification

After installation, confirm the bridge is wired up:

Open your browser's developer tools and check the Console for window.dataLayer — if it is populated, server-side rendering is functioning.
Check that window.ga4AllowServices returns true.
Verify there are no CSP errors in the Console related to GA4 or GTM scripts.
Test an add-to-cart action and confirm the event appears in window.dataLayer or your GTM preview mode.

If window.dataLayer is populated but GTM tags are not firing, the issue is in your GTM container configuration rather than the extension.

Updated on: 19/05/2026

Was this article helpful?

Thank you!