Magento / Adobe Commerce Integration

Magento gives you the same category two different ways, and choosing the wrong one costs every shopper a redirect.

Prerequisites

• You can edit page/template code in Magento / Adobe Commerce.
• You have category, tag, or collection pages ready for target redirects.
• You can test in a published or preview storefront.

Where a zone click should land in Magento

Every Magento category is reachable by its internal route, /catalog/category/view/id/12, and by its URL key, usually /knee-supports.html. The second is what your storefront actually serves, and the first is what silently redirects to it.

Use the URL key in the mapping. The internal route works, but it costs a redirect on every single zone click, and redirects are exactly the kind of thing that turns a fast interaction into a slow one.

Layered navigation is the other option: /supports.html?body_area=knee, using a filterable attribute. Worth the setup when one product belongs to several body areas, since an attribute handles that and a category does not.

1. Prepare Zone Mapping

1. Start with grouped zone IDs (head, neck, lower-back, and so on).
2. Map each zone key to one destination URL or slug.
3. Define a fallback destination for unmapped zones.

2. Embed And Listen

Add this code and update mapping values for your store:

<!-- Wrap the iframe in a div to control its dimensions.
     To fill an entire section, set both the div and iframe height to 100% instead. -->
<div style="height:650px;width:100%;">
<iframe
  id="persoscan-widget"
  src="https://widget.persoscan.com?license=your-license-key"
  style="width:100%;height:650px;border:none;border-radius:8px;color-scheme:light dark;"
  allow="fullscreen"
  title="PersoScan"
></iframe>
</div>

<script>
  var WIDGET_ORIGIN = new URL("https://widget.persoscan.com").origin;

  var zoneToCategory = {
    "head":           "head-care.html",
    "neck":           "neck-support.html",
    "upper-back":     "upper-back-support.html",
    "lower-back":     "lower-back-support.html",
    "left-shoulder":  "shoulder-support.html",
    "right-shoulder": "shoulder-support.html",
    "left-arm":       "arm-support.html",
    "right-arm":      "arm-support.html",
    "left-hand":      "hand-wrist-support.html",
    "right-hand":     "hand-wrist-support.html",
    "left-leg":       "leg-knee-support.html",
    "right-leg":      "leg-knee-support.html",
    "left-foot":      "foot-care.html",
    "right-foot":     "foot-care.html"
  };

  window.addEventListener("message", function(event) {
    if (event.origin !== WIDGET_ORIGIN) return;
    if (!event.data || event.data.source !== "persoscan-widget") return;
    if (event.data.type !== "zone-selected") return;

    var zoneId = event.data.data.zoneId;
    var categoryPath = zoneToCategory[zoneId];

    if (categoryPath) {
      window.location.href = "/" + categoryPath;
    } else {
      window.location.href = "/catalog/category/view/";
    }
  });
</script>

3. Validate End-To-End

1. Open the integration page.
2. Click at least five mapped zones.
3. Confirm each click redirects to the expected destination.
4. Confirm unmapped zones use fallback destination.

Common Mistakes

Full page cache serves a stale block

Problem: The widget or the listener does not appear on the storefront, even though the CMS block is saved.

Cause: Magento’s full page cache is serving the version from before the edit.

Solution:

1. Flush the Magento cache after editing the block.
2. In developer mode, confirm the block renders before blaming the postMessage wiring.

Origin mismatch blocks events

Problem: Clicks produce no redirects.

Cause: Event origin check does not match actual widget origin.

Solution:

1. Derive origin from widget URL (new URL(WIDGET_URL).origin).
2. Compare against event.origin.
3. Keep strict source check (persoscan-widget).

Zone mapping keys do not match runtime keys

Problem: Some body parts never redirect.

Cause: Mapping object uses wrong key format.

Solution:

1. Use exact zoneId values from Zone Reference.
2. Keep keys lowercase with hyphen separators.

Next Steps

• Integrations Overview
• PostMessage API
• Zone Reference
• Quick Start