3D configurator integration overview

This quick overview demonstrates how an Apviz 3D configurator can be integrated on any website.

Release

After having setup your 3D configurator using studio.apviz.io (or the GraphQL API) you will have to create an immutable snapshot of your 3D configurator using the release feature.

The integration URL associated with your release can then be copy/pasted just before the end of the <body> of your HTML page:

<!-- Non-blocking async script that will call "apvizShowcaseReady" once fully loaded. -->
<script
  src="https://public.apviz.io/showcases/U0hPVzoxTFVNSVRkNGNx/releases/UkVMUzozT0RhTk1GUFRC/main.js"
  integrity="sha384-EWrzLL5C335hVPCP2dkfUWTIh0iEnCxMmF5XI4gZlBFuTCtzCjfJpnFQe0jOVWe6"
  defer
  crossorigin="anonymous"
  data-apviz-callback="apvizShowcaseReady"
></script>

Note that integration URL may change for future release, so consider this URL as opaque and don't try to parse it or build it dynamically.

Basic integration (simple viewer)

This example shows you how to integrate a 3D viewer with no configuration menu.

<!DOCTYPE html>
<html>
  <head>
    <title>Apviz - Demo Ring</title>
  </head>
  <body>
    <!-- Apviz 3D viewer. -->
    <div id="apviz-3d-showcase"></div>

    <!-- Your custom initialization script. -->
    <script>
      async function apvizShowcaseReady(showcase) {

        // Initialize a 3D viewer and bind it to the <div>.
        const viewer = await showcase.createViewer({
          divId : "apviz-3d-showcase"
        });

        // Set initial configuration.
        // This will display 3D elements accordingly.
        await viewer.updateConfiguration({
          configuration : {
            "carat" : "1ct",
            "gem" : "diamond",
            "gold" : "yellow"
          }
        });

      }
    </script>

    <!-- Non-blocking async script that will call "apvizShowcaseReady" once fully loaded. -->
    <script
      src="https://public.apviz.io/showcases/U0hPVzoxTFVNSVRkNGNx/releases/UkVMUzozT0RhTk1GUFRC/main.js"
      integrity="sha384-EWrzLL5C335hVPCP2dkfUWTIh0iEnCxMmF5XI4gZlBFuTCtzCjfJpnFQe0jOVWe6"
      defer
      crossorigin="anonymous"
      data-apviz-callback="apvizShowcaseReady"
    ></script>
  </body>
</html>

Integration with a menu

If you want to make your 3D configurable directly within your website you bind your own menu to the Viewer.updateConfiguration method:

<!DOCTYPE html>
<html>
  <head>
    <title>Apviz - Demo Ring</title>
  </head>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    #my-menu { position: absolute; top: 0; left: 0; padding: 10px; background-color: #ffffff; }
  </style>
  <body>
    <!-- Apviz 3D viewer. -->
    <div id="apviz-3d-showcase"></div>

    <!-- Your custom configuration menu. -->
    <div id="my-menu">
      <label for="carat">carat:</label>
      <select id="carat">
        <option>1ct</option>
        <option>0.5ct</option>
      </select>
      <label for="gem">gem:</label>
      <select id="gem">
        <option>diamond</option>
        <option>ruby</option>
      </select>
      <label for="gold">gold:</label>
      <select id="gold">
        <option>yellow</option>
        <option>white</option>
      </select>
    </div>

    <!-- Your custom initialization script. -->
    <script>
      async function apvizShowcaseReady(showcase) {

        // Initialize a 3D viewer and bind it to the <div>.
        const viewer = await showcase.createViewer({
          divId : "apviz-3d-showcase"
        });

        // Set initial configuration.
        // This will display 3D elements accordingly.
        await viewer.updateConfiguration({
          configuration : {
            "carat" : "1ct",
            "gem" : "diamond",
            "gold" : "yellow"
          }
        });

        // Menu initialization.
        document.querySelectorAll("#my-menu select").forEach((select) =>
          select.addEventListener("change", () =>
            viewer.updateConfiguration({
              configuration: {
                [select.id]: select.value
              }
            })
          )
        );
      }
    </script>

    <!-- Non-blocking async script that will call "apvizShowcaseReady" once fully loaded. -->
    <script
      src="https://public.apviz.io/showcases/U0hPVzoxTFVNSVRkNGNx/releases/UkVMUzozT0RhTk1GUFRC/main.js"
      integrity="sha384-EWrzLL5C335hVPCP2dkfUWTIh0iEnCxMmF5XI4gZlBFuTCtzCjfJpnFQe0jOVWe6"
      defer
      crossorigin="anonymous"
      data-apviz-callback="apvizShowcaseReady"
    ></script>
  </body>
</html>

Progress events

You can use Viewer.addUpdatingListener to subscribe to update progress events. This is specially useful to display a progress bar:

async function apvizShowcaseReady(showcase) {

  // Initialize a 3D viewer and bind it to the <div>.
  const viewer = await showcase.createViewer({
    divId : "apviz-3d-showcase"
  });

  // Handles the progress bar.
  const myLoader = document.getElementById("myLoader");
  await viewer.addUpdatingListener(progress => {
    myLoader.innerHTML = `${progress} %`;
    myLoader.style.display = progress === 100 ? "none" : "block";
  });

  // Set initial configuration.
  // This will display 3D elements accordingly.
  await viewer.updateConfiguration({
    configuration : { ...  }
  });

}

The progress event is specially designed not to bloat your UI. Progress event only triggers:

  • When appropriate (HTTP requests > 500ms)
  • With a minimum 500ms resolution

You can unsubscribe your callback from update events using Viewer.removeUpdatingListener.

Note that if you only need to do things before/after 3D has been loaded (without progress), you only have to add asynchronous code before or after Viewer.updateConfiguration.

Dispose

One important aspect in order to improve performance and avoid memory leaks in your application is the disposal of unused 3D viewer. Whenever you create an instance of a 3D viewer, you allocate a certain amount of GPU memory that is necessary for rendering. It's important to highlight that GPU memory is not released automatically. Instead, your application has to use Viewer.dispose() in order to free such resources.

await viewer.dispose();

This is specially useful if you integrate Apviz within a Single-page application (SPA) or if you show/hide 3D multiple times within the same HTML page.

If you use a Multiple-page application (MPA) and the 3D viewer is only showed once, you can skip disposal.

Note that Viewer.dispose() will also unbind the 3D viewer from your <div> making it possibly available for another 3D viewer.

Get fields

If you need to get all configurable field values at runtime you can call the static getFields method:

async function apvizShowcaseReady(showcase) {
  // getFields returns an object with the following structure:
  // {
  //   fields : [
  //    { key: "carat", values: [{ value: "0.5ct" }, { value: "1ct" }] }, 
  //    { key: "gem", values: [{ value: "diamond" }, { value: "ruby" }] },
  //    { key: "gold", values: [{ value: "yellow" }, { value: "white" }] }  
  //   ]
  // }
  const { fields } = await showcase.getFields();
}

This method is intended to ease debugging or fast prototyping. Keep in mind that Apviz is not designed to handle UX (human readable) menu items.

Content Security Policy

Content Security Policies are delivered as a header to your users' browser by your web-server and they are used to declare which dynamic resources are allowed to load on your page.

For many websites, this is often as straightforward as declaring that only scripts/styles from your own domain and that of any tools that you are using is allowed, but this can become more involved when complex setups are in play.

If you identify CSP errors on your site, you will need to work with your development team or hosting provider to adjust your CSP settings by adding the following rules:

img-src https://public.apviz.io blob:;
script-src https://public.apviz.io;
style-src https://public.apviz.io;
connect-src https://public.apviz.io;

Compatibility

Apviz 3D configurator is standard HTML and JavaScript making it compatible with all CMS and e-commerce platforms like:

More features!

This was just a quick overview of how to integrate a basic Apviz 3D configurator to a website. But we have many more features available like:

  • Dynamic text embossing/debossing (for engraving, web to print)
  • Dynamic image embossing/debossing (for engraving, web to print)
  • Virtual try-on (augmented reality)
  • Batch packshot
  • Etc.

More documentation is avaible on studio.apviz.io.

Request a free access and start building and integrating your own 3D configurators on your website today!