Using Ring Configurator

iJewel Ring Configurator

This guide covers how to deploy and use your ring configurator after setting it up in the iJewel3D platform.

Deployment Options

Once your Ring Configurator is configured, you have three ways to deploy it:

Option	Best For	Complexity
Direct Embedding	Quick integration	Low
Share Link	Sending to customers	None
Self-Hosted Template	Full customization	Medium

Make Your Configurator Public

Before using any deployment option, you need to set your Configurator file's visibility to Public. By default, configurators are only accessible internally within the iJewel3D platform. To make it available externally via embedding, sharing, or self-hosting, follow these steps:

Right-click on your Configurator file in the iJewel3D platform.
Select Make Public.

Make Configurator Public

Option 1: Direct Embedding

Embed your ring configurator directly on any webpage using an iframe.

html

<iframe 
  src="https://ijewel3d.com/<your-instance-name>/<your-configurator-file-id>/embedded" 
  width="100%" 
  height="600"
  frameborder="0">
</iframe>

Learn more about embedding configurators.

Share your configurator directly with customers using the link from the iJewel3D platform. This requires no coding.

Just right click on Ring configurator. Click on share. Copy the link and share it with your customers.

Option 3: Self-Hosted Template

For full control over the UI and user experience, use the self-hosted template approach.

Prerequisites

Your File ID from the iJewel3D platform
Your Instance Name (provided by iJewel, e.g., dev-2)

Basic Setup

Create an index.html file with this minimal structure:

html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Ring Configurator</title>
    <style>
        body { font-family: sans-serif; display: flex; height: 100vh; margin: 0; }
        #viewer { flex: 2; }
        #controls { flex: 1; padding: 20px; overflow-y: auto; }
        .group { margin-bottom: 20px; border-bottom: 1px solid #ccc; padding-bottom: 10px; }
        button { margin: 5px; padding: 8px; cursor: pointer; }
        button.active { background: #000; color: #fff; }
    </style>
</head>
<body>
    <div id="viewer"></div>
    <div id="controls"><h2>Controls</h2></div>

    <!-- Load iJewel Viewer -->
    <script src="https://releases.ijewel3d.com/libs/mini-viewer/0.5.10/bundle.iife.js"></script>
    
    <script>
        // ============ CONFIGURATION ============
        const CONFIG = { 
            fileId: 'YOUR_FILE_ID',      // Replace with your File ID
            instance: 'YOUR_INSTANCE'     // Replace with your instance name
        };
        
        let viewer, ringConfigurator, materialPlugin;
        const ui = document.getElementById('controls');

        // Initialize viewer
        ijewelViewer.loadModelById(CONFIG.fileId, CONFIG.instance, document.getElementById('viewer'), {
            showConfigurator: false,
            showCard: false,
        });

        // Wait for viewer to be ready
        window.addEventListener('ijewel-viewer-ready', ({ detail }) => {
            viewer = detail.viewer;
            ringConfigurator = viewer.getPluginByType('RingConfigurator');
            materialPlugin = viewer.getPluginByType('MaterialConfiguratorPlugin');
            
            // Re-render UI when components or materials change
            if (ringConfigurator) ringConfigurator.addEventListener('componentProcessed', renderUI);
            if (materialPlugin) materialPlugin.addEventListener('refreshUi', renderUI);
            
            renderUI();
        });

        function renderUI() {
            ui.innerHTML = '<h2>Controls</h2>';
            renderComponents();
            renderMaterials();
        }

        // Render ring components (Heads, Shanks, etc.)
        function renderComponents() {
            if (!ringConfigurator?.components) return;
            
            ringConfigurator.components.forEach((component) => {
                if (!component.visible) return;
                
                const div = document.createElement('div');
                div.className = 'group';
                div.innerHTML = `<h3>${component.name}</h3>`;
                
                component.variations.forEach((variation, index) => {
                    const btn = document.createElement('button');
                    btn.textContent = variation.name || variation.title || `Variation ${index}`;
                    
                    if (index === component.selectedIndex) btn.className = 'active';

                    btn.onclick = async () => {
                        btn.textContent = '...';
                        await component.applyVariation(variation);
                        renderUI();
                    };
                    div.appendChild(btn);
                });
                ui.appendChild(div);
            });
        }

        // Render material options (Metals, Gems, etc.)
        function renderMaterials() {
            if (!materialPlugin?.variations) return;
            
            materialPlugin.variations.forEach((group) => {
                if (!group.materials) return;

                const div = document.createElement('div');
                div.className = 'group';
                div.innerHTML = `<h3>${group.title}</h3>`;
                
                group.materials.forEach((mat, index) => {
                    const btn = document.createElement('button');
                    btn.textContent = mat.userData?.label || mat.name || mat.uuid;
                    
                    if (group.selectedIndex === index) btn.className = 'active';
                    
                    btn.onclick = async () => {
                        await materialPlugin.applyVariation(group, mat.uuid);
                        renderUI();
                    };
                    div.appendChild(btn);
                });
                ui.appendChild(div);
            });
        }
    </script>
</body>
</html>

Configuration Variables

Variable	Description
`fileId`	Your ring configurator's unique ID from the iJewel3D platform
`instance`	Your client identifier provided by iJewel (e.g., `drive`)

Core Concepts

The RingConfigurator Plugin

The RingConfiguratorPlugin manages ring components (heads, shanks, bands) and their variations.

javascript

// Get the plugin
const ringConfigurator = viewer.getPluginByType('RingConfigurator');

// Access components
ringConfigurator.components.forEach(component => {
    console.log(component.name);           // "Heads", "Shanks", etc.
    console.log(component.variations);     // Available variations
    console.log(component.selectedIndex);  // Currently selected index
});

// Apply a variation
await component.applyVariation(variation);

The MaterialConfigurator Plugin

The MaterialConfiguratorPlugin handles material changes (metals, gems, finishes).

javascript

// Get the plugin
const materialPlugin = viewer.getPluginByType('MaterialConfiguratorPlugin');

// Access material groups
materialPlugin.variations.forEach(group => {
    console.log(group.title);      // "Metal", "Gem", etc.
    console.log(group.materials);  // Available materials
});

// Apply a material
await materialPlugin.applyVariation(group, material.uuid);

Events

Event	Plugin	Description
`componentProcessed`	RingConfigurator	All components finished loading
`refreshUi`	MaterialConfigurator	Materials updated, refresh UI
`ijewel-viewer-ready`	Window	Viewer is initialized and ready

Viewer Options

Customize the viewer by passing options to loadModelById:

javascript

ijewelViewer.loadModelById(fileId, instance, container, {
    showConfigurator: false,    // Hide default configurator UI
    showCard: false,            // Hide product card
    transparentBg: false,       // Use solid background
    showLogo: true,             // Show brand logo
    hideFullScreen: true,       // Hide fullscreen button
    hideResetView: true,        // Hide reset view button
    hideFitScene: true,         // Hide fit scene button
    hideRotateCamera: true,     // Hide camera rotation controls
    hideCameraViews: true,      // Hide camera view presets
    brandingSettings: {
        enable: true,
        showLoadingScreenLogo: true
    }
});

Advanced: Using Tags for Filtering

Variations can include tags for filtering (e.g., by shape or carat size):

javascript

function parseVariationTags(variation) {
    const tags = variation.tags || [];
    let shape = null, size = null;
    
    tags.forEach(tag => {
        if (tag.startsWith('shape:')) shape = tag.split(':')[1];
        if (tag.startsWith('size:')) size = tag.split(':')[1];
    });
    
    return { shape, size };
}

// Usage: Group heads by diamond shape
const groups = {};
component.variations.forEach(variation => {
    const { shape } = parseVariationTags(variation);
    if (shape) {
        if (!groups[shape]) groups[shape] = [];
        groups[shape].push(variation);
    }
});

Ready-Made Templates

All templates are open-source and available on GitHub: iJewelTemplates/ringconfigurator

We provide pre-built templates that you can use instantly — just pass your fileId and instanceName as query parameters in the URL. No coding required to get started!

How It Works

Append your credentials to any template URL like this:

https://ijewel3d.github.io/iJewelTemplates/ringconfigurator/simple/ring-configurator.html?fileId=YOUR_FILE_ID&instanceName=YOUR_INSTANCE_NAME

Replace YOUR_FILE_ID and YOUR_INSTANCE_NAME with the values from your iJewel3D platform.

Available Templates

Simple Ring Configurator

A minimal, clean configurator with basic component and material controls.

Open Template

Configurator with Size & Shape

Adds size and shape filtering using tag-based grouping.

Open Template

Advanced Template

A feature-rich configurator with a polished UI and advanced controls.

Open Template

Advanced Template v2

The latest version of the advanced template with an updated design and improved UX.

Open Template

Quick Start

Pick any template above, append ?fileId=YOUR_FILE_ID&instanceName=YOUR_INSTANCE_NAME to the URL, and open it in your browser to instantly preview your ring configurator with your own 3D models.

Example

If your File ID is abc123 and your instance name is drive, open:

https://ijewel3d.github.io/iJewelTemplates/ringconfigurator/advanced/template-v2.html?fileId=abc123&instanceName=drive

This will load the Advanced Template v2 with your ring configurator data rendered in real-time.

Next Steps

Review the full RingConfigurator Plugin API
Learn about embedding configurators

Contact

For questions or assistance, email us at [email protected]

Rhino Plugin

Using Ring Configurator ​

Deployment Options ​

Make Your Configurator Public ​

Option 1: Direct Embedding ​

Option 2: Share Link ​

Option 3: Self-Hosted Template ​

Prerequisites ​

Basic Setup ​

Configuration Variables ​

Core Concepts ​

The RingConfigurator Plugin ​

The MaterialConfigurator Plugin ​

Events ​

Viewer Options ​

Advanced: Using Tags for Filtering ​

Ready-Made Templates ​

How It Works ​

Available Templates ​

Simple Ring Configurator ​

Configurator with Size & Shape ​

Advanced Template ​

Advanced Template v2 ​

Example ​

Next Steps ​

Using Ring Configurator

Deployment Options

Make Your Configurator Public

Option 1: Direct Embedding

Option 2: Share Link

Option 3: Self-Hosted Template

Prerequisites

Basic Setup

Configuration Variables

Core Concepts

The RingConfigurator Plugin

The MaterialConfigurator Plugin

Events

Viewer Options

Advanced: Using Tags for Filtering

Ready-Made Templates

How It Works

Available Templates

Simple Ring Configurator

Configurator with Size & Shape

Advanced Template

Advanced Template v2

Example

Next Steps