E-commerce Integrations

Use this hub to choose your platform and implement zone-to-product navigation with the widget.

How It Works

1. Embed the widget in your store page.
2. Listen for zone-selected events.
3. Map zoneId values to your category, collection, or product-list URLs.
4. Redirect the shopper to the mapped destination.

Platform Guides

• Shopify
• WooCommerce
• Wix
• Squarespace
• BigCommerce
• PrestaShop
• Magento / Adobe Commerce
• OpenCart
• Cafe24
• EC-CUBE

Shared Implementation Checklist

1. Confirm your widget URL origin and filter by event.origin.
2. Confirm your listener checks source === 'persoscan-widget'.
3. Confirm every mapped zoneId points to a valid destination page.
4. Confirm fallback behavior for unmapped zones.
5. Confirm analytics tracking for zone-to-navigation conversions.

Common Issues

Clicking a body zone does nothing

Problem: Zone clicks do not navigate.

Cause: Origin/source checks fail, or the listener is not attached on the final rendered page.

Solution:

1. Verify the listener runs after page render.
2. Verify origin comparison uses new URL(WIDGET_URL).origin.
3. Verify event filtering checks both origin and source.

Redirect lands on a 404 page

Problem: Zone click redirects to an invalid URL.

Cause: Mapping target URL, handle, or slug does not exist.

Solution:

1. Validate each mapped destination manually.
2. Keep one fallback URL for unmapped or retired targets.

Widget shows an “Unlicensed” watermark

Problem: Watermark is visible in production.

Cause: Missing or invalid license key, or domain not allowed.

Solution:

1. Add a valid license value to iframe URL.
2. Add your domain in the billing portal allowlist.
3. Reload and verify in production origin.

Next Steps

• Quick Start
• PostMessage API
• Configuration
• Zone Reference