Viewer – Two-Way Communication via postMessage

Introduction

To enable communication between the Viewer and the host website:

  1. Open the E-commerce Settings tab in the Alter Product app.
  2. In section Integration set the domain where the iframe will be embedded (e.g. https://yourwebsite.pl or http://localhost:3000 )

You can also add metadata keys to each variant in the design which will be included in product – in the Product Configuration tab.

Messages sent by the Viewer

TypeDescription
ALTER_VIEWER_ADD_TO_CARTClicking the “Add to Cart” button
ALTER_VIEWER_DATA_RESPONSEResponse to product data request

Full Example (HTML + JS)

1<!DOCTYPE html>
2<html lang="en">
3<head>
4  <meta charset="UTF-8" />
5  <title>Alter Product Viewer Integration</title>
6</head>
7<body>
8  <h1>My Viewer Page</h1>
9
10  <button id="getDataBtn">Get Product Info</button>
11
12  <iframe
13    id="viewerWidget"
14    src="https://alterproduct.com/app/viewer/1?nav=0&add_to_cart=1"
15    title="Alter Product Viewer"
16    width="100%"
17    height="600"
18    frameborder="0"
19    allowfullscreen>
20  </iframe>
21
22  <script>
23    const iframe = document.getElementById('viewerWidget');
24    const getDataBtn = document.getElementById('getDataBtn');
25
26    // Request product data from the Viewer
27    getDataBtn.addEventListener('click', () => {
28      iframe.contentWindow.postMessage(
29        { type: 'ALTER_VIEWER_GET_PRODUCT_DATA' },
30        'https://alterproduct.com' // Ensure this matches the actual widget origin
31      );
32    });
33
34    // Handle incoming messages from the Viewer
35    window.addEventListener('message', (event) => {
36      const allowedOrigin = 'https://alterproduct.com';
37      if (event.origin !== allowedOrigin) {
38        console.warn('Rejected message from untrusted origin:', event.origin);
39        return;
40      }
41
42      const data = event.data || {};
43      const type = data.type;
44      const payload = data.payload;
45
46      if (!type || typeof type !== 'string') return;
47
48      if (type === 'ALTER_VIEWER_ADD_TO_CART') {
49        console.log('Viewer Add to Cart triggered:', payload);
50        // Handle cart integration here
51      }
52
53      if (type === 'ALTER_VIEWER_DATA_RESPONSE') {
54        console.log('Received product data from Viewer:', payload);
55        // You can use this data to update your UI or pass it to backend
56      }
57    });
58  </script>
59</body>
60</html>

Example payload

{
  "productItems": [
    {
      "model3d": {
        "id": 3
      },
      "size": {
        "id": 9,
        "name": {
          "pl": "450ml (15oz)",
          "en": "450ml (15oz)"
        },
        "measureSize": {
          "D": 8.65,
          "H": 11.95
        }
      },
      "material": {
        "id": 3,
        "name": {
          "pl": "Ceramika",
          "en": "Ceramic"
        }
      },
      "printType": {
        "id": 5,
        "name": {
          "pl": "Sublimacja",
          "en": "Sublimation"
        }
      },
      "color": {
        "id": 11,
        "name": {
          "pl": "Domyślny",
          "en": "Default"
        },
        "hex": "#FFFFFF"
      },
      "variant": {
        "id": 11,
        "productGroupId": 1,
        "productModel3dId": 3,
        "sizeId": 9,
        "materialId": 3,
        "printTypeId": 5,
        "colorId": 11,
        "metadata": null,
        "minOrderQuantity": null,
        "processingTime": null,
        "stockQuantity": null,
        "volume": null,
        "weight": null
      },
      "unitPrice": {
        "value": 0,
        "currency": "EUR"
      },
      "totalPrice": {
        "value": 0,
        "currency": "EUR"
      },
      "quantity": 1
    }
  ],
  "designName": "Mug 450ml (15oz)",
  "productGroup": {
    "id": 1,
    "name": {
      "pl": "Kubek 450ml (15oz)",
      "en": "Mug 450ml (15oz)"
    }
  },
  "totalPrice": {
    "value": 0,
    "currency": "EUR"
  },
  "userDesignId": 10
}