Server-side GA4
@mercentia/analytics sends ecommerce events directly from the
gateway to GA4 via the
Measurement Protocol.
This complements (or replaces) the in-browser gtag.js tracker
and is resilient to ad-blockers, ITP, and stripped
document.referrer.
Why server-side
The browser tracker drops events when:
- The customer is on Safari with ITP 2.3+ and the script is classified as tracking.
- An ad blocker matches the gtag domain (~30% of EU traffic by 2026).
- The customer closes the tab before the page-unload beacon flushes.
Server-side events are emitted from the gateway after the business event has committed, so they’re as accurate as the order ledger.
Setup
- In GA4 Admin → Data Streams → Web, open your web stream.
- Copy the Measurement ID (starts with
G-). - Scroll to Measurement Protocol API secrets and click Create. Copy the secret.
- In Mercentia, open Settings → Analytics and paste both values. Click Save.
Mercentia verifies the credentials by sending a synthetic
debug_event via https://www.google-analytics.com/debug/mp/collect.
If the call fails, the UI surfaces the validation error.
Event coverage
The 12 GA4-recommended ecommerce events are emitted automatically:
| Event | When |
|---|---|
view_item_list |
Collection / search results render |
view_item |
PDP loads |
select_item |
PLP click that opens a PDP |
add_to_cart |
POST /api/v1/cart/add succeeds |
remove_from_cart |
POST /api/v1/cart/remove succeeds |
view_cart |
Cart page loads |
begin_checkout |
Checkout init endpoint hits |
add_shipping_info |
Shipping address committed |
add_payment_info |
PaymentIntent created |
purchase |
Order transitions to paid |
refund |
Refund webhook from Stripe / Paddle |
add_to_wishlist |
Wishlist add endpoint |
Each event carries the GA4-canonical items[] array (product
id, item_name, item_brand, price, quantity, …) plus a Mercentia
order_id parameter for joinability against your warehouse.
client_id stitching
client_id is the first-party cookie that GA uses to stitch a
user’s sessions. The gateway reads it from the request
(_ga cookie) when present and stamps it on the server-side
event so browser and server sessions merge correctly.
Debug + observability
Server-side events that fail (4xx / 5xx from GA4) write a row to
analytics_events_failed with the GA4 response body. Look at
Settings → Analytics → Recent failures to triage.