> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.weltpixel.com/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# 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:

```bash
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:

```bash
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:

1. Open your browser's developer tools and check the **Console** for `window.dataLayer` — if it is populated, server-side rendering is functioning.
2. Check that `window.ga4AllowServices` returns `true`.
3. Verify there are no CSP errors in the Console related to GA4 or GTM scripts.
4. 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.