Kowal Analytics configuration guide

Admin panel navigation

Main entry points to the module:

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

Configuration structure

The module currently provides three main groups of settings.

1. General

Path:

• Stores -> Configuration -> Analytics -> General

Field:

• Enable Analytics

Meaning:

• enables or disables frontend tracking and further analytics processing for the selected scope.

Recommendation:

• it is best to enable it per store view after first verifying that trackers and consumers work.

2. Debug

Path:

• Stores -> Configuration -> Analytics -> Debug

Fields:

• Enable Backend Debug Log
• Enable Frontend Console Log

Meaning:

• backend debug writes technical logs to:
  • var/log/kowal_analytics_debug.log
• frontend debug writes tracker logs to the browser console.

Use cases:

• installation,
• QA,
• error analysis,
• selector assistant tests,
• confirmation that events reach the pipeline.

Recommendation:

• enable it during deployment and testing,
• disable it in the production environment after validation is complete.

3. Tools

Path:

• Stores -> Configuration -> Analytics -> Tools

Field:

• Enable Frontend Selector Assistant

Meaning:

• shows a helper on the storefront that helps indicate and prepare configuration for custom areas based on selectors.

Use cases:

• mapping custom sections,
• analyzing the DOM structure,
• preparing area definitions without manually editing code.

How to understand configuration in practice

Scope

The module works within the Magento scope, so configuration may differ for:

• default,
• website,
• store view.

The safest approach is to treat the module as a per-store-view tool because:

• different stores may have different layouts,
• different stores may have different blog, CMS, and merchandising sections,
• reports per store view are much more reliable operationally.

How to understand the basic concepts in the module

Area

Area is a defined page section that you want to measure as a source of influence on sales.

Examples:

• 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 is a specific element inside an area.

Examples:

• a single product on a list,
• one blog post,
• one blog category,
• one tag,
• one banner,
• one slide.

Source Page

Source Page is the page from which the user interacted in a way that led further toward a sale.

Examples:

• source product page for related_products,
• blog post for the clicked product,
• category listing for the clicked product,
• search results for the product.

Dashboard and reports

Analytics Dashboard

This is the main overview screen. It shows:

• attributed revenue,
• attributed orders,
• average order value,
• CTR,
• top areas,
• top supported products,
• top blog sources,
• links to detailed reports.

This screen answers the question:

• co działa najlepiej

Area Report

This report answers the questions:

• which area generates revenue,
• which objects in this area sell,
• which source pages sales come from.

Example:

• related_products has 18 orders,
• Zing Jump Rope sells best in it,
• the most common source of this path is the product page Affirm Water Bottle.

Product Context Report

This is a report for product areas such as:

• related_products
• upsell_products
• crosssell_products
• category_listing
• search_results

It shows the relationship:

• source product -> clicked object -> purchased SKU

Example:

• the user is on the Affirm Water Bottle PDP,
• clicks WB05-S-Orange in related_products,
• buys WB05-S-Orange.

Blog Commerce Report

This is a report for blog areas:

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

It answers the questions:

• which post sells,
• which blog category sells,
• which tag supports sales,
• which SKUs are purchased after entering from the blog.

Object Report

This is a report for one specific object.

Example:

• one product in related_products,
• one blog post from blog_post_listing,
• one blog category from blog_sidebar_categories.

It shows:

• how many impressions it had,
• how many clicks it had,
• how many orders it generated,
• what revenue was attributed to it,
• which source pages these paths came from.

Source Page Report

This is a report for one specific source page.

Example:

• product page Affirm Water Bottle,
• blog post Jak wybrać bidon treningowy,
• category listing Buty do biegania.

It shows:

• which clicked objects from this page sell,
• which SKUs are purchased after entering from this page,
• how many orders and how much revenue this specific page generates as the starting point of the path.

Attribution models

Available models:

• Last Click
• First Click
• Assisted
• View Through

How to read them:

Last Click

Best for the question:

• which element directly closed the sale.

First Click

Best for the question:

• which element started the path leading to purchase.

Assisted

Best for the question:

• which element participated in the path, even if it was not the last click.

View Through

Best for the question:

• whether simply exposing the section had an impact on sales, even without a click.

Custom area configuration

You can prepare a custom area through Frontend Selector Assistant.

Typical workflow:

1. Enable Enable Frontend Selector Assistant.
2. Open the storefront.
3. Launch the assistant.
4. Select the area.
5. Check the proposed container selector.
6. Check the proposed item selector.
7. Check the link selector.
8. Save the definition.
9. Confirm that runtime apply has added data-kowal-track-*.
10. Test the click and move on to the reports.

Custom area example

Assume that your homepage has a promotional box with three tiles.

You can define:

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

Then the report will show:

• which tile was clicked,
• which one led to a purchase,
• what revenue it generated.

Testing workflow after configuration

The most sensible order:

1. enable analytics,
2. enable backend debug,
3. enable frontend console log,
4. go through the user scenario,
5. check the dashboard,
6. check the area report,
7. drill down to the object report or source page report,
8. disable debug after confirming correctness.

Operational recommendations

• keep consumers under supervisor or systemd,
• make sure Magento cron runs continuously,
• after theme changes, check whether custom area selectors still match the DOM,
• after merchandising changes, compare results per area,
• do not interpret CTR alone as success without checking revenue and orders.

Kowal Analytics installation guide

Requirements

Before installation, make sure that:

• the Magento 2 instance works correctly,
• Composer has access to the Kowal package repository,
• you have CLI access to bin/magento,
• cron and queue consumers can be run in the environment,
• the environment correctly writes to the database and to var/log.

Installation via Composer

Add the Composer repository:

Access credentials for the Composer repository, including the customer email address and license token, will be sent to you by email after purchase. They are also available in the customer panel after logging in at kowal.store. Replace TWOJ_EMAIL_KLIENTA with your account email address and TWOJ_TOKEN with the token you received. Run the commands in the Magento root directory.

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

Add access credentials for the private repository:

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

Install the module:

composer require kowal/module-analytics

Enable the module

Run the standard Magento commands:

bin/magento module:enable Kowal_Analytics
bin/magento setup:upgrade
bin/magento cache:flush

If the store runs in production mode, also run:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

Starting asynchronous processes

The module uses queues and asynchronous processing. Without this, the dashboard and reports will not be complete.

Start the required consumers:

bin/magento queue:consumers:start kowal_analytics.raw_events
bin/magento queue:consumers:start kowal_analytics.conversion
bin/magento queue:consumers:start kowal_analytics.attribution

Magento cron must also work correctly because the module uses retry and backfill for attribution.

Basic check:

bin/magento cron:run

What happens after installation

After correct installation, the module:

• loads the tracker on the storefront,
• records frontend events,
• links the analytics session with quote,
• transfers analytics identifiers to sales_order,
• records conversions and conversion items,
• calculates order attribution to area and object,
• provides a dashboard and detailed reports in the Magento admin panel.

Where to check whether the module works

After installation, check:

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

If the module is properly active, you should see:

• the module dashboard,
• a summary widget on the native Magento dashboard,
• the configuration section in Stores -> Configuration.

Recommended technical test after deployment

Run a simple end-to-end test:

1. Open the store page.
2. Go to a product page.
3. Click a tracked element, for example a product in related_products or a blog post.
4. Add the product to the cart.
5. Place an order.
6. Check whether events, conversions, and attribution have been saved.

If debug is enabled, check:

• logs in the browser console,
• var/log/kowal_analytics_debug.log

What is worth checking in HTML

If you want to confirm that tracking works on page render, check for the presence of these attributes:

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

Example:

• the related_products section container should have data-kowal-track-area='related_products'
• a single product in this section should have data-kowal-track-object='product' and its own data-kowal-track-id

Common problems after installation

The dashboard is visible, but there is no data

Check:

• whether the consumers are running,
• whether cron is running,
• whether analytics is enabled in the configuration,
• whether the tracker loads on the frontend,
• whether there are actually tracked areas on the page.

Events are saved, but attribution is incomplete

Check:

• whether the kowal_analytics.attribution consumer is running,
• whether cron retry works,
• whether source events reach the database before the final attribution recalculation.

Custom area does not appear in reports

Check:

• whether the area definition was saved correctly,
• whether selectors match the real DOM,
• whether runtime apply adds data-kowal-track-*,
• whether the area has object identifiers needed for further analysis.

Implementation recommendation

The safest order is:

1. install the module,
2. start consumers and cron,
3. enable debug,
4. test one simple product scenario,
5. check the dashboard,
6. only then extend tracking to custom areas.