3D product configurator - Mouthguards

https://hundredjack.bubbleapps.io/version-test/mouthguardhundredjack.bubbleapps.io

This eCommerce platform features an advanced 3D product configurator that allows customers to design their own custom mouthguards.

Mouthguards are protective devices worn over teeth to safeguard against injury, commonly used in contact sports such as martial arts, hockey, and for children engaging in physical activities.

This configurator offers users the ability to choose from three types of mouthguards, customize the color, uploading their logo and preview their design in real-time through an interactive 3D model.

The product configurator page in the WEB version

Mouthguard Types

1. Elite

   • Target Audience: Martial artists

   • Features: Soft insert for enhanced shock absorption, providing superior comfort and protection.

2. Professional

   • Target Audience: Stick athletes (e.g., hockey, lacrosse)

   • Features: Hard front tooth protection insert for additional defense against high-impact collisions.

3. Junior

   • Target Audience: Kids and young athletes

   • Features: Sized appropriately for smaller mouths, ensuring both safety and comfort.

Customization Options

• Colors: Customers can select from 18 different colors to personalize their mouthguard. The 3D model updates instantly to reflect the chosen color.

• Logo: Customers can upload their design as SVG files, move and resize the logo exactly how and where they want it, and preview it in the 3D model.

The product configurator in the WEB version. The customer can select one of 18 available colors.

The customer can upload a STL file and visualize it on the 3d viewer.

Integration Details

The configurator is integrated into the eCommerce site using a JavaScript SDK. Since the JavaScript must be included before the closing </body> tag, adding the script to the SEO/metatags advanced settings in Bubble.io was not the right choice. Instead, we used the LOADERRKW plugin to load the JavaScript as a single external file that will be loaded as a URL. Here's a step-by-step breakdown of how it works:

Loading the 3D Viewer

The first step is to load the 3D viewer from an externally hosted file using an async script. This ensures that the rest of the page remains interactive while the viewer is loading.

var script = document.createElement('script');
script.src = 'https://public.apviz.io/showcases/U0hPVzpPajZQS1pXaktR/releases/UkVMUzpjSXNSZjZUQ2c4/main.js';
script.integrity = 'sha384-TF8sIouPi5c3xnd3Q9TdRWuNlAs9XXKh61rx+BpVGECQKHWJJCyA2CJPCJ3qM1kj';
script.defer = true;
script.crossOrigin = 'anonymous';
script.setAttribute('data-apviz-callback', 'apvizShowcaseReady');
document.body.appendChild(script);

Initializing the Configurator

Once the 3D viewer is loaded, it is initialized and bound to a specific HTML div element with the ID "apviz-3d-viewer". This setup is essential for rendering the 3D model within the desired area of the web page.

async function apvizShowcaseReady(showcase) {
    const url = window.location.href;
    if (url.includes("mouthguard") || url.includes("letsee_3")) {
      // Initialize a 3D viewer and bind it to the div.
      const viewer = await showcase.createViewer({
        divId: "apviz-3d-viewer"
      });

Setting Initial Configuration

During initialization, the configurator is set up with default values. In this case, the mouthguard type is set to "Elite", the color to "Black", and the design to "Custom". These initial settings ensure that the user sees a fully configured product from the start.

      // This will start displaying 3D.
        await viewer.update({
          fields : {
            "01_JuniorElite_Color" : "Black",
            "01_Size" : "Elite",
            "Faccia" : "Design"
          }
        });

Interactive Menu for Customization

The menu where users can select their preferred options is initialized. Each select element in the menu is linked to the 3D viewer. When a user changes a selection, the corresponding field in the 3D model is updated in real-time.

      // Menu initialization.
      document.querySelectorAll("#my-menu select").forEach((select) =>
        select.addEventListener("change", () =>
          viewer.update({
            fields: {
              // After initialization, fields can be updated separately.
              [select.id]: select.value
            }
          })
        )
      );

The basic overview of the 3d configurator tool. The menu is only made of dropdowns.

Bubble.io integration with Custom Menu

This SDK awaits the user selection of the different mouthguard type and color through a dropdown for the type and a dropdown for the color. To maintain a minimalistic approach for the configurator and ensure a clean and beautiful design, I added custom JavaScript scripts that enable the use of other tools like buttons instead of dropdowns. Here’s how it works:

• Create Dummy Dropdowns: Dummy dropdowns with the IDs of each field are created and kept hidden. The initial script searches for these dropdowns.

• Custom Menu Interaction: A script awaits the user click on the custom menu and then changes the hidden dropdown value. This change is detected by the 3D configurator, and the value is displayed on the 3D viewer.

// Select the <select> element by its ID and set it to...
const selectElement = document.getElementById('01_JuniorElite_Color');
selectElement.value = '___';

const event = new Event('change');
selectElement.dispatchEvent(event);

// Console
console.log('Option "___" selected and clicked');

The script is added as action that executes on the user's click

Logo Upload and Customization

Customers can personalize their mouthguards further by uploading their own logo design as an SVG file. The script targets a specific marking zone, which is a supplemental 3D model acting as the area where the user will add their design. The configurator allows users to move and resize the logo to their liking, providing a preview of the final product in the 3D model.

Since the user should have the possibility to add a custom image as an STL and move and resize it exactly where they want the logo to be on the mouthguard, I had to rethink the method to make this work. The original SDK does not allow resizing and moving the imported image.

The original script searches for an input with a specific ID and waits for the user upload. When the upload is completed, the image is displayed on the 3D Viewer. In this case, I wanted to use our own input element to limit the user upload (only allowing STL files).

First, this script is integrated into the current file loaded before the closing </body> tag:

javascriptCopy code// File input event handler.
document.querySelector("#my-image-input").addEventListener("change", (e) => {
  viewer.update({
    markingZones: {
      // Targets a specific marking zone via its key.
      "design": {
        image: {
          color: { source: e.target.files[0] }
        }
      }
    }
  });
});

The red 3D model represents the marking zone

Then, the "image-uploader" component utilized by the user triggers some scripts to convert the uploaded image. The user can zoom or move the image inside a canvas, which is then converted to a dummy image that will be automatically uploaded to the input that the initial script awaits.

Image-Uploader Component

The components wait for the user upload

When the image is updated, the user can move and resize the image

First, the custom uploader (the BetterUploader plugin) awaits a single STL file. Then, after the user chooses the exact position of the logo within the canvas (using Fabric.js), a screenshot of the canvas is taken, and the base64 of the image is transformed and reuploaded to Bubble as a dummy image. With a custom JavaScript action, the URL of the image is added to the input element that the original script is awaiting.

javascriptCopy codeasync function loadImageFromURL(imageUrl, inputElement) {
    try {
        // Fetch the image from the URL
        const response = await fetch(imageUrl);
        const blob = await response.blob();

        // Extract the file name from the URL
        const fileName = imageUrl.substring(imageUrl.lastIndexOf('/') + 1);
        const file = new File([blob], fileName, { type: blob.type });

        // Create a DataTransfer object and add the file to it
        const dataTransfer = new DataTransfer();
        dataTransfer.items.add(file);

        // Assign the files from the DataTransfer object to the input element
        inputElement.files = dataTransfer.files;

        // Dispatch a 'change' event to trigger any associated event listeners
        inputElement.dispatchEvent(new Event('change'));

        // Call bubble_fn_yes with the word 'yes'
        bubble_fn_yes('yes');
    } catch (error) {
        console.error('Error fetching the image:', error);
    }
}

// Example usage
const imageUrl = "___"; // Replace with the actual image URL
const fileInputElement = document.getElementById('my-image-input');

loadImageFromURL(imageUrl, fileInputElement);

Finally, thanks to the JavascripttoBubble plugin, an event is triggered that indicates when to delete the dummy image. This ensures that the created images do not use up all available Bubble storage.

Screenshot of 3D Viewer

Since the 3D viewer resides on an external domain, utilizing the html2canvas library is not feasible as it would result in rendering a blank image. However, the SDK provides a method to generate a base64 image when executed. This base64 data needs to be captured by Bubble for further processing.

The script searches for any <div> with a specific class and ID name. Depending on whether the <div> has just the ID or both the ID and the class:

• If a <div> with only the ID is found, clicking on it triggers the capture of an image. The base64 URL of the image is then passed to the JavascripttoBubble plugin for handling.

• If the <div> has both the special ID and class, the script first updates the viewer's camera settings to a predefined position. This ensures that the captured image displays the customized mouthguard in an optimal view.

javascriptCopy code// Screenshot capture button event handler.
document.querySelectorAll(".capture-image").forEach(element => {
  element.addEventListener("click", async () => {
    console.log("captureImage start");

    // Check if the clicked element has the id="setcamera"
    if (element.id === "setcamera") {
      // Update the viewer's camera settings
      await viewer.update({
        camera: {
          type: "ORBITAL_SMART",
          focalLength: 80,
          yaw: 80,
          pitch: 5,
          distanceRestrictionMin: 2.3,
          distanceRestrictionMax: 2.301
        }
      });
    }

    // Capture the image with updated camera settings
    const image = await viewer.captureImage({
      imageWidth: 512,
      imageHeight: 512
    });

    console.log("captureImage end");

    // Get the image data URL
    const imageDataUrl = await image.toDataUrl();

    // Pass the image data URL to bubble_fn_dataURL
    bubble_fn_dataURL(imageDataUrl);
  });
});