iJewel3D Docs

Appearance

Add an iJewel3D Drive Viewer to Your Website ​

Connect iJewel Viewer and Drive

Open beta

The iJewel Drive embed and Viewer SDK are currently in open beta.

Please let us know on our Discord or by email at contact@ijewel3d.com if you face any issues or would like to request any features.

Docs for old iJewel Drive

The documentation for iJewel Drive instances created before March 2025 is available here.

Choose an integration method ​

RequirementRecommended method
Add a self-contained viewer with minimal codeIframe embed
Control the viewer from your page or applicationMini Viewer SDK

Option 1: Iframe embed ​

An iframe is the quickest way to add a model with its configured viewer settings. Replace {MODEL_ID} with the model's iJewel Drive file ID.

html
<iframe
  src="https://drive.ijewel3d.com/drive/files/{MODEL_ID}/embedded"
  title="Interactive 3D product viewer"
  loading="lazy"
  allow="autoplay; fullscreen; xr-spatial-tracking; web-share"
  allowfullscreen
  style="width: 100%; min-height: 420px; aspect-ratio: 16 / 9; border: 0;"
></iframe>

The base URL in the example is for the standard iJewel Drive. Enterprise customers should use the URL for their Drive instance.

TIP

For more control over the embedded viewer's appearance, open the model in the editor, select the Embed (</>) tool, choose the available branding and control settings, preview the viewer, and copy the generated iframe. See Create an iJewel Viewer Embed for the complete flow.

Option 2: Mini Viewer SDK ​

Use the Mini Viewer SDK when your page needs to control the viewer, respond to viewer events, or coordinate it with other UI.

  • Standard iJewel Drive users should keep the basename as drive.
  • Enterprise customers should use the basename supplied by iJewel3D.
  • Give the viewer container an explicit width and height.
  • See Connect to iJewel Drive for the complete API.
html
<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>iJewel3D Viewer</title>
</head>

<body>
  <div id="root"></div>
  <script src="https://releases.ijewel3d.com/libs/webgi-v0/bundle-0.22.0.js"></script>
  <script src="https://releases.ijewel3d.com/libs/mini-viewer/0.6.8/bundle.nowebgi.iife.js"></script>
  <script>
    const basename = "drive";
    const modelId = "{MODEL_ID}";

    ijewelViewer.loadModelById(
      modelId,
      basename,
      document.getElementById("root"),
      {
        showCard: true,
        brandingSettings: {
          enable: true,
        },
      },
    );

  </script>
  <style>
    #root {
      width: 100vw;
      height: 100dvh;
    }
  </style>
</body>

</html>

Domain authorization

Iframe embeds generally work across domains without authorizing every destination domain.

The Mini Viewer SDK requires each hosting domain to be authorized by iJewel3D. See Host and domain setup.

Find the model ID ​

Both methods require the model's unique Model ID, also called its File ID:

  1. Open your iJewel Drive and find the model.
  2. Right-click the model and select Share.
  3. Find the viewer link, which has a format similar to https://.../files/MODEL_ID/view.
  4. Copy the value between /files/ and /view.

Applying Materials via URL ​

Apply specific materials automatically when the viewer loads by adding parameters to the URL. This works for both the iframe src and the direct link.

Use either query parameters (?) or hash parameters (#?). The format is key=value where:

  • key is the Layer Name (e.g., Metal, Gem Stone).
  • value is the Variation Name (e.g., White Gold, ruby).

Examples:

  • https://ijewel3d.com/drive/files/{MODEL_ID}/embedded?Metal=Gold
  • https://ijewel3d.com/drive/files/{MODEL_ID}/embedded#?Band=Rose-Gold&Gem=Ruby
  • https://ijewel.design/embedded?slug=d8c22bf&Metal=Gold

Finding Layer and Option Names ​

To find the correct names to use in the URL:

  1. Layer Name is the left side (key) of query parameter. It is same as the tab's name at the bottom of the configurator. Right click on the name at the bottom of the editor and select Edit. Layer Name
  2. For variation names, hovering over the variation icon will show the variation name with an edit icon next to it, click on the edit icon to edit the variation name. Variation Name

TIP

Use #? to apply materials via URL in runtime without the need to reload the page. e.g. https://ijewel3d.com/drive/files/{MODEL_ID}/embedded#?Band=Rose-Gold&Gem=Ruby
Alternatively, this can be used to implement custom UI for the material configurator:

html
<button onclick="setMaterial('Metal', 'White-Gold')">Apply Material</button>
<script>
    const iframe = document.getElementById('viewer-frame');

    function setMaterial(layer, name) {
        const url = new URL(iframe.src)
        url.hash = `?${layer}=${name}`
        iframe.src = url.toString()
    }
</script>

Host and domain setup ​

When using the Mini Viewer SDK:

  • Host the HTML/JavaScript code on your website server.
  • Send iJewel3D support the exact production domain where the viewer will run, such as www.example.com. The domain must be authorized before the SDK can load models from your Drive instance.