Instrucțiuni de instalare Kowal Analytics

Cerințe

Înainte de instalare, asigură-te că:

• instanța Magento 2 funcționează corect,
• Composer are acces la repository-ul de pachete Kowal,
• ai acces CLI la bin/magento,
• în mediu se pot rula cron și queue consumers,
• mediul are scrieri funcționale în baza de date și în var/log.

Instalare prin Composer

Adaugă repository-ul Composer:

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

Adaugă datele de acces la repository-ul privat:

composer config http-basic.repo.kowal.store  

Instalează modulul:

composer require kowal/module-analytics

Activarea modulului

Rulează comenzile standard Magento:

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

Dacă magazinul funcționează în production mode, execută și:

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

Pornirea proceselor asincrone

Modulul folosește cozi și procesare asincronă. Fără acestea, dashboardul și rapoartele nu vor fi complete.

Pornește consumerii necesari:

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

Magento cron trebuie, de asemenea, să funcționeze corect, deoarece modulul folosește retry și backfill pentru atribuire.

Verificare de bază:

bin/magento cron:run

Ce se întâmplă după instalare

După instalarea corectă, modulul:

• încarcă trackerul pe storefront,
• salvează evenimentele frontend,
• leagă sesiunea analytics de quote,
• transferă identificatorii analytics în sales_order,
• salvează conversiile și pozițiile conversiilor,
• calculează atribuirea comenzilor pentru area și object,
• pune la dispoziție dashboardul și rapoarte detaliate în panoul Magento.

Unde verifici dacă modulul funcționează

După instalare, verifică:

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

Dacă modulul este activ corect, ar trebui să vezi:

• dashboardul modulului,
• widgetul de sumar în dashboardul nativ Magento,
• secțiunea de configurare în Stores -> Configuration.

Test tehnic recomandat după implementare

Efectuează un test simplu end-to-end:

1. Deschide pagina magazinului.
2. Intră pe pagina unui produs.
3. Accesează un element urmărit, de exemplu un produs din related_products sau un articol de blog.
4. Adaugă produsul în coș.
5. Plasează comanda.
6. Verifică dacă evenimentele, conversiile și atribuirea au fost salvate.

Dacă debug este activat, verifică:

• logurile din consola browserului,
• var/log/kowal_analytics_debug.log

Ce merită verificat în HTML

Dacă vrei să confirmi că trackingul funcționează la randarea paginii, verifică prezența atributelor:

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

Exemplu:

• containerul secțiunii related_products ar trebui să aibă data-kowal-track-area='related_products'
• un produs individual din acea secțiune ar trebui să aibă data-kowal-track-object='product' și propriul data-kowal-track-id

Probleme tipice după instalare

Dashboardul este vizibil, dar nu există date

Verifică:

• dacă consumerii funcționează,
• dacă cron funcționează,
• dacă analytics este activat în configurație,
• dacă trackerul se încarcă pe frontend,
• dacă pe pagină există într-adevăr area urmărite.

Evenimentele sunt salvate, dar atribuirea este incompletă

Verifică:

• dacă funcționează consumerul kowal_analytics.attribution,
• dacă funcționează cron retry,
• dacă evenimentele sursă ajung în baza de date înainte de calculul final al atribuirii.

Custom area nu apare în rapoarte

Verifică:

• dacă definiția area a fost salvată corect,
• dacă selectorii corespund DOM-ului real,
• dacă runtime apply adaugă data-kowal-track-*,
• dacă zona respectivă are identificatorii de obiect necesari pentru analiza ulterioară.

Recomandare de implementare

Cea mai sigură ordine este următoarea:

1. instalezi modulul,
2. pornești consumerii și cron,
3. activezi debug,
4. testezi un scenariu simplu de produs,
5. verifici dashboardul,
6. abia apoi extinzi trackingul la custom area.

Instrucțiuni de configurare Kowal Analytics

Navigare în panoul de administrare

Punctele principale de acces în modul:

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

Structura configurației

În prezent, modulul oferă trei grupuri principale de setări.

1. General

Cale:

• Stores -> Configuration -> Analytics -> General

Câmp:

• Enable Analytics

Semnificație:

• activează sau dezactivează trackingul frontend și procesarea ulterioară analytics pentru scope-ul selectat.

Recomandare:

• cel mai bine este să fie activat per store view după verificarea în prealabil a funcționării trackerelor și consumerilor.

2. Debug

Cale:

• Stores -> Configuration -> Analytics -> Debug

Câmpuri:

• Enable Backend Debug Log
• Enable Frontend Console Log

Semnificație:

• backend debug salvează logurile tehnice în:
  • var/log/kowal_analytics_debug.log
• frontend debug salvează logurile trackerului în consola browserului.

Utilizare:

• instalare,
• QA,
• analiza erorilor,
• teste ale selector assistant,
• confirmarea faptului că evenimentele intră în pipeline.

Recomandare:

• activează pe durata implementării și a testelor,
• dezactivează în mediul de producție după finalizarea validării.

3. Tools

Cale:

• Stores -> Configuration -> Analytics -> Tools

Câmp:

• Enable Frontend Selector Assistant

Semnificație:

• afișează un helper pe storefront care ajută la indicarea și pregătirea configurației pentru propriile area bazate pe selectori.

Utilizare:

• maparea secțiunilor custom,
• analiza structurii DOM,
• pregătirea definiției area fără editarea manuală a codului.

Cum trebuie înțeleasă configurația în practică

Scope

Modulul funcționează în scope-ul Magento, deci configurația poate fi diferită pentru:

• default,
• website,
• store view.

Cel mai sigur este să tratezi modulul ca un instrument per store view, deoarece:

• diferite magazine pot avea layouturi diferite,
• diferite magazine pot avea secțiuni diferite de blog, CMS și merchandising,
• rapoartele per store view sunt mult mai fiabile din punct de vedere operațional.

Cum trebuie înțelese conceptele de bază din modul

Area

Area este o zonă separată a paginii pe care vrei să o măsori ca sursă de influență asupra vânzărilor.

Exemple:

• 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 este un element concret din interiorul area.

Exemple:

• un produs individual din listă,
• un articol de blog,
• o categorie de blog,
• un tag,
• un banner,
• un slide.

Source Page

Source Page este pagina de pe care utilizatorul a pornit interacțiunea care a dus mai departe la vânzare.

Exemple:

• pagina produsului sursă pentru related_products,
• articolul de blog pentru produsul accesat,
• listarea categoriei pentru produsul accesat,
• rezultatele căutării pentru produs.

Dashboard și rapoarte

Analytics Dashboard

Acesta este ecranul principal de ansamblu. Afișează:

• attributed revenue,
• attributed orders,
• average order value,
• CTR,
• top areas,
• top supported products,
• top blog sources,
• linkuri către rapoarte detaliate.

Acest ecran răspunde la întrebarea:

• ce funcționează cel mai bine

Area Report

Acest raport răspunde la întrebările:

• care area generează venit,
• ce object din acea area vând,
• din ce source page provine vânzarea.

Exemplu:

• related_products are 18 comenzi,
• cel mai bine vinde aici Zing Jump Rope,
• cel mai frecvent sursa acestui traseu este pagina produsului Affirm Water Bottle.

Product Context Report

Acesta este raportul pentru zone de produs, cum ar fi:

• related_products
• upsell_products
• crosssell_products
• category_listing
• search_results

Arată relația:

• source product -> clicked object -> purchased SKU

Exemplu:

• utilizatorul este pe PDP-ul Affirm Water Bottle,
• accesează WB05-S-Orange în related_products,
• cumpără WB05-S-Orange.

Blog Commerce Report

Acesta este raportul pentru zonele de blog:

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

Răspunde la întrebările:

• ce post vinde,
• ce categorie de blog vinde,
• ce tag susține vânzarea,
• ce SKU-uri sunt cumpărate după intrarea din blog.

Object Report

Acesta este raportul pentru un singur object concret.

Exemplu:

• un produs în related_products,
• un articol de blog din blog_post_listing,
• o categorie de blog din blog_sidebar_categories.

Arată:

• câte impresii a avut,
• câte clickuri a avut,
• câte comenzi a generat,
• ce venit i-a fost atribuit,
• din ce source page au provenit aceste trasee.

Source Page Report

Acesta este raportul pentru o singură pagină sursă concretă.

Exemplu:

• pagina produsului Affirm Water Bottle,
• articolul de blog Cum să alegi un bidon pentru antrenament,
• listarea categoriei Pantofi de alergare.

Arată:

• ce clicked object de pe această pagină vând,
• ce SKU-uri sunt cumpărate după intrarea de pe această pagină,
• câte comenzi și ce venit generează această pagină concretă ca punct de pornire al traseului.

Modele de atribuire

Modele disponibile:

• Last Click
• First Click
• Assisted
• View Through

Cum trebuie interpretate:

Last Click

Cel mai potrivit pentru întrebarea:

• ce element a finalizat direct vânzarea.

First Click

Cel mai potrivit pentru întrebarea:

• ce element a început traseul care a dus la achiziție.

Assisted

Cel mai potrivit pentru întrebarea:

• ce element a participat la traseu, chiar dacă nu a fost ultimul click.

View Through

Cel mai potrivit pentru întrebarea:

• dacă simpla expunere a secțiunii a avut impact asupra vânzării, chiar și fără click.

Configurarea custom area

Poți pregăti custom area prin Frontend Selector Assistant.

Workflow tipic:

1. Activează Enable Frontend Selector Assistant.
2. Deschide storefrontul.
3. Pornește assistantul.
4. Indică zona.
5. Verifică container selector propus.
6. Verifică item selector propus.
7. Verifică link selector.
8. Salvează definiția.
9. Confirmă că runtime apply a adăugat data-kowal-track-*.
10. Testează clickul și trecerea la rapoarte.

Exemplu de custom area

Să presupunem că pe pagina principală ai un box promoțional cu trei tile-uri.

Poți defini:

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

Atunci raportul va arăta:

• care tile a fost accesat,
• care a dus la achiziție,
• ce venit a generat.

Workflow de test după configurare

Cea mai logică ordine:

1. activezi analytics,
2. activezi backend debug,
3. activezi frontend console log,
4. parcurgi scenariul utilizatorului,
5. verifici dashboardul,
6. verifici raportul area,
7. cobori la object report sau source page report,
8. dezactivezi debug după confirmarea corectitudinii.

Recomandări operaționale

• menține consumerii sub supervisor sau systemd,
• asigură-te că Magento cron funcționează permanent,
• după modificările temei verifică dacă selectorii custom area încă se potrivesc cu DOM-ul,
• după modificările de merchandising compară rezultatele per area,
• nu interpreta doar CTR-ul ca succes fără să verifici venitul și comenzile.