Jak osadzić 3D Viewer, Konfigurator i Personalizator za pomocą iframe + postMessage (Szybki 5-minutowy setup)

Wprowadzenie

Chcesz dodać podglądy 3D/AR i personalizację produktów w czasie rzeczywistym do swojego sklepu bez miesięcy kodowania? Możesz — i zajmie Ci to tylko kilka minut. Dzięki prostemu osadzeniu 3D Viewera, Konfigurator lub Perosonalizator za pomocą iframe i postMessage otwierasz przed klientami interaktywne doświadczenia zakupowe, które zwiększają konwersję, skracają proces zakupu i redukują zwroty.

W tym poradniku zobaczysz, jak w kilka minut wkleić gotowe fragmenty kodu, dostosować parametry URL, podłączyć koszyk przez postMessage i zadbać o bezpieczeństwo. Działa na Shopify, WooCommerce, Webflow, Wix — i każdym headless stacku.

Szybki start: lista kontrolna (5 minut)

1. Utwórz projekt w Alter Product.
2. Przejdź do zakładki Udostępnianie i ustaw widoczność na publiczną dla wybranego modułu (Viewer, Konfigurator lub Perosonalizator).
3. Skopiuj wygenerowany kod iframe.
4. Wklej go na swoją stronę i dostosuj parametry URL (np. add_to_cart=1, bcg, env).
5. Dodaj obsługę postMessage dla zdarzeń koszyka i danych produktu.
6. Dodaj swoją domenę do whitelisty w Ustawienia E-commerce → Integration, aby zapewnić bezpieczeństwo.

Wskazówka: Dynamiczne ceny działają we wszystkich planach. White-label (logo, kolory, pasek nawigacji) dostępne jest w Business, a tworzenie własnych personalizatorów w Business PRO.

Krok 1: Osadzanie przez iframe

Każdy moduł ma swój własny URL. Skopiuj go z zakładki Udostępnianie i wklej tam, gdzie potrzebujesz. Oto podstawy:

Viewer (podgląd 3D/AR)

<iframe src="https://alterproduct.com/app/viewer/40?add_to_cart=1&nav=1" width="100%" height="640"></iframe>

Konfigurator (warianty + cena na żywo)

<iframe src="https://alterproduct.com/app/configurator/41?add_to_cart=1" width="100%" height="720"></iframe>

Perosonalizator (pełna personalizacja + pliki do druku)

<iframe src="https://alterproduct.com/app/customizer/44" width="100%" height="800"></iframe>

Uwaga: nav=1 (brandowany pasek górny) dostępny jest w planach Business. Na urządzeniach mobilnych AR działa od razu w Viewerze i Konfiguratorze — bez dodatkowych aplikacji.

Krok 2: Stylizacja i parametry URL

Możesz dostosować doświadczenie użytkownika w kilka sekund, dodając parametry URL do iframe. Oto najczęściej używane:

• nav=0|1 — włącz/wyłącz pasek nawigacji (Business/PRO).
• add_to_cart=0|1 — pokaż lub ukryj przycisk „Dodaj do koszyka”.
• bcg=value — ustaw tło (gradient, motyw lub własne środowisko).
• env=1 — wybierz HDRI dla oświetlenia.
• light_intensity=0–2 — steruj intensywnością światła (domyślnie ~0.6).

Pełne tabele obsługiwanych parametrów znajdziesz w dokumentacji:

• Viewer — styling & URL parameters
• Konfigurator — styling & URL parameters

Na końcu nie zapomnij ostylować kontenera iframe w CSS (proporcje, zaokrąglenia, marginesy), aby modele 3D prezentowały się estetycznie i były spójne z wyglądem Twojej strony. Spójny styl wzmacnia branding i poprawia doświadczenie użytkownika.

Krok 3: Integracja przez postMessage (Viewer, Konfigurator, Perosonalizator)

postMessage umożliwia komunikację pomiędzy Twoją stroną a osadzonym modułem. Możesz np. pobrać aktualne dane produktu (wariant, cena, ilość) albo zareagować, gdy klient kliknie Dodaj do koszyka.

Uwaga: zawsze waliduj event.origin, aby akceptować wiadomości wyłącznie z zaufanego źródła.

Viewer — komunikacja dwukierunkowa

<iframe
  id="viewerWidget"
  src="https://alterproduct.com/app/viewer/1?add_to_cart=1&nav=1"
  title="Alter Product Viewer"
  width="100%"
  height="560"
  style="border:0;border-radius:12px;"
  loading="lazy"></iframe>

<script>
  const ALLOWED_ORIGIN = "https://alterproduct.com";
  const viewer = document.getElementById("viewerWidget");

  // Example: request a snapshot of current state
  function requestViewerData() {
    viewer.contentWindow.postMessage(
      { type: "ALTER_VIEWER_GET_PRODUCT_DATA" },
      ALLOWED_ORIGIN
    );
  }

  window.addEventListener("message", (event) => {
    if (event.origin !== ALLOWED_ORIGIN) return;
    const { type, payload } = event.data || {};

    if (type === "ALTER_VIEWER_ADD_TO_CART") {
      console.log("[Viewer] ADD_TO_CART", payload);
      // TODO: add to cart
    }
    if (type === "ALTER_VIEWER_DATA_RESPONSE") {
      console.log("[Viewer] DATA_RESPONSE", payload);
      // TODO: update price / variant UI
    }
  });
</script>

Konfigurator — komunikacja dwukierunkowa

<button id="getDataBtn">Get Configured Product</button>

<iframe
  id="configuratorWidget"
  src="https://alterproduct.com/app/configurator/1?nav=0&add_to_cart=1"
  title="Alter Product Configurator"
  width="100%"
  height="600"
  ></iframe>

<script>
  const ALLOWED_ORIGIN = "https://alterproduct.com";
  const iframe = document.getElementById("configuratorWidget");

  // Ask iframe for current product data
  document.getElementById("getDataBtn").addEventListener("click", () => {
    iframe.contentWindow.postMessage(
      { type: "ALTER_CONFIGURATOR_GET_PRODUCT_DATA" },
      ALLOWED_ORIGIN
    );
  });

  // Listen to responses and Add to Cart
  window.addEventListener("message", (event) => {
    if (event.origin !== ALLOWED_ORIGIN) return;
    const { type, payload } = event.data || {};

    if (type === "ALTER_CONFIGURATOR_ADD_TO_CART") {
      console.log("[Configurator] ADD_TO_CART", payload);
      // TODO: add item to your cart
    }
    if (type === "ALTER_CONFIGURATOR_DATA_RESPONSE") {
      console.log("[Configurator] DATA_RESPONSE", payload);
      // TODO: show summary / sync price & variant
    }
  });
</script>

Personalizator — proces order-first

W Personalizatorze kliknięcie Dodaj do koszyka tworzy zamówienie ze statusem pending (klienci nadal mogą edytować projekt przez bezpieczny link). Dane zamówienia otrzymasz w payloadzie; po płatności zmień status, aby zablokować edycję.

<iframe
  id="customizerWidget"
  src="https://alterproduct.com/app/customizer/1?add_to_cart=1"
  title="Alter Product Customizer"
  width="100%"
  height="720"
  style="border:0;border-radius:12px;"
  loading="lazy"></iframe>

<script>
  const ALLOWED_ORIGIN = "https://alterproduct.com";

  window.addEventListener("message", (event) => {
    if (event.origin !== ALLOWED_ORIGIN) return;
    const { type, payload } = event.data || {};

    if (type === "ALTER_CUSTOMIZER_ADD_TO_CART") {
      console.log("[Customizer] ADD_TO_CART", payload);
      // Tip: payload includes the created "pending" order
      // 1) store orderId  2) redirect to checkout
      // (Optional) use API to fetch/update order later
    }
  });
</script>

Krok 4: Obsługa koszyka

• Viewer/Konfigurator: ALTER_*_ADD_TO_CART wysyła dane produktu, gdy użytkownik kliknie przycisk. Wystarczy dodać je do koszyka.
• Personalizator: ALTER_CUSTOMIZER_ADD_TO_CART uruchamia się po zapisaniu zamówienia ze statusem pending. To moment, by:
  • zapisać ID zamówienia,
  • przekierować klienta do checkoutu,
  • (opcjonalnie) pobrać szczegóły zamówienia przez API i zablokować edycję po zmianie statusu.

Krok 5: Bezpieczeństwo i zgodność

• Dodaj swoją domenę do whitelisty w E-commerce Settings → Integration.
• Zawsze filtruj event.origin (nigdy nie używaj * w produkcji).
• Opcje white-label (logo, kolory, pasek nawigacji) dostępne są w planach Business.

Krok 6: Testowanie i debugowanie

• Otwórz DevTools → Console, aby monitorować logi postMessage.
• Przetestuj zmiany wariantów (Konfigurator) i obsługę koszyka.
• Na telefonie sprawdź AR w Viewerze.
• Jeśli nic się nie wyświetla — sprawdź widoczność projektu i whitelistę domeny.

Opcjonalnie: Presonalizator API

Dla bardziej zaawansowanych procesów połącz Presonalizator z API Alter Product. Typowe przypadki użycia:

• pobranie zamówienia po ID,
• aktualizacja statusu po płatności,
• aktualizacja ilości,
• czyszczenie porzuconych zamówień.

Dzięki temu proces staje się płynny: projekt → koszyk → płatność → produkcja z plikami gotowymi do druku.

Najczęstsze błędy (warto unikać)

• Brak widoczności publicznej — iframe nic nie wyświetla.
• Brak filtra event.origin — ryzyko bezpieczeństwa.
• Domena nie dodana do whitelisty — komunikacja nie działa.
• Zbyt mały iframe — ciasny widok 3D (ustaw większą wysokość, dodaj zaokrąglenia).
• Brak parametru add_to_cart=1 — przycisk nie pojawia się.

FAQ

Czy mogę osadzić na dowolnym CMS/stronie?

Tak — to zwykły iframe, kompatybilny z każdym CMS lub własnym projektem.

Czy ceny w czasie rzeczywistym są dostępne w każdym planie?

Tak — aktualizują się natychmiast w ramach wszystkich planów.

Czy potrzebuję dewelopera?

Nie — w przypadku podstawowego osadzania. Do integracji z koszykiem przez postMessage lub API wystarczy low-code.

Czy Personalizator generuje pliki gotowe do druku?

Tak — eksport plików do druku dostępny jest od planu Personal.

Czy mogę używać własnego logo i kolorów?

Tak — opcje white-label dostępne są od planu Business i wyżej.