Skip to main content
This guide covers secure production setup and common embed issues.

​
Security Model

The SDK protects modal message handling by validating iframe origin before processing events. Trusted origins:
  • https://checkout.shoppex.io
  • local development origin for checkout app
Because of this, forged postMessage events from random origins are ignored.

​
CSP Setup

If you run strict CSP, allow checkout iframe + script and pass a nonce to Shoppex.init. Example policy: 
Content-Security-Policy:
  frame-src https://checkout.shoppex.io;
  script-src 'self' 'nonce-YOUR_NONCE' https://checkout.shoppex.io;
  style-src 'self' 'nonce-YOUR_NONCE';
SDK init with nonce: 
Shoppex.init({ nonce: 'YOUR_NONCE' });
Why this matters:
  • The SDK injects styles into its shadow root.
  • The nonce allows those injected styles under strict CSP.

​
Return URL Safety

Use a trusted application URL for returnUrl. 
Shoppex.open({
  items: [{ productId: 'PRODUCT_ID' }],
  returnUrl: 'https://app.example.com/checkout/success'
});
Avoid sending unvalidated user input directly as returnUrl.

​
Production Checklist

  • Use HTTPS everywhere.
  • Load script from https://checkout.shoppex.io/embed/embed.iife.js.
  • Bind success/error handlers for observability.
  • Track conversion events in your analytics after shoppex:success.
  • Validate your product and variant IDs before rendering buy buttons.
  • Test dark/light theme and mobile viewport.
  • Validate CSP in production, not only local.

​
Troubleshooting

Checklist:
  • Script is loaded.
  • Element has valid data-shoppex-product-id or data-shoppex-items.
  • items contains at least one non-empty productId.
  • No JavaScript error before click handler runs.

​
Wrong product opens

Cause:
  • Multiple items currently resolve to first valid item in modal flow.
Fix:
  • Pass one item per checkout open until multi-item modal support lands.

​
Event listeners do not fire

Checklist:
  • Listen on document, not only on button element.
  • Ensure checkout completed successfully for shoppex:success.
  • Verify browser extensions/policies are not blocking cross-origin frames.
Use low-risk defaults:
  • Avoid custom overlays with extreme z-index values.
  • Test with your cookie/privacy banners and support widgets.

​
Dynamic content buttons do not open checkout

The SDK auto-observes DOM changes, but make sure:
  • New nodes actually include data-shoppex-product-id or data-shoppex-checkout.
  • Your frontend does not stop propagation on click before SDK handler runs.

​
Debug Helpers

Simple runtime checks: 
console.log('Shoppex available:', typeof window.Shoppex !== 'undefined');

document.addEventListener('shoppex:error', (event) => {
  console.error('Embed error:', event.detail.error);
});

Embed SDK Overview

Start here for integration patterns.

Embed SDK Reference

Full API, attributes, and event details.