💫Variant Integration
It's as easy as walking! The Variant Integration Feature allows you to dynamically switch product variants by sending predefined trigger values to the embedded iFrame using postMessage.
Final Result 🎉

Integration Example
Step 1: Add the Mazing Script to the <head>
Element
<head>
ElementTo enable the Mazing Viewer, include the following script in the <head>
element of your HTML. This script initializes the library and prepares your website for the 3D experience.
<!-- MAZING -->
<script src="https://cdn.mazing.link/mzg-in.js" defer="defer"></script>
Note: The defer
attribute ensures the script is loaded after the HTML document is parsed, optimizing page performance.
Step 2: Add Your Custom Script at the End of the <body>
<body>
Create a new script at the end of the <body>
element. This script contains the logic to load and customize your 3D experience.
...
<!-- MAZING -->
<script>
// YOUR SCRIPT COMES HERE!
</script>
</body>
Step 3: Fill in Your Script Logic
In this step, you’ll add the main logic to initialize the Mazing Viewer. Copy and paste the following code into your script file or the <script>
element you created earlier (for non-Shopify users).
// Wait for the mazingProjectAvailable function to become available
// Ensures the header script is fully loaded
const waitForMazingFunction = new Promise((resolve) => {
const interval = 50; // Check every 50ms
const checkInterval = setInterval(() => {
if (typeof mazingProjectAvailable === 'function') {
clearInterval(checkInterval);
resolve();
}
}, interval);
});
// Main script logic
const initializeScript = async () => {
// Wait for Mazing to be ready
await waitForMazingFunction;
console.log('mazing configuration is active :)');
// TODO: Add your custom logic here
}
// Start the initialization
initializeScript();
What’s Happening?
The
waitForMazingFunction
ensures that themazingProjectAvailable
function is fully loaded before you execute your custom script.Once everything is ready, the script logs
Mazing configuration is active :)
to confirm successful initialization.
Step 4: Get SKU and Create an iFrame
Next, you’ll use mazingProjectAvailable()
to retrieve the iframeSrc
for the Mazing Viewer. This function fetches the SKU (Stock Keeping Unit) of the current product and initializes the viewer.
const initializeScript = async () => {
await waitForMazingFunction;
// Get the iFrame source by calling mazingProjectAvailable
const iframeSrc = await mazingProjectAvailable({
customerName: 'YourMazingCustomer',
getSKU: () => {
// Extract SKU from the current product URL
const url = window.location.href;
const match = url.match(/\/products\/([^?]+)/);
const currentProduct = match ? match[1] : null;
return currentProduct;
}
});
// TODO: Use iframeSrc to create and append the iFrame
}
initializeScript();
What’s Happening?
Retrieve the SKU: The
getSKU
function extracts the SKU from the product URL using a regular expression. For example, a URL likehttps://example.com/products/your-product
will returnyour-product
as the SKU.Generate the iFrame Source: The
mazingProjectAvailable
function uses the SKU to create theiframeSrc
, which is needed to display the Mazing Viewer.Use the iFrame Source: After generating the
iframeSrc
, you can use it to embed the viewer on your website.
Once you have the iframeSrc
, customize and append it to your website as needed. See the Script Integration Documentation for more details.
Step 5: Create the iFrame Using the iframeSrc
iframeSrc
Use the iframeSrc
to dynamically generate the iFrame and embed it into your website. Here's an example script that shows how you can achieve this:
const initializeScript = async () => {
await waitForMazingFunction;
// Retrieve the iframe source using mazingProjectAvailable
const iframeSrc = await mazingProjectAvailable({
customerName: 'YourMazingCustomer',
getSKU: () => {
const url = window.location.href;
const match = url.match(/\/products\/([^?]+)/);
const currentProduct = match ? match[1] : null;
return currentProduct;
}
});
let iframeElement;
// Create the iframe element
iframeElement = document.createElement('iframe');
iframeElement.style.cssText = "border: 0; height: 100%; left: 0; position: absolute; top: 0; width: 100%; background: white; display: none; padding-left: 22px;"; // max-height: 600px;
// HERE WE USE THE IFRAMESRC !
iframeElement.src = iframeSrc;
iframeElement.allow = "accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture; camera *; xr-spatial-tracking;";
iframeElement.allowFullscreen = true;
iframeElement.setAttribute('allowusermedia', '');
iframeElement.id = 'mazing-iframe';
/*
* Now you can use this iframe and add it to the desired spot. Let's say you want
* to put the iframe in a div in your shop with an id of 'gallery-div1' :
*/
// Add the iframe to the desired container
const iframeContainer = document.getElementById('gallery-div1');
iframeContainer.appendChild(iframe);
}
initializeScript();
The script dynamically creates an iframe
element, assigning it the necessary attributes and styles to embed the Mazing Viewer seamlessly into your website.
The display: none
style is applied by default to hide the iFrame, preventing any visual glitches or flickering when no product is available. This behavior ensures a smooth user experience but can be customized to fit your specific requirements.
By default, the example assumes that the iframe
will be embedded into a div
element with the ID gallery-div1
. You can replace this ID with the appropriate container ID for your setup.
Step 6: Use postMessage to Switch Between Variants
Now it’s time to use the ID/Trigger defined for each variant. This will allow you to switch between different product variations using your own custom user interface.

For example, if you have a dropdown menu for selecting variations, you can listen for a user’s selection and send a postMessage
to the Mazing Viewer. Let’s assume your dropdown menu has the ID operations-dropdown
.
Here’s how you can implement this logic:
// This is the select element from our example
const operations = document.getElementById('operations-dropdown');
// We iterate through all options and add an event listener on each option
for(let i=0; i < operations.length; i++) {
const operation = operations[i];
// This is the value of the option. This will become important later on!
const dropdownItemValue = operation.value;
operation.addEventListener('click', () => {
console.log('clicked variant', dropdownItemValue);
// Send the postMessage to change the Variant.
iframeElement.contentWindow.postMessage({
type: 'SWITCH_VARIANT',
value: {
trigger: dropdownItemValue
}
}, '*');
});
}
When an option in the dropdown is clicked, the script sends a postMessage
to the Mazing Viewer. The trigger
value in the message corresponds to the variant’s ID/Trigger, which you defined earlier during variant creation. See -> Variant Operations
For instance:
Clicking the "All-Black" option sends a trigger value of
"all-black"
.This value activates the variant with the corresponding ID/Trigger.
Once the 3D model has finished loading, an action is sent to notify you:
window.top.postMessage({
type: 'MODEL_3D_LOADED',
value: {
model: model
},
}, '*');
Here's an example of how you can check for the model loading and set up your environment:
// Listen for the MODEL_3D_LOADED event
window.addEventListener('message', (event) => {
if (event.data.type === 'MODEL_3D_LOADED') {
console.log('Model loaded');
// Enable controls or add event listeners for options
initializeColorOptions();
}
});
// Make the iFrame visible to start loading the model
const iframe = document.getElementById('model-iframe');
iframe.style.display = 'block'; // or any other logic to unhide the iFrame
Creating the Variant: This step demonstrates how to define a variant, such as "all-black," within your configuration.

Sending the PostMessage:
Send a postMessage
with the trigger value 'all-black' from your shop website to switch between product variants.

Congratulations! You've successfully integrated your first configurator into your website! 🎉
Last updated