Guida alla configurazione di Kowal Analytics

Navigazione nel pannello amministrativo

Accessi principali al modulo:

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

Struttura della configurazione

Attualmente il modulo offre tre gruppi principali di impostazioni.

1. General

Percorso:

• Stores -> Configuration -> Analytics -> General

Campo:

• Enable Analytics

Significato:

• abilita o disabilita il tracking frontend e l’ulteriore elaborazione analytics per lo scope selezionato.

Raccomandazione:

• meglio abilitarlo per store view dopo aver verificato in precedenza il funzionamento di tracker e consumer.

2. Debug

Percorso:

• Stores -> Configuration -> Analytics -> Debug

Campi:

• Enable Backend Debug Log
• Enable Frontend Console Log

Significato:

• backend debug salva i log tecnici in:
  • var/log/kowal_analytics_debug.log
• frontend debug salva i log del tracker nella console del browser.

Uso:

• installazione,
• QA,
• analisi degli errori,
• test del selector assistant,
• conferma che gli eventi arrivino alla pipeline.

Raccomandazione:

• abilitare durante implementazione e test,
• disabilitare nell’ambiente di produzione al termine della validazione.

3. Tools

Percorso:

• Stores -> Configuration -> Analytics -> Tools

Campo:

• Enable Frontend Selector Assistant

Significato:

• mostra sullo storefront un helper che aiuta a indicare e preparare la configurazione per aree personalizzate basate su selettori.

Uso:

• mappatura di custom section,
• analisi della struttura DOM,
• preparazione delle definizioni di area senza modificare manualmente il codice.

Come interpretare la configurazione in pratica

Scope

Il modulo funziona nello scope Magento, quindi la configurazione può variare per:

• default,
• website,
• store view.

È più sicuro trattare il modulo come uno strumento per store view, perché:

• negozi diversi possono avere layout diversi,
• negozi diversi possono avere sezioni blog, CMS e merchandising diverse,
• i report per store view sono molto più affidabili a livello operativo.

Come interpretare i concetti di base del modulo

Area

Area è una sezione delimitata della pagina che vuoi misurare come fonte di impatto sulle vendite.

Esempi:

• 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 è un elemento specifico all’interno dell’area.

Esempi:

• un singolo prodotto in una lista,
• un articolo del blog,
• una categoria del blog,
• un tag,
• un banner,
• una slide.

Source Page

Source Page è la pagina da cui l’utente ha avviato un’interazione che ha portato poi alla vendita.

Esempi:

• scheda del prodotto di origine per related_products,
• articolo del blog per un prodotto cliccato,
• listing di categoria per un prodotto cliccato,
• risultati di ricerca per un prodotto.

Dashboard e report

Analytics Dashboard

È la schermata principale di panoramica. Mostra:

• attributed revenue,
• attributed orders,
• average order value,
• CTR,
• top areas,
• top supported products,
• top blog sources,
• link ai report dettagliati.

Questa schermata risponde alla domanda:

• co działa najlepiej

Area Report

Questo report risponde alle domande:

• quale area genera ricavi,
• quali object in questa area vendono,
• da quali source page proviene la vendita.

Esempio:

• related_products ha 18 ordini,
• al suo interno vende meglio Zing Jump Rope,
• la fonte più frequente di questo percorso è la scheda prodotto Affirm Water Bottle.

Product Context Report

È il report per aree prodotto come:

• related_products
• upsell_products
• crosssell_products
• category_listing
• search_results

Mostra la relazione:

• source product -> clicked object -> purchased SKU

Esempio:

• l’utente si trova sulla PDP Affirm Water Bottle,
• clicca WB05-S-Orange in related_products,
• acquista WB05-S-Orange.

Blog Commerce Report

È il report per aree blog:

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

Risponde alle domande:

• quale post vende,
• quale categoria del blog vende,
• quale tag supporta la vendita,
• quali SKU vengono acquistati dopo l’ingresso dal blog.

Object Report

È il report per un singolo object specifico.

Esempio:

• un prodotto in related_products,
• un articolo del blog da blog_post_listing,
• una categoria del blog da blog_sidebar_categories.

Mostra:

• quante impression ha avuto,
• quanti clic ha avuto,
• quanti ordini ha generato,
• quali ricavi gli sono stati attribuiti,
• da quali source page provenivano questi percorsi.

Source Page Report

È il report per una specifica pagina di origine.

Esempio:

• scheda prodotto Affirm Water Bottle,
• articolo del blog Jak wybrać bidon treningowy,
• listing di categoria Buty do biegania.

Mostra:

• quali clicked object da questa pagina vendono,
• quali SKU vengono acquistati dopo l’ingresso da questa pagina,
• quanti ordini e ricavi genera questa specifica pagina come punto di partenza del percorso.

Modelli di attribuzione

Modelli disponibili:

• Last Click
• First Click
• Assisted
• View Through

Come leggerli:

Last Click

Il migliore per la domanda:

• quale elemento ha chiuso direttamente la vendita.

First Click

Il migliore per la domanda:

• quale elemento ha avviato il percorso che porta all’acquisto.

Assisted

Il migliore per la domanda:

• quale elemento ha partecipato al percorso, anche se non è stato l’ultimo clic.

View Through

Il migliore per la domanda:

• se la sola esposizione della sezione ha avuto un impatto sulle vendite, anche senza clic.

Configurazione custom area

Puoi preparare una custom area tramite Frontend Selector Assistant.

Workflow tipico:

1. Abilita Enable Frontend Selector Assistant.
2. Apri lo storefront.
3. Avvia l’assistant.
4. Indica l’area.
5. Controlla il container selector proposto.
6. Controlla l’item selector proposto.
7. Controlla il link selector.
8. Salva la definizione.
9. Conferma che runtime apply abbia aggiunto data-kowal-track-*.
10. Testa il clic e il passaggio ai report.

Esempio di custom area

Supponiamo che nella homepage tu abbia un box promozionale con tre riquadri.

Puoi definire:

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

Allora il report mostrerà:

• quale riquadro è stato cliccato,
• quale ha portato all’acquisto,
• quali ricavi ha generato.

Workflow di test dopo la configurazione

La sequenza più sensata:

1. abilitare analytics,
2. abilitare backend debug,
3. abilitare frontend console log,
4. percorrere uno scenario utente,
5. controllare la dashboard,
6. controllare il report area,
7. passare all’object report oppure al source page report,
8. disabilitare il debug dopo aver confermato la correttezza.

Raccomandazioni operative

• mantieni i consumer sotto supervisor o systemd,
• assicurati che Magento cron funzioni costantemente,
• dopo modifiche al tema verifica che i selettori delle custom area corrispondano ancora al DOM,
• dopo modifiche al merchandising confronta i risultati per area,
• non interpretare il solo CTR come successo senza verificare ricavi e ordini.

Guida all’installazione di Kowal Analytics

Requisiti

Prima dell’installazione assicurati che:

• l’istanza Magento 2 funzioni correttamente,
• Composer abbia accesso al repository dei pacchetti Kowal,
• tu abbia accesso CLI a bin/magento,
• nell’ambiente sia possibile eseguire cron e queue consumers,
• l’ambiente disponga di scritture funzionanti verso il database e verso var/log.

Installazione tramite Composer

Aggiungi il repository Composer:

I dati di accesso al repository Composer, ovvero indirizzo e-mail del cliente e token di licenza, saranno inviati via e-mail dopo l’acquisto. Sono disponibili anche nel pannello cliente dopo l’accesso su kowal.store. Sostituisci TWOJ_EMAIL_KLIENTA con l’indirizzo e-mail del tuo account e TWOJ_TOKEN con il token ricevuto. Esegui i comandi nella directory principale di Magento.

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

Aggiungi le credenziali di accesso al repository privato:

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

Installa il modulo:

composer require kowal/module-analytics

Abilitazione del modulo

Esegui i comandi Magento standard:

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

Se il negozio funziona in production mode, esegui anche:

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

Avvio dei processi asincroni

Il modulo utilizza code ed elaborazione asincrona. Senza questo, dashboard e report non saranno completi.

Avvia i consumer richiesti:

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

Anche Magento cron deve funzionare correttamente, perché il modulo utilizza retry e backfill per l’attribuzione.

Controllo di base:

bin/magento cron:run

Cosa succede dopo l’installazione

Dopo una corretta installazione, il modulo:

• carica il tracker sullo storefront,
• registra gli eventi frontend,
• collega la sessione analytics a quote,
• trasferisce gli identificatori analytics a sales_order,
• registra conversioni e righe di conversione,
• calcola l’attribuzione degli ordini ad area e object,
• mette a disposizione dashboard e report dettagliati nel pannello Magento.

Dove verificare se il modulo funziona

Dopo l’installazione controlla:

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

Se il modulo è attivo correttamente, dovresti vedere:

• la dashboard del modulo,
• il widget riepilogativo nella dashboard nativa di Magento,
• la sezione di configurazione in Stores -> Configuration.

Test tecnico consigliato dopo l’implementazione

Esegui un semplice test end-to-end:

1. Apri la pagina del negozio.
2. Vai alla scheda prodotto.
3. Clicca un elemento tracciato, per esempio un prodotto in related_products oppure un articolo del blog.
4. Aggiungi il prodotto al carrello.
5. Effettua un ordine.
6. Verifica che eventi, conversioni e attribuzione siano stati salvati.

Se il debug è abilitato, controlla:

• i log nella console del browser,
• var/log/kowal_analytics_debug.log

Cosa vale la pena controllare nell’HTML

Se vuoi confermare che il tracking funzioni nel render della pagina, verifica la presenza degli attributi:

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

Esempio:

• il container della sezione related_products dovrebbe avere data-kowal-track-area='related_products'
• un singolo prodotto in questa sezione dovrebbe avere data-kowal-track-object='product' e il proprio data-kowal-track-id

Problemi tipici dopo l’installazione

La dashboard è visibile, ma non ci sono dati

Controlla:

• se i consumer sono in esecuzione,
• se cron funziona,
• se analytics è abilitato nella configurazione,
• se il tracker si carica sul frontend,
• se nella pagina sono effettivamente presenti area tracciate.

Gli eventi vengono salvati, ma l’attribuzione è incompleta

Controlla:

• se il consumer kowal_analytics.attribution funziona,
• se il cron retry funziona,
• se gli eventi di origine arrivano al database prima del calcolo finale dell’attribuzione.

La custom area non compare nei report

Controlla:

• se la definizione dell’area è stata salvata correttamente,
• se i selettori corrispondono al DOM reale,
• se runtime apply aggiunge data-kowal-track-*,
• se l’area specifica ha gli identificatori degli oggetti necessari per l’analisi successiva.

Raccomandazione di implementazione

La sequenza più sicura è:

1. installare il modulo,
2. avviare consumer e cron,
3. abilitare il debug,
4. testare un semplice scenario prodotto,
5. controllare la dashboard,
6. solo dopo estendere il tracking alle custom area.