GA4 DataLayer / GTM

Das Modul DataLayer sendet GA4-E-Commerce-Ereignisse automatisch an die Datenschicht (dataLayer). Es unterstützt sowohl Google Tag Manager (GTM) als auch die direkte Integration von gtag.js. Die Skripte werden mit dem Attribut defer geladen, um die Web Vitals so wenig wie möglich zu beeinträchtigen.

Aktivierung des Moduls

Gehen Sie zu WooCommerce > Polski > Storefront-Module und aktivieren Sie GA4 DataLayer / GTM (Modul-ID: datalayer).

Konfiguration

Die Moduleinstellungen werden in der Option polski_datalayer gespeichert. Gehen Sie zu WooCommerce > Polski > Storefront-Module > GA4 DataLayer / GTM.

Verfügbare Einstellungen

Einstellung	Format	Beschreibung
`gtm_container_id`	`GTM-XXXXXXX`	Container-Kennung von Google Tag Manager
`ga4_measurement_id`	`G-XXXXXXXXXX`	GA4-Mess-ID (für den gtag.js-Modus)
`use_sku_as_id`	boolean	SKU statt der Produkt-ID als `item_id` verwenden

Betriebsmodi

Google Tag Manager - geben Sie gtm_container_id ein. Das Modul fügt das Snippet des GTM-Containers ein (ein Skript im <head> und ein noscript im <body>). Die E-Commerce-Ereignisse gelangen in window.dataLayer.

gtag.js - geben Sie ga4_measurement_id ein (ohne GTM). Das Modul lädt das gtag.js-Skript direkt von Google und sendet die Ereignisse über gtag('event', ...).

Sie können beide Modi gleichzeitig verwenden, dann gelangen die Ereignisse sowohl in den dataLayer (GTM) als auch direkt zu GA4.

E-Commerce-Ereignisse

Das Modul sendet die folgenden Ereignisse gemäß der Spezifikation GA4 Enhanced Ecommerce:

view_item_list

Aufruf einer Produktliste (Kategorieseite, Suchergebnisse, Shop-Seite).

dataLayer.push({
  event: 'view_item_list',
  ecommerce: {
    item_list_id: 'category_koszulki',
    item_list_name: 'Koszulki',
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Koszulka polo',
        item_category: 'Koszulki',
        price: 89.99,
        index: 0
      }
    ]
  }
});

view_item

Aufruf der Seite eines einzelnen Produkts.

dataLayer.push({
  event: 'view_item',
  ecommerce: {
    currency: 'PLN',
    value: 89.99,
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Koszulka polo',
        item_category: 'Koszulki',
        price: 89.99,
        quantity: 1
      }
    ]
  }
});

add_to_cart

Hinzufügen eines Produkts zum Warenkorb. Das Ereignis wird per AJAX nach dem Klick auf die Schaltfläche In den Warenkorb gesendet (sowohl auf der Produktseite als auch in der Liste).

dataLayer.push({
  event: 'add_to_cart',
  ecommerce: {
    currency: 'PLN',
    value: 89.99,
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Koszulka polo',
        item_category: 'Koszulki',
        price: 89.99,
        quantity: 1
      }
    ]
  }
});

remove_from_cart

Entfernen eines Produkts aus dem Warenkorb.

dataLayer.push({
  event: 'remove_from_cart',
  ecommerce: {
    currency: 'PLN',
    value: 89.99,
    items: [
      {
        item_id: 'SKU-001',
        item_name: 'Koszulka polo',
        price: 89.99,
        quantity: 1
      }
    ]
  }
});

begin_checkout

Beginn des Bestellvorgangs (Aufruf der Kassenseite).

dataLayer.push({
  event: 'begin_checkout',
  ecommerce: {
    currency: 'PLN',
    value: 179.98,
    items: [/* Produkte aus dem Warenkorb */]
  }
});

purchase

Abschluss der Bestellung (Dankeseite). Das Ereignis wird pro Bestellung nur einmal gesendet (abgesichert durch ein Cookie).

dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: '12345',
    currency: 'PLN',
    value: 179.98,
    tax: 33.55,
    shipping: 9.99,
    items: [/* Produkte aus der Bestellung */]
  }
});

GTM-Container-Snippet

Nach der Eingabe von gtm_container_id fügt das Modul den Code des GTM-Containers automatisch ein:

Im Abschnitt <head> (Hook wp_head, Priorität 1):

<script defer>
(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.defer=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXXX');
</script>

Nach dem öffnenden <body> (Hook wp_body_open):

<noscript>
<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
height="0" width="0" style="display:none;visibility:hidden"></iframe>
</noscript>

Leistung und Web Vitals

Das Modul ist für die Core Web Vitals optimiert:

Defer - die GTM- und gtag.js-Skripte werden mit dem Attribut defer geladen, sie blockieren das Rendern der Seite nicht
Inline dataLayer - die E-Commerce-Daten werden als Inline-JSON eingefügt, ohne zusätzliche HTTP-Anfragen
Lazy events - die Ereignisse add_to_cart und remove_from_cart werden über Event-Delegation registriert (ein einziger Listener auf dem Dokument)
No layout shift - das GTM-noscript-Snippet hat keine Abmessungen, es verursacht kein CLS

Produktkennung

Standardmäßig wird die WooCommerce-Produkt-ID (Post-ID) als item_id verwendet. Aktivieren Sie die Option SKU als ID verwenden (use_sku_as_id), um stattdessen die SKU des Produkts zu senden.

Wenn einem Produkt keine SKU zugewiesen ist, verwendet das Modul die Produkt-ID als Fallback.

Daten variabler Produkte

Bei variablen Produkten (variable products) sendet das Modul die Daten der ausgewählten Variation:

item_id - die SKU der Variation (oder die Variations-ID)
item_variant - der Name der ausgewählten Attribute (z. B. “Rot / XL”)
price - der Preis der Variation

Hooks

// Produktdaten vor dem Senden an den dataLayer ändern
add_filter('polski/datalayer/item_data', function (array $item_data, \WC_Product $product): array {
    $item_data['item_brand'] = $product->get_attribute('marka');
    return $item_data;
}, 10, 2);

// Ein bestimmtes Ereignis deaktivieren
add_filter('polski/datalayer/event_enabled', function (bool $enabled, string $event_name): bool {
    if ($event_name === 'view_item_list') {
        return false;
    }
    return $enabled;
}, 10, 2);

// Die Daten des purchase-Ereignisses ändern
add_filter('polski/datalayer/purchase_data', function (array $data, \WC_Order $order): array {
    $data['ecommerce']['coupon'] = implode(',', $order->get_coupon_codes());
    return $data;
}, 10, 2);

Debugging

GTM-Vorschaumodus

Verwenden Sie Tag Assistant, um Ereignisse in Echtzeit anzuzeigen. Öffnen Sie den Tag Assistant, verbinden Sie sich mit der Shop-Domain und durchlaufen Sie den gesamten Kaufvorgang.

Browser-Konsole

Prüfen Sie den Inhalt des dataLayer in der Konsole:

console.table(window.dataLayer);

GA4 DebugView

Gehen Sie in Google Analytics 4 zu Verwaltung > DebugView, um Ereignisse in Echtzeit von einem Gerät mit aktiviertem Debug-Modus zu sehen.

Fehlerbehebung

Das purchase-Ereignis wird nicht ausgelöst - prüfen Sie, ob die Dankeseite im Cache liegt. Deaktivieren Sie das Caching für den Endpunkt order-received.

Keine add_to_cart-Ereignisse - stellen Sie sicher, dass WooCommerce-AJAX korrekt funktioniert. Prüfen Sie die Browser-Konsole auf JavaScript-Fehler.

Doppelte purchase-Ereignisse - das Modul setzt nach dem Senden des Ereignisses ein Cookie polski_datalayer_order_{id}. Wenn das Cookie blockiert wird, kann sich das Ereignis wiederholen.

Das GTM-Snippet wird nicht geladen - prüfen Sie, ob das Theme wp_head() und wp_body_open() aufruft.

Probleme melden: github.com/wppoland/polski/issues

Diese Seite dient ausschließlich zu Informationszwecken und stellt keine Rechtsberatung dar. Polski for WooCommerce ist Open-Source-Software (GPLv2), die ohne Gewährleistung bereitgestellt wird.