Analytics Integrations (Matomo, Databox, Criteo, Contactpigeon)

Flow ID: IN-12 | Module(s): src/Analytics/, ecommercen/libraries/, ecommercen/feeds/, ecommercen/helpers/ | Complexity: High

Business Overview

Ecommercen integrates with multiple analytics and marketing platforms to provide merchants with comprehensive visitor tracking, business intelligence dashboards, and retargeting product feeds. These integrations fall into three categories:

Server-side tracking (Matomo) -- Real-time visitor profiling, ecommerce event tracking, site search analytics, and user identity stitching via the Matomo PHP SDK with bulk tracking and circuit breaker protection.
Business intelligence push (Databox) -- Hourly push of 15+ aggregated metrics (revenue, orders, customers, shipping, referrers, geographic breakdowns) to the Databox dashboard API.
Product catalog feeds (Criteo, Contactpigeon) -- XML feed exports that power retargeting ad campaigns and personalized push notifications.

A shared tracking_helper.php provides client-side analytics data transforms (GA4 purchase events, platform-specific product ID prefixes, category hierarchy mapping).

API Reference

Matomo Tracking API (Server-Side)

Method	Parameters	Description
`trackPageView($pageTitle)`	string	Tracks a page view event
`trackLoginEvent($userId, $email)`	int, string	Tracks Auth/Login event (value: 1)
`trackRegisterEvent($userId, $email)`	int, string	Tracks Auth/Registration event (value: 5)
`trackSiteSearch($keyword, $category, $count)`	string, ?string, ?int	Tracks internal search query
`trackEcommerceOrder(...)`	orderId, grandTotal, subTotal, tax, shipping, discount	Tracks completed order
`trackEcommerceCartUpdate($grandTotal)`	float	Tracks cart state change
`setEcommerceView($sku, $name, $category, $price)`	mixed	Sets product/category page context
`addEcommerceItem($sku, $name, $category, $price, $qty)`	mixed	Adds item to current transaction
`flush()`	--	Sends all queued actions in bulk HTTP request

Databox Push API

Metric Key	SQL Source	Attributes
`Revenue`	`SUM(total_vat)`, `SUM(total)`	`vat`: With Vat / No Vat
`Orders`	`COUNT(id)`	--
`Quantity`	`SUM(qty)`	--
`Average Order Value`	`AVG(total_vat)`	--
`Registrations`	`COUNT(customer.id)`	--
`Customers`	`COUNT(customer.id)`	`registration`: Registered / No registered
`Order Method`	`COUNT(id)`	`method`: By phone / On line
`Payment Method`	`COUNT(id)`	`method`: payway value
`Shipping Cost`	`COUNT(id)`	`cost`: Paid / Free
`Shipping type`	`COUNT(id)`	`transporter`: transporter name
`Picking point`	`COUNT(id)`	`store`: store address
`Marketplaces`	`COUNT(id)`	`chanel`: marketplace domain
`Referrer`	`COUNT(id)`	`channel`: referrer domain
`Country`	`COUNT(id)`	`country`: country name
`County`	`COUNT(id)`	`county`: county name

Feed Endpoints

Platform	Endpoint	Controller
Criteo	`GET /xml/criteo`	`AdvCriteoCatalog`
Contactpigeon	`GET /xml/contactpigeon`	`AdvContactpigeonXml`

Tracking Helper Functions

Function	Description
`productIdToGoogleId($id)`	Prefixes product ID for Google Analytics
`productIdToFaceBookId($id)`	Prefixes product ID for Facebook Pixel
`productIdToManagoId($id)`	Prefixes product ID for Manago
`applyCategoriesToItemGA4($item, $cats)`	Maps up to 5 category levels to GA4 `item_category*` fields
`trackPurchase($orderData)`	Builds GA4 purchase event payload

Code Flow

Matomo Server-Side Tracking

Page Request (storefront)
  -> Adv_front_controller (base controller)
     -> MatomoTracking is initialized via DI with:
        - Config: enabled, baseUrl, siteId, token, productIdPrefix, timeout
        - CircuitBreaker (optional, configured via APP_CB_MATOMO_* env vars)
     -> During page lifecycle:
        -> setEcommerceView() on product pages
        -> addEcommerceItem() for cart items
        -> trackPageView() / trackSiteSearch() / trackEcommerceOrder()
     -> On shutdown/deferred:
        -> flush() sends all queued actions via bulk HTTP POST
           -> CircuitBreaker check: if open, silently skip
           -> On failure: recordFailure(), log error
           -> On success: recordSuccess()

Databox Hourly Push

Cron: AdvReportingToDatabox job
  -> Check registry: DATABOX.ENABLED, DATABOX.TOKEN
  -> Initialize AdvDatabox (legacy) or Databox (client) with token
  -> allData() calls 15 metric methods sequentially:
     -> Each method:
        1. Build SQL query (3-month window, or 3-year for initialization)
        2. Execute query, get hourly-aggregated results
        3. Transform to Databox push format [{key, value, date, unit?, attributes?}]
        4. Chunk into batches of 500
        5. POST each batch to https://push.databox.com/data
           -> Rate limiting: sleep(1) every 10 API calls
           -> Auth: Basic auth with token

Criteo Catalog Feed

HTTP GET /xml/criteo?token=xxx
  -> AdvCriteoCatalog::index() (extends AdvGoogleCatalog)
     -> secureXml(): check XML_FEEDS.IS_ENABLED_CRITEO, optional token auth
     -> getDbData(): product_model->getCriteoRecords()
     -> parseItem(): maps to Google Shopping format with optional custom price modifier
     -> OutputGoogleCatalog XML output

Contactpigeon Feed

HTTP GET /xml/contactpigeon?token=xxx&brand=1&category=2&top=100&stock=50
  -> AdvContactpigeonXml::index() (extends AdvXml)
     -> secureXml(): check XML_FEEDS.IS_ENABLED_CONTACTPIGEON, optional token auth
     -> getDbData(): product_model->getFeedProductsForContactPigeon(brand, category, topSellers, topStock)
     -> parseItems(): for each product:
        -> If colorAsDifferentProduct enabled and multiple colors:
           -> splitProductWithColors(): creates separate XML entries per color variant
           -> Each variant gets: unique uid, color-appended name, color query param in URL, color-specific image
        -> Otherwise: parseSkroutzItem() (standard format)
     -> push_image field: resized to w360,h180 with white fill background

Architecture

src/Analytics/
  MatomoTracking.php           # Server-side Matomo tracking with bulk mode and circuit breaker

ecommercen/libraries/
  AdvDatabox.php               # Databox push client with 15 metric types and SQL queries

ecommercen/job/libraries/
  AdvReportingToDatabox.php    # Cron job wrapper for Databox push

ecommercen/feeds/controllers/
  AdvCriteoCatalog.php         # Criteo product feed (extends AdvGoogleCatalog)
  AdvContactpigeonXml.php      # Contactpigeon product feed (extends AdvXml)

ecommercen/helpers/
  tracking_helper.php          # Client-side analytics transforms (GA4, Facebook, Manago ID prefixes)

application/libraries/
  Databox.php                  # Client-overridable Databox class (extends AdvDatabox)

application/modules/job/libraries/
  ReportingToDatabox.php       # Client-overridable job class (extends AdvReportingToDatabox)

tests/Unit/Analytics/
  MatomoTrackingTest.php       # Unit tests for Matomo tracking

Class Relationships

MatomoTracking wraps MatomoTracker (matomo/matomo-php-tracker SDK). Uses CircuitBreaker for fault tolerance and LoggerInterface (PSR-3) for logging.
AdvDatabox is a standalone library with direct SQL queries and Guzzle HTTP client. Uses basic auth with push.databox.com.
AdvCriteoCatalog extends AdvGoogleCatalog (Google Shopping format) -- only overrides parseItem() and secureXml().
AdvContactpigeonXml extends AdvXml (generic feed base) -- adds color-splitting logic and push image resizing.

Data Model

Matomo

No database tables. Uses Matomo PHP SDK to send tracking events to an external Matomo instance. User identity is stitched via setUserId() with the customer ID.

Databox

Queries these tables for aggregated metrics:

Table	Metrics Derived
`shop_order`	Revenue, orders, avg order value, payment method, order method, shipping cost, transporters, stores, marketplaces, referrers, country, county
`shop_order_basket`	Quantity (items sold)
`shop_customer`	Registrations, customer type (guest vs registered)
`transporters_mui`	Transporter name lookup
`store_mui`	Store address lookup
`country` / `county`	Geographic name lookups

Criteo / Contactpigeon

Standard product model queries via product_model methods. Contactpigeon supports query parameters for brand, category, top sellers, and top stock filtering.

Configuration

Matomo (Environment)

Variable	Description
`MATOMO_LOG_THRESHOLD`	Log level threshold (default: ERROR)
`MATOMO_LOG_MAX_FILES`	Maximum log file rotation
`APP_CB_MATOMO_THRESHOLD`	Circuit breaker failure threshold (default: 3)
`APP_CB_MATOMO_COOLDOWN_SECONDS`	Initial cooldown on open (default: 30)
`APP_CB_MATOMO_MAX_COOLDOWN_SECONDS`	Maximum cooldown (default: 300)
`APP_CB_MATOMO_COOLDOWN_MULTIPLIER`	Exponential backoff multiplier (default: 2.0)
`APP_CB_MATOMO_STATE_TTL_BUFFER`	State TTL buffer (default: 300)

Matomo site config (baseUrl, siteId, token, productIdPrefix) is loaded from DI container configuration.

Databox (Registry)

Group	Key	Description
`DATABOX`	`ENABLED`	Enable/disable Databox push
`DATABOX`	`TOKEN`	Databox push API token

Criteo (Registry)

Group	Key	Description
`XML_FEEDS`	`IS_ENABLED_CRITEO`	Enable feed
`XML_FEEDS`	`IS_PROTECTED_CRITEO`	Require token auth
`XML_FEEDS`	`CRITEO_TOKEN`	Feed access token
`XML_FEEDS`	`CUSTOM_PRICE_CRITEO`	Apply custom price modifier

Contactpigeon (Registry)

Group	Key	Description
`XML_FEEDS`	`IS_ENABLED_CONTACTPIGEON`	Enable feed
`XML_FEEDS`	`IS_PROTECTED_CONTACTPIGEON`	Require token auth
`XML_FEEDS`	`CONTACTPIGEON_TOKEN`	Feed access token
`XML_FEEDS`	`CUSTOM_PRICE_CONTACTPIGEON`	Apply custom price modifier

Tracking (Registry)

Group	Key	Description
`TRACKING`	`PRODUCT_ID_PREFIX_GOOGLE`	Prefix for Google Analytics product IDs
`TRACKING`	`PRODUCT_ID_PREFIX_FACEBOOK`	Prefix for Facebook Pixel product IDs
`MATOMO`	`ENABLED`	Enable/disable Matomo dashboard widget

Client Extension Points

Matomo

The MatomoTracking class is registered in the DI container. Clients can override the container definition to inject custom configuration or disable tracking entirely.

Databox

Override application/libraries/Databox.php (extends AdvDatabox) to add custom metrics.
Override application/modules/job/libraries/ReportingToDatabox.php to modify the job execution logic.
The allData() method calls all metric pushers -- individual metrics can be overridden by overriding their sent*SQL() and prepare*Rows() method pairs.

Criteo / Contactpigeon

Override parseItem() to modify feed field mapping.
Override secureXml() to change authentication logic.
Override getDbData() to change the product query.

Tracking Helper

Client repos can provide a custom tracking_helper.php in application/helpers/ to override ID prefix functions.

Business Rules

Matomo bulk tracking: All tracking calls are queued in memory and sent in a single bulk HTTP request at the end of the page lifecycle.
Circuit breaker: Matomo tracking is protected by a circuit breaker. When Matomo is unavailable, tracking silently degrades (no impact on page rendering).
Databox rate limiting: API calls are throttled to prevent rate limiting (1-second sleep every 10 calls). Data is chunked in batches of 500 data points.
Databox time windows: Regular pushes cover 3 months; initialization (allData(true)) covers 3 years.
Order status filtering: Databox excludes orders with status CANCELED, RETURN, or PENDING from all metrics.
Criteo format: Extends Google Shopping catalog format. Only overrides pricing and authentication.
Contactpigeon color splitting: When colorAsDifferentProduct is enabled, products with multiple color variants generate separate feed entries, each with a unique ID suffix, color-specific image, and color query parameter in the URL.
Contactpigeon push images: Images are resized to 360x180 with white background fill for push notification compatibility.
Product ID prefixes: Each analytics platform uses a configurable prefix (e.g., ADV_ for Google, FB_ for Facebook) to avoid ID collisions across platforms.

AD-10 Reporting -- Admin dashboard reporting that uses some of the same analytics data
IN-01 Feed Generation -- General feed framework for XML catalog exports
CF-02 Product Detail -- Matomo ecommerce view tracking on product pages
CF-04 Search -- Matomo site search tracking
SY-01 Cron Framework -- Cron scheduling for Databox push job
SY-26 Circuit Breaker -- Matomo tracking is protected by a circuit breaker (circuit_breaker.matomo) to silently degrade when Matomo is unavailable

Analytics Integrations (Matomo, Databox, Criteo, Contactpigeon) ​

Business Overview ​

API Reference ​

Matomo Tracking API (Server-Side) ​

Databox Push API ​

Feed Endpoints ​

Tracking Helper Functions ​

Code Flow ​

Matomo Server-Side Tracking ​

Databox Hourly Push ​

Criteo Catalog Feed ​

Contactpigeon Feed ​

Architecture ​

Class Relationships ​

Data Model ​

Matomo ​

Databox ​

Criteo / Contactpigeon ​

Configuration ​

Matomo (Environment) ​

Databox (Registry) ​

Criteo (Registry) ​

Contactpigeon (Registry) ​

Tracking (Registry) ​

Client Extension Points ​

Matomo ​

Databox ​

Criteo / Contactpigeon ​

Tracking Helper ​

Business Rules ​

Related Flows ​

Analytics Integrations (Matomo, Databox, Criteo, Contactpigeon)

Business Overview

API Reference

Matomo Tracking API (Server-Side)

Databox Push API

Feed Endpoints

Tracking Helper Functions

Code Flow

Matomo Server-Side Tracking

Databox Hourly Push

Criteo Catalog Feed

Contactpigeon Feed

Architecture

Class Relationships

Data Model

Matomo

Databox

Criteo / Contactpigeon

Configuration

Matomo (Environment)

Databox (Registry)

Criteo (Registry)

Contactpigeon (Registry)

Tracking (Registry)

Client Extension Points

Matomo

Databox

Criteo / Contactpigeon

Tracking Helper

Business Rules

Related Flows