Instrucciones de configuración de Kowal Analytics

Navegación en el panel de administración

Entradas principales al módulo:

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

Estructura de la configuración

Actualmente, el módulo ofrece tres grupos principales de ajustes.

1. General

Ruta:

• Stores -> Configuration -> Analytics -> General

Campo:

• Enable Analytics

Significado:

• activa o desactiva el tracking frontend y el procesamiento posterior de analytics para el scope seleccionado.

Recomendación:

• lo mejor es activarlo per store view tras verificar previamente el funcionamiento de trackers y consumers.

2. Debug

Ruta:

• Stores -> Configuration -> Analytics -> Debug

Campos:

• Enable Backend Debug Log
• Enable Frontend Console Log

Significado:

• backend debug guarda logs técnicos en:
  • var/log/kowal_analytics_debug.log
• frontend debug guarda logs del tracker en la consola del navegador.

Uso:

• instalación,
• QA,
• análisis de errores,
• pruebas del selector assistant,
• confirmación de que los eventos llegan al pipeline.

Recomendación:

• activarlo durante la implementación y las pruebas,
• desactivarlo en el entorno de producción tras finalizar la validación.

3. Tools

Ruta:

• Stores -> Configuration -> Analytics -> Tools

Campo:

• Enable Frontend Selector Assistant

Significado:

• muestra un helper en el storefront que ayuda a señalar y preparar la configuración de area propias basadas en selectores.

Uso:

• mapeo de custom section,
• análisis de la estructura DOM,
• preparación de definiciones de area sin edición manual del código.

Cómo entender la configuración en la práctica

Scope

El módulo funciona en el scope de Magento, por lo que la configuración puede ser diferente para:

• default,
• website,
• store view.

Lo más seguro es tratar el módulo como una herramienta per store view, porque:

• distintas tiendas pueden tener un layout diferente,
• distintas tiendas pueden tener secciones de blog, CMS y merchandising diferentes,
• los informes per store view son mucho más fiables operativamente.

Cómo entender los conceptos básicos del módulo

Area

Area es una zona delimitada de la página que quieres medir como fuente de impacto en las ventas.

Ejemplos:

• 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 es un elemento concreto dentro de area.

Ejemplos:

• un producto individual en una lista,
• una entrada de blog,
• una categoría de blog,
• una etiqueta,
• un banner,
• un slide.

Source Page

Source Page es la página desde la que el usuario inició una interacción que conduce posteriormente a la venta.

Ejemplos:

• ficha del producto de origen para related_products,
• entrada de blog para el producto clicado,
• listing de categoría para el producto clicado,
• resultados de búsqueda para el producto.

Dashboard e informes

Analytics Dashboard

Es la pantalla principal de resumen. Muestra:

• attributed revenue,
• attributed orders,
• average order value,
• CTR,
• top areas,
• top supported products,
• top blog sources,
• enlaces a informes detallados.

Esta pantalla responde a la pregunta:

• co działa najlepiej

Area Report

Este informe responde a las preguntas:

• qué area genera ingresos,
• qué object en esa area venden,
• de qué source page procede la venta.

Ejemplo:

• related_products tiene 18 pedidos,
• el que mejor vende dentro de ella es Zing Jump Rope,
• la fuente más frecuente de esa ruta es la ficha de producto Affirm Water Bottle.

Product Context Report

Es un informe para áreas de producto como:

• related_products
• upsell_products
• crosssell_products
• category_listing
• search_results

Muestra la relación:

• source product -> clicked object -> purchased SKU

Ejemplo:

• el usuario está en la PDP Affirm Water Bottle,
• hace clic en WB05-S-Orange en related_products,
• compra WB05-S-Orange.

Blog Commerce Report

Es un informe para áreas de blog:

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

Responde a las preguntas:

• qué post vende,
• qué categoría de blog vende,
• qué etiqueta apoya la venta,
• qué SKU se compran después de entrar desde el blog.

Object Report

Es un informe para un object concreto.

Ejemplo:

• un producto en related_products,
• una entrada de blog de blog_post_listing,
• una categoría de blog de blog_sidebar_categories.

Muestra:

• cuántas impresiones tuvo,
• cuántos clics tuvo,
• cuántos pedidos generó,
• qué ingresos se le atribuyeron,
• de qué source page procedían esas rutas.

Source Page Report

Es un informe para una página de origen concreta.

Ejemplo:

• ficha de producto Affirm Water Bottle,
• entrada de blog Jak wybrać bidon treningowy,
• listing de categoría Buty do biegania.

Muestra:

• qué clicked object de esa página venden,
• qué SKU se compran después de entrar desde esa página,
• cuántos pedidos e ingresos genera esa página concreta como punto de inicio de la ruta.

Modelos de atribución

Modelos disponibles:

• Last Click
• First Click
• Assisted
• View Through

Cómo leerlos:

Last Click

El mejor para la pregunta:

• qué elemento cerró directamente la venta.

First Click

El mejor para la pregunta:

• qué elemento inició la ruta que llevó a la compra.

Assisted

El mejor para la pregunta:

• qué elemento participó en la ruta, aunque no fuera el último clic.

View Through

El mejor para la pregunta:

• si la mera exposición de la sección influyó en la venta, incluso sin clic.

Configuración de custom area

Puedes preparar custom area mediante Frontend Selector Assistant.

Workflow típico:

1. Activa Enable Frontend Selector Assistant.
2. Abre el storefront.
3. Ejecuta el assistant.
4. Señala el área.
5. Comprueba el container selector propuesto.
6. Comprueba el item selector propuesto.
7. Comprueba el link selector.
8. Guarda la definición.
9. Confirma que runtime apply ha añadido data-kowal-track-*.
10. Prueba el clic y pasa a los informes.

Ejemplo de custom area

Supongamos que en la página de inicio tienes un box promocional con tres tarjetas.

Puedes definir:

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

Entonces el informe mostrará:

• en qué tarjeta se hizo clic,
• cuál condujo a la compra,
• qué ingresos generó.

Workflow de prueba tras la configuración

El orden más razonable:

1. activar analytics,
2. activar backend debug,
3. activar frontend console log,
4. recorrer un escenario de usuario,
5. comprobar el dashboard,
6. comprobar el informe area,
7. bajar hasta object report o source page report,
8. desactivar debug tras confirmar que todo es correcto.

Recomendaciones operativas

• mantén los consumers bajo supervisor o systemd,
• asegúrate de que Magento cron funcione de forma continua,
• tras cambios en el tema, comprueba si los selectores custom area siguen ajustándose al DOM,
• tras cambios en merchandising, compara los resultados per area,
• no interpretes solo el CTR como éxito sin comprobar ingresos y pedidos.

Instrucciones de instalación de Kowal Analytics

Requisitos

Antes de la instalación, asegúrate de que:

• la instancia de Magento 2 funciona correctamente,
• Composer tiene acceso al repositorio de paquetes Kowal,
• tienes acceso CLI abin/magento,
• en el entorno se pueden ejecutar cron y queue consumers,
• el entorno tiene correctamente operativas las escrituras en la base de datos y envar/log.

Instalación mediante Composer

Añade el repositorio Composer:

Recibirás por correo electrónico los datos de acceso al repositorio Composer (dirección de e-mail del cliente y token de licencia) después de la compra. También están disponibles en el panel de cliente tras iniciar sesión en kowal.store. Sustituye TWOJ_EMAIL_KLIENTA por la dirección de e-mail de tu cuenta y TWOJ_TOKEN por el token recibido. Ejecuta los comandos en el directorio raíz de Magento.

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

Añade los datos de acceso al repositorio privado:

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

Instala el módulo:

composer require kowal/module-analytics

Activación del módulo

Ejecuta los comandos estándar de Magento:

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

Si la tienda funciona en production mode, ejecuta también:

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

Puesta en marcha de procesos asíncronos

El módulo utiliza colas y procesamiento asíncrono. Sin ello, el dashboard y los informes no estarán completos.

Ejecuta los consumers requeridos:

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 también debe funcionar correctamente, porque el módulo utiliza retry y backfill para la atribución.

Comprobación básica:

bin/magento cron:run

Qué ocurre después de la instalación

Tras una instalación correcta, el módulo:

• carga el tracker en el storefront,
• guarda eventos frontend,
• vincula la sesión analytics conquote,
• transfiere los identificadores analytics asales_order,
• guarda conversiones y posiciones de conversión,
• calcula la atribución de pedidos a area y object,
• ofrece dashboard e informes detallados en el panel de Magento.

Dónde comprobar si el módulo funciona

Después de la instalación, comprueba:

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

Si el módulo está correctamente activo, deberías ver:

• el dashboard del módulo,
• el widget de resumen en el dashboard nativo de Magento,
• la sección de configuración en Stores -> Configuration.

Prueba técnica recomendada tras la implementación

Realiza una prueba end-to-end sencilla:

1. Abre la página de la tienda.
2. Entra en una ficha de producto.
3. Haz clic en un elemento trackeado, por ejemplo un producto enrelated_productso una entrada de blog.
4. Añade el producto al carrito.
5. Realiza un pedido.
6. Comprueba si se han guardado los eventos, las conversiones y la atribución.

Si debug está activado, comprueba:

• los logs en la consola del navegador,
• var/log/kowal_analytics_debug.log

Qué conviene comprobar en el HTML

Si quieres confirmar que el tracking funciona al renderizar la página, comprueba la presencia de los atributos:

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

Ejemplo:

• el contenedor de la secciónrelated_productsdebería tenerdata-kowal-track-area="related_products"
• un producto individual en esa sección debería tenerdata-kowal-track-object="product"y su propiodata-kowal-track-id

Problemas habituales después de la instalación

El dashboard es visible, pero no hay datos

Comprueba:

• si los consumers están funcionando,
• si cron funciona,
• si analytics está activado en la configuración,
• si el tracker se carga en el frontend,
• si en la página hay realmente area trackeadas.

Los eventos se guardan, pero la atribución está incompleta

Comprueba:

• si funciona el consumerkowal_analytics.attribution,
• si funciona cron retry,
• si los eventos de origen llegan a la base antes del recálculo final de la atribución.

Custom area no aparece en los informes

Comprueba:

• si la definición de area se ha guardado correctamente,
• si los selectores coinciden con el DOM real,
• si runtime apply añadedata-kowal-track-*,
• si esa área tiene los identificadores de objetos necesarios para el análisis posterior.

Recomendación de implementación

El orden más seguro es:

1. instalar el módulo,
2. ejecutar consumers y cron,
3. activar debug,
4. probar un escenario de producto sencillo,
5. comprobar el dashboard,
6. solo después ampliar el tracking a custom area.