FAQ

For Businesses

Questions for jewelry brand owners, managers, and decision-makers evaluating the Wedding Band Builder.

What does the Wedding Band Builder cost?

The Wedding Band Builder is part of the iJewel3D platform. The pricing model is one-time onboarding plus an annual subscription. No per-change fees, no opaque project quotes. Contact contact@ijewel3d.com for a quote. See License and Pricing for general iJewel3D pricing information.

Which plan do I need?

Every plan includes the Wedding Band Builder, from Free upward. On any plan you can create a Wedding Band project and use the built-in profile library.

Custom profile upload — your own .3dm cross sections — needs the Silver plan or above. On a lower plan, the upload option shows an upgrade prompt.

A whitelabel embed, with the iJewel branding removed, needs the Gold plan or above. See Whitelabeling and Branding.

Do I need a developer to set it up?

For the basic setup, no. The project itself is created and configured on the iJewel3D platform, no code required (Create a Project). You can then embed the Wedding Band Builder with a single <iframe> tag. Your web team or Shopify/WordPress admin can handle this.

For custom integrations, yes. If you want a fully custom UI, cart integration, or server-side price validation, you'll need a frontend developer. The Quick Start guide covers both paths.

How long does it take to go live?

• Basic iframe embed: same day. Drop the iframe tag into your site, configure your metals and profiles on the iJewel platform, and you're live.
• Custom branded integration: 1-2 weeks for a developer to build custom controls, wire up cart/checkout, and match your brand styling.
• Asset preparation (custom profiles, finishes, scene settings): depends on how many custom assets you need. Built-in profiles and materials work out of the box.

How realistic is the 3D preview?

The Wedding Band Builder uses the iJewel3D photorealistic rendering engine with physically based materials, real time reflections, and HDR environment lighting. The preview closely matches what customers will receive. Metals, surface finishes (hammered, brushed, polished), and diamonds all render with physically accurate properties.

Does it work on my customers' phones?

Yes. The viewer is responsive and supports native touch gestures such as pinch to zoom and swipe to rotate. Camera Try-On works in current Safari on iOS and Chrome on Android when the device passes the Web VTO capability check. Test the devices and in-app browsers most common among your customers.

Can I use my own metals, profiles, and finishes?

Yes. The platform ships with common defaults (Gold/White Gold/Rose Gold; D-Shape, Flat, Concave, Round, Knife Edge, Beveled, and Comfort profiles; and Polished, Hammered, Brush, Ice, Nature, Sand, and Linear finishes), but you can add custom options:

• Custom profiles: upload .3dm (Rhino) files with your own cross section curves (Silver plan or above)
• Custom metals: add Platinum, Palladium, Titanium, etc. with matching PBR materials
• Custom finishes: upload material files for any surface texture

See Assets Setup for details.

Can I control which options customers see?

Yes. The manifest on the iJewel platform defines exactly which profiles, metals, finishes, diamond settings, and edge types are available. Remove options there and they disappear from the configurator, no code changes needed. You can also set default values so every customer starts with your preferred configuration. See Create a Project for editing catalogs and defaults in your project.

Can I match the configurator to my brand?

Yes. The built-in UI supports full theming: colors, fonts, layout. There are 11 built-in presets (luxury-gold, dark, modern-minimal, etc.), or you can set your exact brand colors and typography. For complete control, use Headless mode and build your own interface from scratch.

How does pricing work?

The builder calculates prices in real time based on:

1. Ring weight: computed from the 3D geometry volume and metal density
2. Metal cost: weight multiplied by your price-per-gram
3. Diamond cost: carat weight multiplied by your price-per-carat
4. Markup: a multiplier you set (e.g., 2x, 2.5x)

You configure all pricing parameters (metal prices, diamond rates, markup) on the platform or via the API. Prices update live as customers customize. See Pricing for details.

WARNING

Prices are calculated client-side for display purposes. Always validate the final price on your server before processing an order. Never trust client-submitted prices for payment.

How do customers' designs get to my order system?

When a customer clicks "Add to Cart" or completes their design, your site captures the full ring configuration (profile, dimensions, materials, diamonds, engraving) as a JSON object, along with the price breakdown. You send this to your backend/cart system via a standard API call. Platform specific examples are available for Shopify, WooCommerce, Magento, and others.

Can I send the configuration to my manufacturer?

Yes. Use getSpecSheetData(bandName) for the manufacturing summary, and exportConfig() for a readable record of every band. Both give your CAD or order system precise numbers, because the ring is parametric.

For a design that uses material variants or the outside features (inlays, overlays, sleeve), also store api.toJSON(). That record restores the exact design later.

Does it support multiple languages?

The built-in UI labels (profile names, metal names, finish names) come from your manifest configuration, name them in any language. The fixed UI text (section headers, buttons) currently uses English. For full localization, use Headless mode and build your own UI with your localization framework.

Can customers save or share their designs?

Yes. Save api.toJSON() and restore it with the Wedding Band plugin's fromJSON() method. That pair keeps the complete design, including material variants, inlays, overlays, and the sleeve.

Use exportConfig() when you want a readable summary of every band for an order record, and importConfig() to apply a set of options.

What support is available?

• Onboarding: dedicated setup assistance is included with every plan
• Documentation: this site covers integration, API reference, and examples
• Email support: contact@ijewel3d.com for technical questions
• Partner network: integration partners available for custom builds
• Helpdesk: use the bug report / feedback form for issues

For Developers

Technical questions about integration, API usage, and troubleshooting.

Integration

What's the difference between script tag and iframe embedding?

Script tag loads the viewer on your page via a <script> tag. You get direct JavaScript access to the API. Best when you control the page.

iframe wraps the viewer in an isolated <iframe>. You communicate via postMessage. Best for CMS platforms or when you can't add scripts. See the Script Tag and iframe guides for both approaches.

Can I use it on Shopify / WordPress / Squarespace?

Yes. Use iframe embedding since it works on any platform where you can add an <iframe> tag. You host the viewer page separately and communicate via postMessage. Platform specific examples with Add to Cart wiring:

• Shopify: Liquid section
• WooCommerce: Shortcode + AJAX handler
• Magento: PHTML block + controller
• BigCommerce: Stencil template
• Wix: HTML embed + Velo code

Do you have examples for React / Vue / Angular / Next.js?

Yes. See the Framework Examples table on the Script Tag guide:

• Vanilla JS: plain HTML, no build step
• React: component + hooks
• Vue 3: composable + SFC
• Next.js: client component with SSR handling
• Angular: service + component with RxJS
• Svelte: component with slots

Each example includes both a built-in UI version and a headless variant with custom controls.

How do I hide the built-in panel and build my own UI?

Set hideWbbUi: true in Mini Viewer's options:

{
  showCard: false,
  showConfigurator: false,
  hideWbbUi: true,
}

The 3D viewer renders full width and you control everything through the API. See the Custom UI (Headless) guide for building your own controls.

Where should I host the viewer assets?

The mini-viewer bundle and WebGI engine are served from the iJewel CDN by default. Your manifest and custom assets (profiles, materials) are hosted on the iJewel platform. For the iframe approach, you host a single lightweight HTML page that loads the viewer. This can go on any static host, CDN, or your own server.

PMAT files are not embedded into Mini Viewer or Mini Editor builds. Those bundles contain code and asset URL strings; the browser downloads the selected PMAT from Drive, Packs, or your CDN at runtime. Authoring-only folders such as materials/_sources do not need to be deployed.

For self-hosted deployments, you can serve the IIFE bundle from your own CDN by downloading it from the iJewel platform. Set the basePath option to point to your asset location.

Configuration

How do I set the initial ring configuration on page load?

Use batch() for a new preset, or plugin fromJSON() for a previously saved complete state, after the viewer is ready:

window.addEventListener('ijewel-viewer-ready', async (e) => {
  const api = e.detail.viewer.getPluginByType('WeddingBandBuilder').controller;

  await api.batch({
    profile: { name: 'Concave' },
    dimensions: { widthMm: 1.1 },
    materials: {
      partition: 1,
      slots: [{ slot: 1, metal: 'Yellow', finish: 'Polished' }],
    },
  });
});

Or restore a previously saved complete configuration:

const plugin = viewer.getPluginByType('WeddingBandBuilder');
await plugin.fromJSON(savedPluginState);

How do I apply multiple changes at once without flickering?

Use batch() instead of calling individual setters. It triggers only one geometry rebuild:

await api.batch({
  profile: { name: 'Flat' },
  dimensions: { widthMm: 1.2 },
  materials: {
    partition: 2,
    slots: [
      { slot: 1, metal: 'White', finish: 'Polished' },
      { slot: 2, metal: 'Yellow', finish: 'Brush' },
    ],
  },
  diamonds: { settingType: 'Channel' },
});

For material variants, call setMaterialRef(). When inlays, overlays, or the sleeve change together, call setOutsideFeatures() once. The current batch() method does not apply those fields.

What profiles, materials, qualities, and finishes are available?

It depends on your manifest. Query the catalog at runtime:

api.getAvailableProfiles();     // [{ index: 0, name: 'D-Shape', ... }, ...]
api.getAvailableMaterials('band'); // [{ id: 'yellow', name: 'Yellow Gold', ... }, ...]
api.getAvailableVariants('yellow'); // [{ id: '14k', name: '14k', ... }, ...]
api.getAvailableFinishesFor('yellow'); // Only finishes supported by Yellow Gold
api.getAvailableSettingTypes(); // [{ id: 'none', name: 'None', iconKey: '...' }, ...]
api.getAvailableEdgeTypes();    // [{ id: 'None', name: 'None' }, ...]

Use inlay, overlay, or sleeve instead of band to build a role-specific material picker. These methods return the catalog stored in the project manifest. Run Drive Sync after folder changes so new options reach that manifest.

Can I have two rings (his & hers) on the same page?

Yes. The Wedding Band Builder supports two bands by default (her and his). Switch between them with:

api.switchBand('her');
api.switchBand('his');

Each band has independent configuration (profile, material, diamonds, etc.). The built-in UI includes a toggle. For custom UI, listen to band:switched events to update your controls.

Can I customize the look of the built-in panel?

Yes. Use the theme API to change colors, fonts, and layout:

api.setTheme({
  colors: { primary: '#8B7355', background: '#FAF8F5' },
  fonts: {
    body: "'Cormorant Garamond', serif",
    googleFonts: ['Cormorant+Garamond:wght@400;500;600'],
  },
});

There are 11 built-in presets (luxury-gold, dark, modern-minimal, etc.) or you can fully customize. See the API Reference.

Pricing & Cart

How do I get the ring configuration for my cart / order system?

Use exportConfig() for a readable record of every band, and getSnapshot(bandName) for one ring:

const config = api.exportConfig();       // { her: {...}, his: {...} }
const herSnap = api.getSnapshot('her');  // single ring snapshot
const herPrice = api.getPrice('her');    // price breakdown

// Send to your backend
await fetch('/api/cart/add', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ config, summary: herSnap, price: herPrice }),
});

Add api.toJSON() to the payload when the order must reproduce the exact design later, such as a saved or shared configuration.

How do I listen for price changes?

Subscribe to the price:updated event:

api.events.on('price:updated', (data) => {
  console.log(`${data.bandName}: $${data.pricing.totalUsd.toFixed(2)}`);
});

In an iframe setup, price events are forwarded automatically to the parent page via postMessage. See Pricing for configuration details.

Should I trust the client-side price for checkout?

No. The pricing engine runs in the browser for real time display. A user could modify the DOM or intercept API calls to change the price. Always recalculate the price on your server before processing payment.

The recommended flow:

1. Customer configures ring → client shows live price
2. Customer adds to cart → your backend receives the config JSON via getSnapshot()
3. Your backend recalculates price using the config dimensions, metal prices, and diamond specs
4. Payment is processed against the server-calculated price

The PriceBreakdown object includes all inputs (volume, weight, metal density, price per gram, carat weight, markup) so your backend can verify the math.

// Server-side price validation (Node.js)
function validatePrice(snapshot, pricingParams) {
  const { weightGrams, metal, finish } = snapshot;
  const metalInfo = pricingParams.metalPrices[metal];
  const metalCost = weightGrams * metalInfo.pricePerGram;

  // Making charge (percent mode shown; adapt for 'per-gram' or 'none')
  const makingCharge = pricingParams.makingChargeMode === 'percent'
    ? metalCost * (pricingParams.makingChargePercent / 100)
    : 0;

  const finishSurcharge = pricingParams.finishSurcharges?.[finish] ?? 0;

  // Diamonds (null when no stones are set)
  const diamonds = snapshot.diamonds;
  const stoneCost = diamonds
    ? diamonds.totalCarats * pricingParams.diamondPricePerCarat
    : 0;
  const settingCost = diamonds
    ? diamonds.count * (pricingParams.settingCostPerStone ?? 0)
    : 0;

  const subtotal = metalCost + makingCharge + finishSurcharge + stoneCost + settingCost;
  const total = subtotal * (pricingParams.markupMultiplier ?? 1);
  return total;
}

AR & Mobile

How do I enable AR try-on?

Open the Wedding Band project menu in iJewel3D Platform and select Edit Default Settings. Open TryOn Settings, turn on Enable AR, fit the selected ring in setup mode, and save the defaults. One saved fit applies to all rings in the project. A linked pair asks the customer which ring to try on.

AR is built in. For direct integration, make sure that the page uses HTTPS because the camera requires it.

For iframe integration, add the allow attribute:

<iframe src="wbb-viewer.html" allow="camera; fullscreen"></iframe>

Without camera permission, the Try-On button can appear but the camera cannot start inside the iframe.

What browsers are supported?

The Wedding Band Builder uses WebGL 2.0 through the iJewel3D engine and works in current desktop and mobile versions of Chrome, Edge, Firefox, and Safari.

Camera Try-On does not use WebXR. It requires WebGL 2, camera access through navigator.mediaDevices.getUserMedia, and HTTPS. Device performance also matters. For custom controls, use ij_vto.canRunVTO() before showing the Try-On button:

const support = ij_vto.canRunVTO();

if (!support.ok) {
  console.warn("Try-On unavailable", support.reason, support.details);
}

Test the exact devices and in-app browsers used by your customers instead of depending on a browser version number alone.

Performance

How large is the viewer bundle?

The mini-viewer IIFE bundle (including the WebGI engine) is approximately 2-3 MB gzipped. Assets (profiles, PMAT materials, environment maps) are separate and load on demand after the viewer initializes. First-load time depends on your CDN and the number of assets in your manifest, but the viewer shell typically renders within 1-2 seconds.

Is the ring geometry generated in real time or pre made?

Real time. The Wedding Band Builder uses a parametric approach: 2D profile curves are extruded along a circular path, materials are applied procedurally, and diamonds/edges/grooves are computed on the fly. Every combination produces a unique ring. There's no fixed catalog of 3D models.

Offline & Caching

Does the configurator work offline?

No. The Wedding Band Builder requires an internet connection. The viewer bundle, 3D engine, profile curves, material files, and environment maps are all loaded from the CDN or your asset server. Without connectivity, the viewer cannot initialize.

However, assets are cached by the browser after the first load. Subsequent visits on the same device load significantly faster because profiles, materials, and environment maps are served from the browser cache. The viewer bundle itself is also cached.

If a customer loses connectivity mid-session, the ring they've already configured remains visible and interactive (rotation, zoom). Changes that require loading new assets (switching profiles or materials) will fail until connectivity is restored.

Troubleshooting

The viewer is blank / not loading. What do I check?

1. Script loaded? Check the browser console for 404 errors on the mini-viewer bundle.
2. Container has dimensions? The viewer fills its container. If the container has 0 height, nothing renders. Give it explicit dimensions (e.g., height: 600px).
3. Manifest accessible? The manifestUrl must be reachable from the browser. Check the Network tab for failed fetches.
4. CORS? If your assets are on a different domain, make sure the server sends Access-Control-Allow-Origin headers.
5. Console errors? Check for JavaScript errors. The error event also fires if something goes wrong after initialization:

   api.events.on('error', (err) => console.error(err));

How do I track what customers are configuring?

Listen to change events and send them to your analytics platform:

// Track profile changes
api.events.on('profile:changed', (data) => {
  analytics.track('ring_profile_changed', {
    band: data.bandName,
    profile: data.profileName,
  });
});

// Track material changes
api.events.on('material:changed', (data) => {
  analytics.track('ring_material_changed', {
    band: data.bandName,
    metal: data.metal,
    finish: data.finish,
  });
});

// Track price views
api.events.on('price:updated', (data) => {
  analytics.track('ring_price_viewed', {
    band: data.bandName,
    total: data.pricing.totalUsd,
  });
});

This works with any analytics provider (Google Analytics, Segment, Mixpanel, etc.).

How do I handle version updates?

The viewer bundle is versioned. Pin to a specific version in your script tag or iframe URL to avoid unexpected changes:

<!-- Pinned version -->
<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.18/bundle.nowebgi.iife.js"></script>

The Wedding Band SDK guides pin the release pair that was verified end to end. Check the Changelog before upgrading. The Wedding Band iframe lifecycle fixes require Mini Viewer 0.6.11 or newer. Material variants, the outside and inside material features, and the Modern Metals layout require 0.6.17 or newer. Ring Configurator and Wedding Band Builder Try-On require 0.6.18 or newer.