BigCommerce Integration

BigCommerce keeps category URLs short and human, which makes the mapping table unusually readable. The catch is where the snippet is allowed to live.

Prerequisites

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

BigCommerce category URLs are the category path itself: /knee-supports/, /lower-back/, and /all/ for the full catalogue. There is no /category/ prefix to remember, so the mapping table reads almost like the menu.

Nested categories inherit the parent path, so /supports/knee/ is a valid destination if that is how the catalogue is organised. Use the full path rather than the last segment.

For the fallback destination, /all/ is the right choice. It always exists, and it is a better landing place for an unmapped zone than the homepage.

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;

  // Map zone keys to BigCommerce category URL paths
  var zoneToCategory = {
    "head":           "head-care",
    "neck":           "neck-support",
    "upper-back":     "upper-back-support",
    "lower-back":     "lower-back-support",
    "left-shoulder":  "shoulder-support",
    "right-shoulder": "shoulder-support",
    "left-arm":       "arm-support",
    "right-arm":      "arm-support",
    "left-hand":      "hand-wrist-support",
    "right-hand":     "hand-wrist-support",
    "abdomen":        "abdominal-support",
    "pelvis":         "pelvic-support",
    "buttocks":       "back-support",
    "left-leg":       "leg-knee-support",
    "right-leg":      "leg-knee-support",
    "left-foot":      "foot-care",
    "right-foot":     "foot-care"
  };

  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 category = zoneToCategory[zoneId];

    if (category) {
      window.location.href = "/" + category + "/";
    } else {
      window.location.href = "/all/";
    }
  });
</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

Category renamed, mapping not updated

Problem: One zone starts landing on a 404 after a merchandising change.

Cause: BigCommerce URLs follow the category name, so renaming a category silently changes its path.

Solution:

1. Set a custom URL on any category a zone points at, so the path survives a rename.
2. Keep the mapping table in source control and review it when categories change.

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