cwax / banner
ConversionWax banner widget and queued Last Mile server-event adapter for Magento 2
Requires
- php: ^8.1
- ext-curl: *
- ext-json: *
- magento/framework: >=103.0.6 <103.0.10
- magento/framework-message-queue: ^100.4
- magento/module-backend: ^102.0
- magento/module-catalog: ^104.0
- magento/module-checkout: ^100.4
- magento/module-config: ^101.2
- magento/module-cookie: ^100.4
- magento/module-csp: ^100.4
- magento/module-customer: ^103.0
- magento/module-message-queue: ^100.4
- magento/module-mysql-mq: ^100.4
- magento/module-quote: ^101.2
- magento/module-sales: ^103.0
- magento/module-store: ^101.1
- magento/module-widget: ^101.2
- psr/log: ^2.0 || ^3.0
Requires (Dev)
- phpunit/phpunit: ^9.5 || ^10.5
Suggests
None
Provides
None
Conflicts
- magento/product-community-edition: >=2.4.10
- magento/product-enterprise-edition: >=2.4.10
Replaces
None
- dev-main
- 0.5.5
- 0.5.4
- 0.5.3
- 0.5.2
- 0.5.1
- 0.5.0
- 0.4.1
- 0.4.0
- 0.3.2
- 0.3.1
- 0.3.0
- 0.1.1
- dev-feature/cwtasks-100-guest-identify
- dev-feature/cwtasks-159-refund-cancel
- dev-fix/lastmile-identify-once
- dev-fix/lastmile-checkout-start-per-quote
- dev-fix/lastmile-queue-amounts
- dev-feat/lastmile-purchase-amounts
- dev-docs/integration-id-location
- dev-feat/lastmile-lmjs-views
- dev-feat/lastmile-browser-view-beacon
- dev-fix/lastmile-public-product-path
- dev-feat/lastmile-single-endpoint
- dev-fix/lastmile-esi-page-view
- dev-staging
- dev-fix/page-view-html-detection
- dev-feat/lastmile-m1-attribution
- dev-feat/body-text-replace
This package is auto-updated.
Last update: 2026-11-19 08:13:38 UTC
README
Magento 2 module Cwax_Banner provides the existing ConversionWax banner widget and the native
Last Mile server-event integration.
Last Mile architecture
Page and product views come from the Last Mile browser snippet (lm.js), which the module loads on
the storefront (see "Views come from lm.js" below). Cart, checkout, login and order events stay on
the server: storefront observers only build a small event envelope and publish it to Magento's
conversionwax.lastmile.events queue. They never call ConversionWax over HTTP. The queue consumer
performs authenticated delivery, so a slow or unavailable collector is outside page rendering,
cart, login, and checkout requests.
This module declares its queues, publisher, and consumers explicitly on Magento's database queue
(connection="db" in etc/queue_topology.xml, etc/queue_publisher.xml, and
etc/queue_consumer.xml). It does not use RabbitMQ or ActiveMQ Artemis and does not auto-detect
one; the database transport is every Magento 2 install's built-in option and needs no broker.
Moving to an AMQP broker would require changing this module's queue XML and adding an AMQP package
dependency, neither of which this release does.
Both the conversionwax.lastmile.events queue and the conversionwax.lastmile.failed queue are
processed only when Magento's consumers cron group is running (see "Run the consumer" below).
Publishing an event only writes a row to queue_message; nothing else moves that row until a
consumer process reads it, so a stopped or excluded consumers cron group means events queue up
and never ship, even though enqueuing keeps succeeding silently on the storefront.
Transient delivery failures retry eight times with consumer-side backoff. Permanent failures and
exhausted retries move to the conversionwax.lastmile.failed queue, where a dedicated consumer
logs the failure metadata (event ID, attempt count, reason, failure time) at error level and lets
the message complete. No event payload, PII, or connection token is ever written to Magento logs,
and none is retained once that log line is written: the failed queue is a drain point for cleanup,
not a replay buffer.
Events
| Source | Last Mile event | Key data |
|---|---|---|
lm.js in the browser, every page |
page_view |
path, referrer, device (snippet provenance) |
lm.js on a product page |
product_view |
SKU from cw.push(['context', ...]) |
sales_quote_product_add_after |
add_to_cart |
SKU, including REST and GraphQL quote mutation |
| Checkout controller predispatch | checkout_start |
path |
checkout_submit_all_after |
purchase |
increment ID, grand total, currency, customer, first SKU |
customer_login |
identify |
customer ID, SHA-256 email hash |
customer_register_success |
identify |
customer ID, SHA-256 email hash |
Raw email addresses and visitor IP addresses are not sent by Magento.
Views come from lm.js
A page served from Magento's built-in full-page cache, Varnish, Fastly, Cloudflare or another CDN
never runs the product controller, and a CDN hit never reaches PHP at all, so a server observer
cannot see those views. The module therefore adds the Last Mile browser snippet (lm.js) to every
storefront page, on Luma and Hyva themes alike, and lm.js sends page_view and product_view
straight to the ConversionWax collector. A page view costs no request to Magento PHP: the inline
script that loads it is the same for every visitor, so it is safe in any HTML cache.
The module renders one inline script in the page head and no static lm.js tag. The script
queues on the array form of window.cw, which lm.js drains when it loads and then replaces with
its live API, and then injects the tag itself (appended to document.head):
<script async src="https://assets.conversionwax.com/lastmile/v1/lm.js" data-cwax-site-id="WEBSITE_ID" data-cwax-integration-id="INTEGRATION_ID" data-cwax-gpc="honor"></script>
- On a product page it first queues
['context', { productId: '<SKU>', pageType: 'product', platform: 'magento' }]. The SKU is the sameproductIdthe server commerce events use. The product page also keeps<meta name="cwax-product" content="<SKU>">for any other front end. - Magento Cookie Restriction Mode off: the tag is injected at once and
lm.jsapplies the install's own consent mode. - Restriction on and cookies already allowed (
user_allowed_save_cookie): it queues['consent', true]and injects the tag at once. - Restriction on and not allowed yet: nothing more.
lm.jsis not loaded, so it sets no cookie and calls no collector, whatever the install's consent mode. When the visitor clicks Allow (Hyva'suser-allowed-save-cookiewindow event, Luma'suser:allowed:save:cookiejQuery event) it queues['consent', true]and injects the tag, once, without a page load.
lm.js finds the injected tag through document.currentScript (or script[data-cwax-site-id]).
The collector serves Magento installs a config with serverCommerce: true and no commerce
patterns, so lm.js sends views, identify and track only. Cart, checkout, login and order
events stay server events, whatever caches the HTML. A visitor whose browser blocks lm.js (or
has JavaScript off) sends no views; there is no server fallback for views. Browser prefetches and
prerenders run no snippet code until the page is shown, and server events skip prefetch and
prerender requests (Sec-Purpose, Purpose, X-Purpose, X-Moz).
The Staging environment loads the staging build
(https://dev.assets.conversionwax.com/lastmile/v1/lm.js), which reports to the staging collector.
lm.js does not start on localhost, *.localhost or *.local hosts.
Visitor identity
lm.js owns visitor identity on the storefront. It writes the first-party cookies _cwid (visitor
UUID, 400 days), _cws (session, URI-encoded JSON with the session id sid) and _cwvs (the
collector-signed visitor summary), as described in the Last Mile cookie contract (C1). It applies the
install's consent mode (wait_for_consent or capture_immediately) itself, and deletes the three
cookies when consent is withdrawn.
Server commerce events read _cwid and _cws.sid, so server and browser events join on the same
visitor and session. They take the session count and has-purchased flag from the _cwvs claims.
Magento writes cookies only on responses that are never cacheable (an add to cart, login,
registration or order POST, a REST order call, the checkout page), never on a cacheable page:
- With storage consent and no
_cwid(becauselm.jsis blocked, or another front end runs it), it mints_cwidand a session. Its own_cwscarries an extra"mg": 1key; Magento keeps that session alive for 30 minutes of inactivity and never rewrites a sessionlm.jsstarted. - It sends the existing
_cwidagain withSet-Cookie(same value, Max-Age 400 days,Path=/,SameSite=Lax,Secure, notHttpOnly). Safari limits a cookie written by script to 7 days, or 24 hours after a tracked link, but not one set by an HTTP response.
The module has no private-content section, no _cwms cookie and no visitor-sync script any more.
Install or upgrade
Install this package in app/code/Cwax/Banner or through Composer, then run:
bin/magento module:enable Cwax_Banner bin/magento setup:upgrade bin/magento cache:flush
The package requires PHP 8.1 or later and Magento 2.4.
Connect a site
- In ConversionWax, open the website's Last Mile settings and add a Magento install under Integrations.
- The install's Connect Magento step lists every setting under the name Magento Admin uses: ConversionWax Website ID, Integration ID and Connection Token. Generate the token there and copy it immediately (it is shown once).
- In Magento Admin, open Stores > Configuration > ConversionWax > Last Mile.
- Set Enabled to Yes and enter the ConversionWax Website ID, Integration ID and Connection Token.
- Leave Environment on Production. Choose Staging only to test against the ConversionWax staging service.
- Leave Load Last Mile on Magento storefront on Yes, unless another front end already loads its
own
lm.jsfor this website. Flush the cache.
Settings (all can be set per store view):
- ConversionWax Website ID. The
data-cwax-site-idof the tag and thestoreIdof every server event. - Integration ID. The install's id, shown on its Connect Magento step in ConversionWax. It must be a UUID (checked at save
time). While it is empty, Magento adds no
lm.jstag, so no views are tracked; server commerce events do not need it. - Connection Token. Authenticates server events and the consent mode lookup. Stored encrypted.
- Environment. Production or Staging. Each maps to a fixed collector host and
lm.jsURL in the module; no URL is a setting. - Load Last Mile on Magento storefront (default Yes). One switch for Luma and Hyva. No means
another front end (for example a headless storefront) runs its own
lm.js: the module adds no tag and no browser script, and keeps sending server commerce events.
The token is shown once by ConversionWax, stored only as a SHA-256 digest centrally, and stored by Magento using its encrypted configuration backend. Configure values per store view when different Magento storefronts map to different ConversionWax websites.
Consent
In the browser, lm.js decides. Its window.cw.consentState() returns 'granted', 'denied' or
'pending' (pending under wait_for_consent before any decision), and window dispatches
cw:consent with { detail: { state } } on every change; granted is dispatched only once the
cookies exist. Before lm.js has loaded (or, under restriction, before Allow), window.cw is the
plain array queue and has no consentState; readers fall back to cookie presence. The ConversionWax banner embed reads these.
A store using a third-party CMP (OneTrust, Cookiebot, etc.) under wait_for_consent must wire that
CMP to call cw.consent(true) (and cw.consent(false) on decline), or push
['consent', true|false] onto window.cw before lm.js loads. The module only forwards Magento's
own cookie notice. A CMP that never calls cw.consent() leaves every visitor pending: no views,
no _cws, and no server events (see below).
With Magento Cookie Restriction Mode on, lm.js is only loaded once the visitor has allowed
cookies (see "Views come from lm.js"), so under either consent mode nothing runs in the browser
before that decision. A visitor who never clicks Allow is not tracked at all.
On the server, a composite of small resolvers (Cwax\Banner\Api\ConsentResolverInterface, wired in
etc/di.xml) decides whether a server commerce event may be sent. Each resolver either abstains,
grants, or denies two named signals, storage (may _cwid/_cws be read or minted at all) and
measurement (may an event be published to the queue). A signal is only ever true in the final
decision when at least one resolver granted it and no resolver denied it - any single denial vetoes
that signal for the whole request, no matter how many resolvers granted it.
Resolvers included in this module:
- Global Privacy Control. A
Sec-GPC: 1request header denies both signals unconditionally. Its absence proves nothing and is not treated as consent. The tag setsdata-cwax-gpc="honor", solm.jsrefuses under GPC too. - Magento Cookie Restriction Mode. Denies both signals only when restriction mode is enabled and the visitor has not accepted. It never affirmatively grants on its own; it is a veto, not a primary gate.
- Consent mode. Reads the store's
consentMode(capture_immediatelyorwait_for_consent) from the ConversionWax collector (GET /v1/integrations/configon the selected environment's host, authenticated with the connection token asAuthorization: Bearer), cached locally for 5 minutes on success and 30 seconds when unresolved. Undercapture_immediatelyit grants both signals, matchinglm.js. Underwait_for_consentit abstains and lets the resolver below decide. If the config cannot be resolved at all (network failure, unknown or inactive token, website switched off), it denies both signals: there is no fallback policy. - Browser snippet identity. Under a confirmed
wait_for_consentmode only, this resolver readslm.js's session cookie (_cws, not_cwid/_cwvs, which persist 400 days and only prove consent was granted at some point, not that it applies now). Anlm.jssession (a JSON object with asidand nomgkey) meanscw.consent(true)ran this browser session; anything else is treated as an explicit denial. A session Magento minted is never evidence of consent.
Under wait_for_consent a visitor without lm.js consent sends no server events. No cookie is
minted and no event is queued until lm.js has written _cws after cw.consent(true). This
mirrors lm.js's own behavior, and nothing in this module buffers events across requests to work
around it.
A third party (or a future ConversionWax module) adds its own resolver purely by declaring, in its
own di.xml, the same Cwax\Banner\Model\Consent\CompositeConsentResolver array-argument node with
one additional <item> - no edit to this module, no plugin, no preference override.
There is no setting to disable consent checking entirely.
Run the consumer
For a direct test:
bin/magento queue:consumers:start conversionwax.lastmile.events --max-messages=100 bin/magento queue:consumers:start conversionwax.lastmile.failed --max-messages=100
In production, supervise both consumers or add them to Magento's cron consumers runner. For
example, the cron_consumers_runner section of app/etc/env.php can include:
'cron_consumers_runner' => [ 'cron_run' => true, 'max_messages' => 100, 'consumers' => [ 'conversionwax.lastmile.events', 'conversionwax.lastmile.failed', ], ],
This only takes effect while Magento's own cron scheduler is installed and running
(bin/magento cron:install) and the consumers cron group is not excluded from that run. If
neither an external process supervisor nor Magento cron is actually executing the consumers
group, messages accumulate in queue_message and nothing is ever delivered, even though the
storefront keeps enqueuing successfully.
Monitor the conversionwax.lastmile.events backlog for delivery health. The
conversionwax.lastmile.failed queue is drained automatically: its consumer logs failure metadata
for investigation and completes the message so Magento's queue cleanup cron can purge the row.
There is no replay from this queue; use the logged event ID, attempt count, and reason to diagnose
and correct the underlying configuration or collector problem, then let the storefront's normal
event flow produce a fresh event.
Banner widget
The original widget remains available. It accepts a banner_div value and loads
https://assets.conversionwax.com/dist/app.js on storefront pages. The CSP whitelist permits
ConversionWax script, style, image, and connection hosts (*.conversionwax.com), which also covers
lm.js and the collector it reports to.