Embedding
Introduction
This document outlines the two primary methods for integrating our 3D configurator into your website: using an iFrame or injecting it directly via a script. Each approach has distinct advantages and challenges, which we will explore in detail to help you choose the best method for your needs.
Implementation Methods for 3D Configurator
iFrame Method
- Simplicity: Easier to implement with minimal effort.
- Isolation: Keeps the configurator separate from the host page, reducing conflicts with the site's styles and scripts.
- Limitations: No interaction with the host page and third-party plugins like analytics tools, and potential accessibility issues.
Script Injection Method
- Flexibility: Allows for deeper integration and interaction with the host page and third-party tools (e.g., Google Analytics).
- Customization: Can match the styling of the host website, including fonts.
- Challenges: Requires careful handling to avoid conflicts with existing page styles.
- Mobile View Advantage: Improves user experience on mobile by hiding the URL and navigation bars, unlike iFrames.
iFrame Mode
Key-Value Pairs in URLs
Key-value pairs are used in URLs to pass information in the following structure:
feature_id=valueCopy to clipboardErrorCopied
- Key: The name of a parameter (e.g., width, depth).
- Value: The value assigned to the parameter (e.g., 171, 62).
Multiple key-value pairs are combined in a URL using the & symbol:
https://web.iconfigure.nl?product=YOUR_PRODUCT_ID&feature_id=VALUECopy to clipboardErrorCopied
How Key-Value Pairs Work
- Purpose: Key-value pairs allow a server or application to receive and use specific data.
Example:
https://web.iconfigure.nl?width=100&height=200Copy to clipboardErrorCopied
- width=100: Specifies the width as 100 units.
- height=200: Specifies the height as 200 units.
Applications parse these pairs to adjust their behavior or display based on the provided values.
The Product ID
A Product ID is a unique identifier used to specify a particular product in a database or system. It is often included as part of a URL query string.
Example:
https://web.iconfigure.nl/?product=118987e2-f58a-4b7d-8a5b-8349f3a7cdf1Copy to clipboardErrorCopied
- Key (product): Represents the parameter related to selecting a product.
- Value (118987e2-f58a-4b7d-8a5b-8349f3a7cdf1): A unique identifier (often a UUID) for a specific product.
Why This Matters
- Customization: Key-value pairs enable customization, such as pre-configuring a product or filtering search results.
- Product Identification: The product ID ensures the correct product is loaded, crucial in systems with many similar items.
Example: Embedding in an iFrame
To embed a pre-configured product in an iFrame, you can use the following HTML:
<iframe
src="https://web.iconfigure.nl/?product=118987e2-f58a-4b7d-8a5b-8349f3a7cdf1&width=100&height=200"
></iframe>Copy to clipboardErrorCopied
- The src attribute includes the URL with key-value pairs.
- The style attribute ensures the iFrame fits within the webpage layout.
Styling the iFrame for Full Viewport
To make the iFrame cover the full width and height of the viewport minus the height of the top bar, and to ensure it is fixed in position, you can use the following CSS:
<iframe src="https://web.iconfigure.nl/?product=118987e2-f58a-4b7d-8a5b-8349f3a7cdf1" style=" position: fixed; top: 50px; /* Adjust to match the height of your top bar */ left: 0; width: 100%; height: calc(100dvh - 50px); /* Subtract the top bar height */ border: none;"> </iframe>Copy to clipboardErrorCopied
- position: fixed: Ensures the iFrame remains in place as the user scrolls.
- top: 50px: Sets the top margin to match the height of the top bar.
- width: 100%: Makes the iFrame span the full width of the viewport.
- height: calc(100dvh - 50px): Uses the calc() function to dynamically adjust the height of the iFrame, subtracting the height of the top bar.
Dynamic viewport height (dvh) on Mobile
On mobile devices, the standard 100vh unit can cause issues because it doesn’t account for the browser’s navigation bar, leading to content being cut off. To fix this, you can use a dynamic viewport height calculation
height: calc(100dvh - 50px)Copy to clipboardErrorCopied
This ensures your iFrame remains fully visible and properly positioned on all devices.
Inject mode
This guide explains how to use the inject method to integrate the 3D configurator into your website. The inject method allows for greater flexibility and interaction with the host page, while enabling customization of the configurator's behavior.
Required Scripts and Stylesheets
Include the following script and stylesheet in your HTML to load the configurator:
<script src="https://web.iconfigure.nl/inject/inject.iife.js" crossorigin="anonymous"></script> <link rel="stylesheet" media="all" href="https://web.iconfigure.nl/inject/style.css" />Copy to clipboardErrorCopied
HTML Structure
Add a div element where the configurator will be injected:
<div style=" position: sticky; height: 100dvh !important; width: 100vw !important; margin-bottom: -100vh; top: 0; pointer-events: auto; scroll-behavior: auto; " id="iConfigure"> </div>Copy to clipboardErrorCopied
id
note: id="iConfigure" is important because its used to find the div
style
- position: sticky: Ensures the configurator remains visible at the top.
- height: 100dvh: Uses dynamic viewport height to ensure proper rendering, including on mobile devices.
- width: 100vw: Sets the width to cover the entire viewport.
- top: 0: Anchors the configurator to the top of the page.
- pointer-events: auto: Allows user interactions with the configurator.
- scroll-behavior: auto: Prevents scrolling issues.
Note that the injection method of the Configurator is in the body where it's possible to be scrolled to because on mobile devices that makes possible to hide the URL bar and the notification bar from the browser
Handling Events from the Configurator
To handle messages sent from the configurator (e.g., when the user completes a configuration), add an event listener to your page:
<script> window.addEventListener("message", function (event) { if (event.origin !== "https://web.iconfigure.nl") { console.warn(`Wrong origin: '${event.origin}', not handling message.`, event); return; } const iframeThanksPageUrl = "https://www.example.nl/bedankt-voor-uw-offerte"; if (event.data.state === "finished") { window.location.href = iframeThanksPageUrl; } }); </script>Copy to clipboardErrorCopied
- event.origin: Ensures that the message originates from the trusted configurator URL.
- event.data.state: Checks for a specific state (e.g., finished) to perform an action, such as redirecting to a thank-you page.
Pre-Configuration Settings
To customize the configurator's behavior and pre-load specific settings, define a preConfig object and call the injectApp function:
<script> let preConfig = { product: "029bc7cc-e1a0-4b90-82e4-9cc1190d4643", aantal_deuren: "1_deur", type: "type_taats", hoogte_sparing: "224.7", breedte_sparing: "80", breedte_deuren_ghost: "1", hoogte_deuren_ghost: "224.7", breedte_paneel_ghost: "500", draairichting: "lbi", m2: "0", model: "rome", materiaal: "eiken", kleur: "eiken_behandeld", kleur_glas: "glas_helder", greep_taats: "brielle", maat_greep: "35cm", montage: "laten_monteren", active_step: "0", }; injectApp(preConfig); </script>
- Pre-configured parameters: These parameters customize the configurator, such as the product type, dimensions, material, and color.
- injectApp(preConfig): Initializes the configurator with the provided settings.
Final Notes
- The inject method provides seamless integration and allows you to interact dynamically with the configurator.
- Ensure that you handle messages securely and only trust messages from the expected origin.
- Use the pre-configuration object to adapt the configurator to your specific needs.
This setup ensures a smooth and customizable user experience for your 3D product configurator.