EC-CUBE Integration

EC-CUBE is a Symfony application underneath, so the integration is the tidiest of these: one Twig block, one query parameter.

Prerequisites

• You can edit page/template code in EC-CUBE.
• 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 EC-CUBE

EC-CUBE product listings take the category as a query parameter: /products/list?category_id=7. Nested categories use the child ID directly, not a path, which keeps the mapping short.

/products/list with no parameter lists the whole catalogue and makes a sensible fallback for unmapped zones.

Because it is a query parameter rather than a path, you can combine it with the platform’s other list parameters. ?category_id=7&orderby=2 sends a knee click to knee products sorted by price, which is occasionally exactly what you want.

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;

  // Replace the numbers with your actual EC-CUBE category IDs
  var zoneToCategoryId = {
    "head":           "10",
    "neck":           "11",
    "upper-back":     "12",
    "lower-back":     "13",
    "left-shoulder":  "14",
    "right-shoulder": "14",
    "left-arm":       "15",
    "right-arm":      "15",
    "left-hand":      "16",
    "right-hand":     "16",
    "left-leg":       "17",
    "right-leg":      "17",
    "left-foot":      "18",
    "right-foot":     "18"
  };

  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 categoryId = zoneToCategoryId[zoneId];

    if (categoryId) {
      window.location.href = "/products/list?category_id=" + categoryId;
    } else {
      window.location.href = "/products/list";
    }
  });
</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

Twig cache serving the old block

Problem: The block is saved in the admin but the storefront has not changed.

Cause: Symfony’s Twig cache still holds the compiled template.

Solution:

1. Clear the cache from the admin, or remove var/cache and let it rebuild.
2. Confirm the block is attached to the layout of the page you are testing, not only created.

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