Marketing Cloud Personalization Sitemap: Five Data Layer Gotchas

The catalog defines what Marketing Cloud Personalization knows. The sitemap.js defines what it sees. On every production engagement, the data-layer file is the source of more debugging time than every other component combined. Four reasons recur. A fifth shows up only when the implementation looks done, which is when it gets shipped.

1. SPA route changes do not look like page loads

Single-page applications navigate without a full page reload. The browser URL changes, content swaps, but no new page-load event fires. Default sitemap.js implementations that hook into page-load see one event for the entire session.

The symptom is that visitors look like they spent 40 minutes on the home page and never visited a product. Affinity learning starves. Recommendation quality stays at cold-start levels even after weeks of traffic.

Two fixes work, and exactly one of them is the right one for any given site:

• Hook the framework's router events. React Router, Vue Router, Next.js, and SvelteKit all expose route-change listeners. Fire Evergage.Sensor (or the modern MCP.beacon equivalent) on each route change with the new page type and item context.
• Listen on the History API. pushState, replaceState, and popstate cover most SPA navigation patterns even when the framework router is opaque or wrapped. More fragile than framework events, but works as a fallback.

Whichever path is chosen, the test is identical. Open the network tab, click through five pages without reloading. Five distinct beacons should fire, each with the correct page type. If only one fires on initial load, the integration is silently broken.

2. The DOM lies until async data arrives

Product pages on modern sites render the layout first, then fetch product data via XHR or GraphQL, then update the DOM. Sitemap.js typically reads from the DOM at page-load time. On async-rendered pages, that read happens before the data is there.

The result is beacons that fire with itemId: null or with placeholder values from the layout shell. The platform attributes the visit to nothing, or worse, to a phantom item that never gets cataloged.

Three patterns are reliable, in order of preference:

• Wait for an explicit ready event. Most front-end frameworks emit a custom event (product:loaded, data:ready) when async data hydrates. Hook the beacon to that event, not to DOMContentLoaded.
• Poll for the data attribute. A 100ms interval that checks document.querySelector("[data-item-id]") and fires the beacon when the value is present. Cap the polling at five seconds and log a failure if no value arrives.
• MutationObserver on the container. Set up an observer on the parent element. Fire the beacon the first time the item-id attribute mutates from empty to a real value.

Avoid setTimeout-with-arbitrary-delay. It works on a fast connection and breaks on a slow one, which means it works in dev and breaks in production.

3. Item attribution depends on which ID the DOM exposes

The catalog stores items keyed by the canonical product ID. The product detail page DOM might expose:

• data-product-id (canonical SKU, the one the catalog uses)
• data-variant-id (color or size variant, child of the SKU)
• data-listing-id (e-commerce platform's auto-generated number, not stable)
• A URL slug that is human-readable but unrelated to the SKU

Reading the wrong one means every beacon attributes to the wrong identity. Affinity profiles split across ghost variants. Recommendations target items that do not exist in the catalog.

The discipline is to confirm the DOM source matches the catalog ID column, in writing, before any traffic flows. The five-minute conversation: "what attribute does the product page expose, and is that the same field used as item ID in the catalog feed?" That conversation prevents months of bad data.

When variants exist, decide upfront whether the platform tracks at parent SKU or variant level. Both are defensible. Mixed is not. Pick one, document it, configure the catalog and the sitemap consistently.

4. Modals and quick-view break page-type assumptions

Most sitemap.js code assumes one page type per page load. On a category listing page, that is "category." On a product detail page, that is "item-detail." The platform learns from this and recommends accordingly.

Then a quick-view modal opens. The visitor is now looking at product detail content while the URL still shows the category. Default sitemaps fire nothing for the modal, or fire the wrong event, or double-fire and the platform sees two competing contexts.

The fix is explicit modal handling:

• Detect the quick-view open event in JavaScript. Most sites already have a modal:opened or quickview:show event.
• Fire a context-update beacon with itemId set to the modal's product and a hint that this is a sub-page-type rather than a navigation.
• On modal close, fire a return-to-context beacon if the visitor is still on the original category page.

Without this discipline, sites with heavy quick-view usage end up with category pages that look like nothing happened, even when visitors are deep-diving on individual products through modals.

5. Beacon timing decides what counts as a view

A view event with no timing rule fires the moment the page loads. On a product detail page, that means a 0.4-second visitor who hits back immediately gets counted as a viewer. Recommendation models trained on that data optimize for accidental clicks.

A few timing patterns work well:

• Scroll-into-view threshold. Fire the view beacon only when the product hero has been visible for a continuous window, typically 1.5 to 3 seconds. Visitors who land and bounce do not count.
• Engagement threshold. Fire when the visitor has scrolled past 50 percent of the product detail content. Pairs well with newer "qualified view" definitions analytics teams already use.
• Explicit hover for desktop, dwell for mobile. Different signals on different devices, but same principle.

Listing pages are the opposite. There, the platform wants to know what items the visitor saw without forcing each one to be hovered. The right pattern is impression beacons keyed off intersection observers, fired once per item per visit, gated on the product card being at least partially visible.

The default behavior in most starter sitemaps is to fire instantly on page load. The cost is recommendation models that overfit on noise. The fix is two hours of timing logic per page type.

A practical debugging checklist

When MCP behavior looks wrong, the sitemap is the most likely cause. The order to check:

1. Open the browser network tab and watch beacon fires across a typical session. Confirm they fire on the right pages, with the right page types, and with non-null item IDs.
2. Match the beacon itemId against the catalog. The platform's debug overlay will flag unrecognized IDs.
3. Verify SPA route changes fire beacons. Click between pages without reloads.
4. Verify async-rendered data is present before beacons fire. Slow the network in devtools to 3G to expose race conditions.
5. Test modal and quick-view flows explicitly. They almost always break first.

A clean sitemap.js is the single highest-leverage piece of an MCP implementation. Sapota's Salesforce team budgets two to three weeks for sitemap design and validation on every Personalization project, regardless of how mature the existing analytics layer looks.

---

Building or debugging an MCP sitemap? Sapota's Salesforce team handles data-layer design, beacon validation, and SPA integration on production engagements. Get in touch ->

See our full platform services for the stack we cover.