Developer notes

Overview · Installation · Configuration · Usage · FAQ

Add-on identity

Item	Value
Add-on id	kv_marketing_pixels_pack
Function prefix	fn_kv_marketing_pixels_pack_
Language variables	kv_marketing_pixels_pack.*
PHP namespace	Tygh\Addons\KvMarketingPixelsPack
CSS scope	.kv-mpx-debug (debug panel only)

Event model

The server collects the events of a response and the storefront script sends them to the platforms. An event is a neutral object; func.js maps it to each platform’s call:

{"e": "add_to_cart", "id": "tn3zfm.8b69d89c11f58d31", "v": 110, "c": "USD", "n": 2,
 "items": [{"id": "A0007DQ1TL", "name": "Ankle boots", "price": 55, "qty": 2, "cat": "Shoes"}]}

Key	Meaning
e	page_view, view_item, search, add_to_cart, begin_checkout, purchase, sign_up (the GA4 names Ecommerce Tracking Pro uses)
id	Event ID: <time base36>.<16 hex>; purchases order.<order_id>.<10 hex HMAC> (stable per order)
v, c	Value and currency (product and cart events, purchase)
n	Number of items
items	id (product ID by the Product ID sent as rule, with the prefix), name, price (unit price), qty, cat (main category)
q, ids	Search words and the IDs of the first 10 results (search)
oid	Order ID (purchase)

Delivery:

• Page events (page_view, view_item, search, begin_checkout, purchase) are printed into the page head as window.kvMarketingPixelsConfig.events.
• Add to cart is found by comparing the session cart at the start of the request (before_dispatch) with the cart at its end (redirect / dispatch_before_display). AJAX responses carry the events in the kv_mpx key, read on ce.ajaxdone. Actions that end in a redirect keep their events in the session (kv_mpx.queue, 1 hour, 20 events) for the next uncached page.
• Sign-up (update_profile, action add, storefront) is queued for the next page.
• Purchase on checkout.complete: INSERT IGNORE into ?:kv_mpx_orders claims the order; only the request that claims it prints the event. Orders in status F, D or I (all vendor orders of a parent order) are skipped and not claimed.

Full page cache. Tracker::isSharedPage() (fn_full_page_cache_is_current_dispatch_cacheable()) marks a response that the 4.21 full page cache may share. Such a page carries only settings and page-level events, no queued visitor events, and the script replaces the printed event IDs with its own random IDs. Consent, test mode and the debug panel are read from cookies in the browser.

Consent contract

The script loads no platform code and sends nothing until marketing consent is known (mode opt_in), in this order of sources:

1. window.kvConsent (Kavio Labs consent contract, Cookie Consent Manager): hasDecision(), has('marketing'), on('ready'|'change'), or the DOM events kv:consent-ready / kv:consent-changed (alias kv_consent_changed). When present, it is the only source.
2. The CS-Cart cookie dialog (GDPR add-on, Klaro): the klaro cookie, service kv_marketing_pixels, read on the ce.gdpr_cookie_* events.
3. kvMarketingPixels.consent(true|false) from your own banner; mirrored in the cookie kv_mpx_consent (g/d, 180 days).

The add-on registers kv_cookie_consent_mode_get_services so Cookie Consent Manager lists Advertising pixels (category marketing) and deletes the platforms’ first-party cookies (_ttp, _pin_unauth, _scid, _uetsid, _uetvid, _twpid, _rdt_uuid, li_fat_id, …) when marketing consent is withdrawn. On TikTok and Microsoft UET the script also calls ttq.revokeConsent() / uetq.push('consent', 'update', {ad_storage: 'denied'}).

JavaScript API

Member	Description
window.kvMarketingPixels.consent(granted)	Sets marketing consent (true loads the tags and sends the waiting events, false stops sending). Ignored when consent handling is off.
window.kvMarketingPixels.send(event)	Sends an event object (see the event model), e.g. {e: 'sign_up', id: 'newsletter-123'} for a custom sign-up form.
window.kvMarketingPixels.sent	Log of every call: {platform, event, name, id, value, currency, time}.
window.kvMarketingPixels.state()	granted, denied or unknown.
window.kvMarketingPixelsConfig	The page configuration (platforms, event mapping, consent mode, events).

The platform globals are the official ones (ttq, pintrk, snaptr, uetq, twq, rdt, lintrk), so your own code can send extra events after the tags loaded.

Hooks used

Type	Hook	Purpose
PHP	before_dispatch	Cart snapshot (storefront)
PHP	redirect	Add-to-cart detection before a redirect (queued)
PHP	dispatch_before_display	Page events, configuration for the page head, kv_mpx key of AJAX responses
PHP	update_profile	Sign-up
PHP	kv_cookie_consent_mode_get_services	Service + cookie list for Cookie Consent Manager
PHP	init_templater_post (only while an upgrade is pending)	Self-healing upgrade (Upgrade\Synchronizer)
Schema	gdpr/klaro_config.post.php	Advertising pixels service in the CS-Cart cookie dialog
Template (storefront)	index:head_scripts (post)	window.kvMarketingPixelsConfig
Template (storefront)	index:scripts (post), index:styles (post)	func.js (only when a platform is active), Klaro texts, debug panel styles
Template (admin)	addons:tabs_content (pre), addons:manage (post), index:styles (post)	License card, badge, styles

No core file is changed and no storefront template is overridden.

Data model

?:kv_mpx_orders: order_id (primary key), fired_at. One row per order whose purchase was reported. Dropped on uninstall.

License check

Tygh\Addons\KvMarketingPixelsPack\License\Client (generated) verifies the license against the Kavio Labs license server. Gate point: Tracker::isTrackingActive() (fn_kv_marketing_pixels_pack_is_licensed(), which reads the stored state only). Without a valid license no configuration and no event is printed, AJAX responses carry no events and no order is claimed; checkout and orders are not affected. Cron: php admin.php --dispatch=kv_marketing_pixels_pack_license.check.

Not in 1.0.0

Server-side events (TikTok Events API, Pinterest Conversions API, Snap Conversions API, Reddit Conversions API, LinkedIn Conversions API), advanced matching with hashed e-mail and phone, vendor pixels in Multi-Vendor, add-to-wishlist and add-payment-info events, Microsoft Clarity and Hotjar.

File map

Path	Purpose
app/addons/kv_marketing_pixels_pack/addon.xml	Settings (General, one tab per platform, License), table
init.php, func.php	Hooks, client configuration, Klaro service, install/uninstall, Status block, fn_kv_marketing_pixels_pack_is_licensed()
Tygh/Addons/KvMarketingPixelsPack/Config.php	Settings, platform IDs and their formats, event mapping
Tracker.php	Event collection: page events, cart diff, queue, begin_checkout, purchase claim
ContentBuilder.php	Items, values, currency conversion, product IDs
Consent.php	Consent mode and providers
License/, controllers/backend/kv_marketing_pixels_pack_license.php	License check (generated)
Upgrade/Synchronizer.php	Self-healing upgrades (generated)
schemas/gdpr/klaro_config.post.php, schemas/settings/variants.functions.post.php	Cookie dialog service, currency variants
js/addons/kv_marketing_pixels_pack/func.js	Storefront runtime: consent, platform adapters, debug panel
var/themes_repository/responsive/templates/addons/kv_marketing_pixels_pack/hooks/index/	Head configuration, script include
var/themes_repository/responsive/css/addons/kv_marketing_pixels_pack/styles.less	Debug panel
design/backend/templates/addons/kv_marketing_pixels_pack/settings/status.tpl	Status block