Konfigurationsanleitung für Kowal Analytics

Navigation im Adminbereich

Die wichtigsten Einstiegspunkte des Moduls:

• Kowal -> Analytics -> Dashboard
• Stores -> Configuration -> Analytics

Konfigurationsstruktur

Das Modul stellt derzeit drei Hauptgruppen von Einstellungen bereit.

1. General

Pfad:

• Stores -> Configuration -> Analytics -> General

Feld:

• Enable Analytics

Bedeutung:

• aktiviert oder deaktiviert das Frontend-Tracking und die weitere Analytics-Verarbeitung für den ausgewählten Scope.

Empfehlung:

• Aktivieren Sie die Funktion am besten pro store view, nachdem Sie zuvor die Funktionsweise der Tracker und Consumer überprüft haben.

2. Debug

Pfad:

• Stores -> Configuration -> Analytics -> Debug

Felder:

• Enable Backend Debug Log
• Enable Frontend Console Log

Bedeutung:

• Backend Debug speichert technische Protokolle unter:
  • var/log/kowal_analytics_debug.log
• Frontend Debug schreibt Tracker-Protokolle in die Browserkonsole.

Anwendungsbereiche:

• Installation,
• QA,
• Fehleranalyse,
• Tests des Selector Assistant,
• Bestätigung, dass Ereignisse die Pipeline erreichen.

Empfehlung:

• während der Implementierung und Tests aktivieren,
• nach Abschluss der Validierung in der Produktionsumgebung deaktivieren.

3. Tools

Pfad:

• Stores -> Configuration -> Analytics -> Tools

Feld:

• Enable Frontend Selector Assistant

Bedeutung:

• zeigt im Storefront einen Helper an, mit dem Sie die Konfiguration eigener, auf Selektoren basierender Areas auswählen und vorbereiten können.

Anwendungsbereiche:

• Zuordnung benutzerdefinierter Bereiche,
• Analyse der DOM-Struktur,
• Vorbereitung von Area-Definitionen ohne manuelle Codebearbeitung.

Die Konfiguration in der Praxis verstehen

Scope

Das Modul arbeitet im Magento-Scope, sodass sich die Konfiguration für folgende Ebenen unterscheiden kann:

• default,
• website,
• store view.

Am sichersten ist es, das Modul als Tool pro Store View zu behandeln, denn:

• verschiedene Shops können unterschiedliche Layouts haben,
• verschiedene Shops können unterschiedliche Blog-, CMS- und Merchandising-Bereiche haben,
• Berichte pro Store View sind operativ deutlich zuverlässiger.

Grundlegende Begriffe im Modul verstehen

Area

Area bezeichnet einen abgegrenzten Seitenbereich, den Sie als Quelle des Einflusses auf den Verkauf messen möchten.

Beispiele:

• related_products
• upsell_products
• crosssell_products
• category_listing
• search_results
• wishlist_products
• compare_products
• blog_post_listing
• blog_sidebar_categories
• homepage_promo_box

Object

Object bezeichnet ein konkretes Element innerhalb einer Area.

Beispiele:

• ein einzelnes Produkt in einer Liste,
• ein Blogbeitrag,
• eine Blogkategorie,
• ein Tag,
• ein Banner,
• ein Slide.

Source Page

Source Page bezeichnet die Seite, auf der der Benutzer eine Interaktion begonnen hat, die später zu einem Verkauf führte.

Beispiele:

• die Seite des Ausgangsprodukts für related_products,
• ein Blogbeitrag bei einem Klick auf ein Produkt,
• ein Kategorielisting bei einem Klick auf ein Produkt,
• Suchergebnisse für ein Produkt.

Dashboard und Berichte

Analytics Dashboard

Dies ist die zentrale Übersichtsseite. Sie zeigt:

• zugeordneten Umsatz,
• zugeordnete Bestellungen,
• durchschnittlichen Bestellwert,
• CTR,
• Top-Areas,
• Top-Produkte mit unterstützender Wirkung,
• Top-Blogquellen,
• Links zu detaillierten Berichten.

Diese Ansicht beantwortet die Frage:

• was am besten funktioniert

Area Report

Dieser Bericht beantwortet folgende Fragen:

• welche Area Umsatz generiert,
• welche Objects innerhalb dieser Area verkaufen,
• aus welchen Source Pages die Verkäufe stammen.

Beispiel:

• related_products hat 18 Bestellungen,
• Zing Jump Rope verkauft sich darin am besten,
• die Produktseite Affirm Water Bottle ist am häufigsten der Ausgangspunkt dieses Pfads.

Product Context Report

Dies ist ein Bericht für produktbezogene Bereiche wie:

• related_products
• upsell_products
• crosssell_products
• category_listing
• search_results

Er zeigt folgende Beziehung:

• source product -> clicked object -> purchased SKU

Beispiel:

• Der Benutzer befindet sich auf der PDP Affirm Water Bottle,
• klickt in related_products auf WB05-S-Orange,
• und kauft WB05-S-Orange.

Blog Commerce Report

Dies ist ein Bericht für Blogbereiche:

• blog_post_listing
• blog_recent_posts_widget
• blog_sidebar_recent_posts
• blog_sidebar_categories
• blog_sidebar_tags
• blog_post_view

Er beantwortet folgende Fragen:

• welcher Beitrag verkauft,
• welche Blogkategorie verkauft,
• welcher Tag den Verkauf unterstützt,
• welche SKUs nach dem Einstieg über den Blog gekauft werden.

Object Report

Dies ist ein Bericht für ein einzelnes konkretes Object.

Beispiel:

• ein Produkt in related_products,
• ein Blogbeitrag aus blog_post_listing,
• eine Blogkategorie aus blog_sidebar_categories.

Er zeigt:

• wie viele Impressionen das Objekt hatte,
• wie viele Klicks es hatte,
• wie viele Bestellungen es generiert hat,
• welcher Umsatz ihm zugeordnet wurde,
• aus welchen Source Pages diese Pfade stammten.

Source Page Report

Dies ist ein Bericht für eine einzelne konkrete Quellseite.

Beispiel:

• die Produktseite Affirm Water Bottle,
• der Blogbeitrag Wie wählt man eine Trainingsflasche aus?,
• das Kategorielisting Laufschuhe.

Er zeigt:

• welche Clicked Objects dieser Seite verkaufen,
• welche SKUs nach dem Einstieg über diese Seite gekauft werden,
• wie viele Bestellungen und welchen Umsatz diese konkrete Seite als Ausgangspunkt des Pfads generiert.

Attributionsmodelle

Verfügbare Modelle:

• Last Click
• First Click
• Assisted
• View Through

So werden sie interpretiert:

Last Click

Am besten geeignet für die Frage:

• welches Element den Verkauf unmittelbar abgeschlossen hat.

First Click

Am besten geeignet für die Frage:

• welches Element den zum Kauf führenden Pfad begonnen hat.

Assisted

Am besten geeignet für die Frage:

• welches Element am Pfad beteiligt war, auch wenn es nicht der letzte Klick war.

View Through

Am besten geeignet für die Frage:

• ob bereits die Einblendung eines Bereichs den Verkauf beeinflusst hat, auch ohne Klick.

Konfiguration einer benutzerdefinierten Area

Eine benutzerdefinierte Area können Sie mit dem Frontend Selector Assistant vorbereiten.

Typischer Workflow:

1. Aktivieren Sie Enable Frontend Selector Assistant.
2. Öffnen Sie den Storefront.
3. Starten Sie den Assistant.
4. Wählen Sie einen Bereich aus.
5. Prüfen Sie den vorgeschlagenen container selector.
6. Prüfen Sie den vorgeschlagenen item selector.
7. Prüfen Sie den link selector.
8. Speichern Sie die Definition.
9. Bestätigen Sie, dass Runtime Apply data-kowal-track-* hinzugefügt hat.
10. Testen Sie den Klick und die Übernahme in die Berichte.

Beispiel einer benutzerdefinierten Area

Angenommen, Sie haben auf der Startseite eine Werbebox mit drei Kacheln.

Sie können Folgendes definieren:

• area_code = homepage_promo_box
• object_type = promotion
• container_selector = .homepage-promo
• item_selector = .homepage-promo__item
• link_selector = .homepage-promo__link

Der Bericht zeigt dann:

• welche Kachel angeklickt wurde,
• welche Kachel zu einem Kauf führte,
• welchen Umsatz sie generiert hat.

Test-Workflow nach der Konfiguration

Die sinnvollste Reihenfolge:

1. Analytics aktivieren,
2. Backend Debug aktivieren,
3. Frontend Console Log aktivieren,
4. ein Benutzerszenario durchlaufen,
5. das Dashboard prüfen,
6. den Area Report prüfen,
7. zum Object Report oder Source Page Report wechseln,
8. den Debug-Modus nach erfolgreicher Prüfung deaktivieren.

Betriebliche Empfehlungen

• Betreiben Sie die Consumer unter Supervisor oder systemd,
• stellen Sie sicher, dass der Magento-Cron dauerhaft funktioniert,
• prüfen Sie nach Theme-Änderungen, ob die Selektoren benutzerdefinierter Areas weiterhin zum DOM passen,
• vergleichen Sie nach Merchandising-Änderungen die Ergebnisse pro Area,
• interpretieren Sie die CTR nicht isoliert als Erfolg, ohne Umsatz und Bestellungen zu prüfen.

Installationsanleitung für Kowal Analytics

Anforderungen

Stellen Sie vor der Installation sicher, dass:

• die Magento-2-Instanz ordnungsgemäß funktioniert,
• Composer Zugriff auf das Kowal-Paket-Repository hat,
• Sie über CLI-Zugriff auf bin/magento verfügen,
• Cron und Queue Consumer in der Umgebung ausgeführt werden können,
• Datenbankzugriffe und Schreibvorgänge in var/log in der Umgebung ordnungsgemäß funktionieren.

Installation über Composer

Fügen Sie das Composer-Repository hinzu:

Die Zugangsdaten für das Composer-Repository, also die E-Mail-Adresse des Kunden und das Lizenz-Token, erhalten Sie nach dem Kauf per E-Mail. Sie sind außerdem nach der Anmeldung auf kowal.store im Kundenbereich verfügbar. Ersetzen Sie TWOJ_EMAIL_KLIENTA durch die E-Mail-Adresse Ihres Kontos und TWOJ_TOKEN durch das erhaltene Token. Führen Sie die Befehle im Magento-Stammverzeichnis aus.

composer config repositories.kowal composer https://repo.kowal.store

Fügen Sie die Zugangsdaten für das private Repository hinzu:

composer config http-basic.repo.kowal.store 'TWOJ_EMAIL_KLIENTA' 'TWOJ_TOKEN'

Installieren Sie das Modul:

composer require kowal/module-analytics

Modul aktivieren

Führen Sie die standardmäßigen Magento-Befehle aus:

bin/magento module:enable Kowal_Analyticsbin/magento setup:upgradebin/magento cache:flush

Wenn der Shop im Produktionsmodus läuft, führen Sie außerdem Folgendes aus:

bin/magento setup:di:compilebin/magento setup:static-content:deploy -fbin/magento cache:flush

Asynchrone Prozesse starten

Das Modul verwendet Warteschlangen und asynchrone Verarbeitung. Ohne diese sind Dashboard und Berichte nicht vollständig.

Starten Sie die erforderlichen Consumer:

bin/magento queue:consumers:start kowal_analytics.raw_eventsbin/magento queue:consumers:start kowal_analytics.conversionbin/magento queue:consumers:start kowal_analytics.attribution

Der Magento-Cron muss ebenfalls ordnungsgemäß funktionieren, da das Modul Retry und Backfill für die Attribution verwendet.

Grundlegende Prüfung:

bin/magento cron:run

Was geschieht nach der Installation?

Nach der ordnungsgemäßen Installation führt das Modul folgende Aktionen aus:

• Es lädt den Tracker im Storefront,
• erfasst Frontend-Ereignisse,
• verknüpft die Analytics-Sitzung mit dem quote,
• überträgt Analytics-Kennungen nach sales_order,
• speichert Conversions und Conversion-Positionen,
• berechnet die Attribution von Bestellungen zu Area und Object,
• stellt das Dashboard und detaillierte Berichte im Magento-Adminbereich bereit.

So prüfen Sie, ob das Modul funktioniert

Prüfen Sie nach der Installation:

• Kowal -> Analytics -> Dashboard
• Stores -> Configuration -> Analytics

Wenn das Modul ordnungsgemäß aktiviert ist, sollten folgende Elemente sichtbar sein:

• das Modul-Dashboard,
• ein Zusammenfassungs-Widget im nativen Magento-Dashboard,
• der Konfigurationsbereich unter Stores -> Configuration.

Empfohlener technischer Test nach der Implementierung

Führen Sie einen einfachen End-to-End-Test durch:

1. Öffnen Sie die Shop-Seite.
2. Rufen Sie eine Produktseite auf.
3. Klicken Sie auf ein getracktes Element, beispielsweise ein Produkt in related_products oder einen Blogbeitrag.
4. Legen Sie das Produkt in den Warenkorb.
5. Geben Sie eine Bestellung auf.
6. Prüfen Sie, ob Ereignisse, Conversions und Attribution gespeichert wurden.

Wenn der Debug-Modus aktiviert ist, prüfen Sie:

• die Protokolle in der Browserkonsole,
• var/log/kowal_analytics_debug.log

Was sollte im HTML geprüft werden?

Wenn Sie bestätigen möchten, dass das Tracking beim Rendern der Seite funktioniert, prüfen Sie, ob folgende Attribute vorhanden sind:

• data-kowal-track-area
• data-kowal-track-area-id
• data-kowal-track-object
• data-kowal-track-id
• data-kowal-track-sku

Beispiel:

• Der Container des Bereichs related_products sollte data-kowal-track-area='related_products' enthalten.
• Ein einzelnes Produkt in diesem Bereich sollte data-kowal-track-object='product' und eine eigene data-kowal-track-id enthalten.

Typische Probleme nach der Installation

Das Dashboard ist sichtbar, enthält jedoch keine Daten

Prüfen Sie:

• ob die Consumer ausgeführt werden,
• ob der Cron funktioniert,
• ob Analytics in der Konfiguration aktiviert ist,
• ob der Tracker im Frontend geladen wird,
• ob auf der Seite tatsächlich Areas getrackt werden.

Ereignisse werden gespeichert, die Attribution ist jedoch unvollständig

Prüfen Sie:

• ob der Consumer kowal_analytics.attribution ausgeführt wird,
• ob Cron-Retry funktioniert,
• ob die Quellereignisse vor der abschließenden Berechnung der Attribution in der Datenbank eintreffen.

Die benutzerdefinierte Area wird nicht in den Berichten angezeigt

Prüfen Sie:

• ob die Area-Definition ordnungsgemäß gespeichert wurde,
• ob die Selektoren dem tatsächlichen DOM entsprechen,
• ob Runtime Apply data-kowal-track-* hinzufügt,
• ob der jeweilige Bereich über die für die weitere Analyse erforderlichen Objektkennungen verfügt.

Implementierungsempfehlung

Die sicherste Reihenfolge ist:

1. das Modul installieren,
2. Consumer und Cron starten,
3. den Debug-Modus aktivieren,
4. ein einfaches Produktszenario testen,
5. das Dashboard prüfen,
6. und erst danach das Tracking auf benutzerdefinierte Areas erweitern.