Shopify Integration

This guide covers the current Shopify integration path for PersoScan. Use the Shopify app and theme app extension as the primary setup, and only use the iframe listener approach if you are intentionally building a manual custom theme implementation.

Recommended Setup

Use the dedicated Shopify app when you want the supported PersoScan workflow in Shopify admin.

What The Shopify App Handles

• Online Store theme app extension setup
• Storefront widget loading through the Shopify app proxy
• Navigation mappings managed inside the embedded PersoScan admin
• Grouped zone navigation on the free tier
• Detailed zone navigation on Pro
• Storefront settings such as height, theme, language, body model, colors, auto-rotate, and camera behavior

Prerequisites

• You have Shopify Online Store enabled.
• You can preview or publish theme changes.
• You have collections or pages ready for the destinations you want to map.

1. Install The Shopify App

1. Install PersoScan from Shopify admin.
2. Open the embedded PersoScan admin after the install redirect completes.
3. Confirm the app shows your shop connection, billing status, and theme block status.

2. Add The Theme App Block

1. Click Open theme editor inside the PersoScan admin.
2. Choose the template or section where the body map should appear.
3. Add the PersoScan widget app block.
4. Save the theme.
5. Preview the storefront and confirm the widget loads successfully.

3. Configure Storefront Behavior

Set the widget options directly from the theme block settings in Shopify:

• Widget height
• Theme
• Language
• Default body model
• Zone detail level
• Auto rotate
• Colors
• Transparent background
• Camera and interaction settings

Grouped zone mode works on every plan. Detailed zone mode is available on Pro, while free stores still render grouped zones at runtime.

4. Configure Navigation Mappings

1. Return to the PersoScan admin.
2. Open the navigation mappings section.
3. Set destinations for grouped regions, and detailed regions if your store is on Pro.
4. Save the configuration.
5. Refresh the storefront preview and test body-area clicks.

Use collections when possible so merchants can manage landing pages through Shopify without changing the integration.

5. Validate End-To-End

1. Open the storefront preview.
2. Click several mapped body regions.
3. Confirm each selection opens the expected collection or page.
4. Confirm unmapped regions follow your fallback behavior.
5. Publish the theme changes after the preview is correct.

Manual Fallback: iframe Embed In A Custom Theme

Use this approach only if you are intentionally bypassing the Shopify app and managing navigation with your own theme code.

<!-- Manual Shopify fallback: embed the widget in a custom theme section or custom liquid block.
     Use the Shopify app and theme app extension when possible. This snippet is for stores that intentionally bypass the app. 
     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>
  // IMPORTANT: origin is scheme + host only, no trailing slash or path
  var WIDGET_ORIGIN = new URL("https://widget.persoscan.com").origin;

  // Prevent duplicate listeners if the section re-renders
  if (!window.__persoscanListenerInstalled) {
    window.__persoscanListenerInstalled = true;

    // Map zone keys to your Shopify collection handles
    // Remove zones you don't sell for; update handles to match yours
    var zoneToCollection = {
      "head":           "head-care",
      "neck":           "neck-support",
      "chest":          "chest-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;

      var msg = event.data;
      if (!msg || msg.source !== "persoscan-widget" || msg.type !== "zone-selected") return;

      // Support multiple payload shapes
      var data = msg.data;
      var zoneKey =
        (typeof data === "string" ? data : "") ||
        (data && (data.zoneKey || data.key || data.zoneId || data.id || data.slug)) ||
        "";

      zoneKey = String(zoneKey).trim().toLowerCase().split("_").join("-");

      var collection = zoneToCollection[zoneKey];
      window.location.assign(collection ? "/collections/" + collection : "/collections/all");
    });
  }
</script>

Common Mistakes

Theme block is installed but not visible

Problem: The widget does not appear on the storefront after app install.

Cause: The app is installed, but the PersoScan widget block has not been added to the active template or section.

Solution:

1. Open Theme Editor from the PersoScan admin.
2. Add the app block to the intended template or section.
3. Save the theme and preview again.

Zone clicks do not navigate where you expect

Problem: The widget loads, but shoppers are not sent to the expected collection or page.

Cause: Navigation mappings are incomplete, outdated, or saved for the wrong plan detail level.

Solution:

1. Re-open the navigation mappings in PersoScan admin.
2. Confirm the grouped mappings are correct for the free tier.
3. If you use Pro, confirm the detailed mappings are also configured.
4. Save and retest on the storefront preview.

Manual iframe fallback does not redirect

Problem: The iframe loads, but clicks produce no redirects in the manual fallback implementation.

Cause: The event listener is missing, origin filtering is wrong, or the zone mapping keys do not match runtime zone IDs.

Solution:

1. Derive the widget origin with new URL(WIDGET_URL).origin.
2. Check both event.origin and source === 'persoscan-widget'.
3. Use exact grouped zoneId values from Zone Reference.
4. Keep zone keys lowercase with hyphen separators.

Next Steps

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