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 info@ijewel3d.com for a quote. See License and Pricing for general iJewel3D pricing information.

Do I need a developer to set it up?

For the basic setup, no. You can embed the Wedding Band Builder with a single <iframe> tag, no coding required. 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 fully responsive and optimized for mobile browsers. Touch gestures (pinch to zoom, swipe to rotate) work natively. AR try-on is supported on iOS 15+ (Safari) and Android (Chrome), letting customers see the ring on their hand through their phone camera.

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

Yes. The platform ships with common defaults (Yellow/White/Rose Gold, D-Shape, Flat, Court profiles, Polished/Hammered/Brushed finishes), but you can add custom options:

• Custom profiles: upload .3dm (Rhino) files with your own cross section curves
• 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.

Can I match the configurator to my brand?

Yes. The built-in UI supports full theming: colors, fonts, layout. There are 10 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. The exportConfig() method returns a complete JSON specification of the ring: profile name, exact dimensions (width, height, ring size in mm), metal, finish, diamond setting type, count, and engraving text. This can be forwarded to your manufacturer or CAD team as a production spec. The parametric nature means every dimension is precise, nothing is approximated from a visual.

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. The API provides exportConfig() to save a complete ring configuration as JSON, and importConfig() to restore it. You can store saved designs in your backend, generate shareable links, or let customers resume where they left off. The configuration is a lightweight JSON object (under 1KB), easy to store and transmit.

What support is available?

• Onboarding: dedicated setup assistance is included with every plan
• Documentation: this site covers integration, API reference, and examples
• Email support: info@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 showUI: false in your project config:

plugins: {
  WeddingBandBuilder: {
    manifestUrl: 'wedding-band-project.json',
    showUI: false,
  },
}

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.

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() or importConfig() 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: 'Court' },
    dimensions: { widthMm: 4.5 },
    materials: {
      partition: 1,
      slots: [{ slot: 1, metal: 'Yellow', finish: 'Polished' }],
    },
  });
});

Or restore a previously saved configuration:

await api.importConfig(savedConfig); // applies to both her and his

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: 6.0 },
  materials: {
    partition: 2,
    slots: [
      { slot: 1, metal: 'White', finish: 'Polished' },
      { slot: 2, metal: 'Yellow', finish: 'Brushed' },
    ],
  },
  diamonds: { settingType: 'Channel' },
});

What profiles / metals / finishes are available?

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

api.getAvailableProfiles();     // [{ index: 0, name: 'D-Shape', ... }, ...]
api.getAvailableMetals();       // [{ id: 'Yellow', name: 'Yellow Gold', ... }, ...]
api.getAvailableFinishes();     // [{ id: 'Polished', name: 'Polished', ... }, ...]
api.getAvailableSettingTypes(); // ['none', 'Channel', 'Bezel', 'Prong', ...]
api.getAvailableEdgeTypes();    // ['None', 'Beveled', 'Rounded', 'Sharp']

These return whatever is configured in your manifest on the iJewel platform. Add new options there and they appear automatically, no code changes needed.

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 10 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() to get the full state of both rings, or getSnapshot(bandName) for a single 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: herSnap, price: herPrice }),
});

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?

AR is built in. For direct integration, just make sure the page is served over HTTPS (camera access requires it).

For iframe integration, add the allow attribute:

<iframe src="wbb-viewer.html" allow="camera; xr-spatial-tracking"></iframe>

Without these permissions, the AR button will appear but won't work.

What browsers are supported?

The Wedding Band Builder uses WebGL 2.0 via the iJewel3D engine. It works on all modern browsers:

• Chrome 80+
• Firefox 80+
• Safari 15+
• Edge 80+
• Mobile Safari (iOS 15+)
• Chrome for Android

AR try-on requires WebXR support (Chrome on Android, Safari on iOS 15+).

Performance

How large is the viewer bundle?

The mini-viewer IIFE bundle (including the WebGI engine) is approximately 2-3 MB gzipped. Assets (profiles, materials, environment maps) 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://cdn.ijewel3d.com/mini-viewer/v5.2.1/bundle.iife.js"></script>

Check the Changelog before upgrading. Breaking changes are documented and major versions follow semver.