Skip to documentation

Your products.
Interactive, on any website.

Embed a published 3D product, connect your own controls, and build a configurator that feels native to your website.

HTML embed
Available

Any website or CMS. No SDK or secret API key required.

JavaScript SDK
Local preview

Framework-independent controls, typed events, and lifecycle handling.

React wrapper
Local preview

The same SDK with automatic mounting, cleanup, and error UI.

From published product to live embed

1. Publish a product
Upload and configure a model in the asset library, then publish it.
2. Create an embed
Select your model in the asset library, open Share & Embed in its settings, and create an embed.
3. Embed and connect
Copy the deployment URL below or load it in the playground. Give the container an explicit height.
Local SDK Packages Notice
The SDK packages are included in this repository but are not published to npm. Build them locally with npm run build --workspace=@product-viewer/sdk and npm run build --workspace=@product-viewer/react. External projects can install the tarballs produced by npm pack in each package.

Replace YOUR_DEPLOYMENT_ID with an active deployment UUID, or load a real URL in the playground to update these examples.

HTML embed
<div style="width: 100%; height: 480px;">
  <iframe
    src="https://neidoz.com/deployments/YOUR_DEPLOYMENT_ID/view"
    title="3D Product Viewer"
    style="display: block; width: 100%; height: 100%; border: 0;"
    allow="xr-spatial-tracking; web-share; fullscreen"
    loading="lazy"
  ></iframe>
</div>

Deployments resolve the latest published manifest. Paused deployments, unpublished products, and deleted products are unavailable.

Analytics & Privacy
Model analytics is off by default. Enable it in the model's General settings to collect anonymous metrics automatically in customer embeds, including plain iframes. Changes apply on the next viewer load without publishing. SDK/React integrations can explicitly disable collection with analyticsConsent: false, or bind it to a consent manager. A grant cannot override a disabled model. DNT/GPC always disable collection. No analytics cookies, storage, visitor identity, URLs or order data are used. Changed memory-only summaries send at most every two minutes plus a best-effort exit flush. After pending data is delivered, unchanged idle viewers send nothing until new input or a load outcome. Collection runs only in customer-facing viewers; this website's editor and playground previews do not collect analytics. Merchant SDK controls still count as viewer interaction. Metrics describe engagement and load outcomes, not unique shoppers or purchases.

Try the real integration

These controls use the same local React wrapper and JavaScript SDK documented here. Only choices returned by the published product are offered.

Paste any active, published deployment URL. No viewer account is needed to open it. A site-wide sample can be configured with PUBLIC_DEMO_DEPLOYMENT_ID.

Not connected
Live viewer
Load a deployment to test real viewer controls. This preview does not use a simulated model.
Viewer Controls
Live event log
  1. No events yet.

Methods, events, and lifecycle

Create a client with createViewer({ container, deploymentUrl, timeoutMs?, title? }). The default timeout is 30,000 ms; increase it for large products on slower networks. Methods validate input and return promises. An acknowledgement means the change was accepted; material loading and rendering may continue afterward.

JavaScript SDK Method Reference
JavaScript SDK method reference
MethodReturnsBehavior
ready()Promise<void>Wait for the first rendered model frame and interactive geometry. Calls queue until ready; the default timeout is 30 seconds.
capabilitiesreadonly ViewerCapability[]After the handshake, discover enabled control families. This is not a guarantee of available materials, clips, or XR hardware.
getState()Promise<ViewerState>Discover published component IDs, allowed materials, hideability, animation IDs, and current selections. No private manifest or renderer objects.
getCamera()Promise<ViewerCamera>Read position and orbit target as [x, y, z] tuples in viewer scene coordinates.
setCamera({ position, target })Promise<void>Set both camera vectors. Orbit distance and angle limits still apply.
resetCamera()Promise<void>Reset the camera to the controls' saved initial view.
selectMaterial(componentId, materialId)Promise<void>Choose a material returned for that component. Shared material groups update together.
setComponentVisibility(componentId, visible)Promise<void>Change visibility only for components marked hideable in the published product.
selectComponent(componentId | null)Promise<void>Select/highlight a published component or clear selection.
setAnimation(animationId, playing, { speed?, loop? })Promise<void>Control a discovered model clip. Speed must be greater than 0 and at most 10.
setMeasurements(visible, unit?)Promise<void>Show published dimensions; unit is cm, m, or in. Does not author new measurements.
setMarkers(visible)Promise<void>Show or hide published annotations. Does not author new markers.
setAutoRotate(enabled, speed?)Promise<void>Override the saved rotation setting for this instance. Optional speed is greater than 0 and at most 10, using OrbitControls units.
setAnalyticsConsent(granted)Promise<void>Overrides analytics for this viewer; omitted options follow the saved model setting. False stops collection; true cannot enable a disabled model. DNT/GPC override grants. React: analyticsConsent prop.
on(listener)() => voidSubscribe to validated status, state-change, and error events. Returns an unsubscribe function.
destroy()voidRemove the iframe, timers and listeners; reject outstanding requests with DESTROYED. Idempotent.
Build a material selector
const state = await viewer.getState();
const component = state.components.find(item => item.materials.length > 1);
if (component) {
  await viewer.selectMaterial(component.id, component.materials[1].id);
}

const unsubscribe = viewer.on(event => {
  if (event.type === "state-change") {
    console.log("Current selection", event.state);
  }
});
// unsubscribe(); // when this listener is no longer needed
Typed Events
  • status: loading, ready, or error.
  • state-change: a public state snapshot, coalesced to at most 10 per second.
  • reload: the nested renderer reloaded.
  • error: a code and actionable message.
React and SSR

The wrapper accepts deploymentUrl, timeoutMs, onReady, onEvent, and onError, plus div attributes. It mounts only in the browser and destroys the client on unmount or URL changes. In Next.js, use it inside a client component.

Each embed has an independent instance ID and iframe. Multiple viewers can coexist without sharing rendering state. Reloading rejects outstanding requests with RELOADED; call ready() again. Your own async event handlers should catch rejected promises.

Camera vectors use viewer scene coordinates, not real-world centimeters. Animation and component IDs are discovered from getState(); revalidate them after republishing. This release does not provide versioned configuration export/restore or authoritative shopping-cart pricing.

Use it on your platform

Shopify

Paste the HTML snippet into a Custom Liquid block in the theme editor, save, and publish. Custom JavaScript controls require a theme asset or app integration.

Webflow

Add an Embed element, paste the HTML snippet, set a container height, and publish. Check the published site; editor previews can restrict embedded scripts.

WordPress

Use a Custom HTML block or an HTML widget. Your editor, role, or site policy may strip iframes; verify the saved public page.

For Vue, Svelte, or plain JavaScript, create the SDK client after mounting and call destroy() before removing the container. No framework-specific rendering engine is required.

Compatibility and permissions

Requirements & Permissions
  • The renderer uses WebGPU with a WebGL2 fallback where supported. Device, driver, and model features can affect rendering; this is not a certification of every browser/device combination.
  • Use HTTPS in production. AR/VR depend on browser, hardware, permissions, and user gestures. The embed delegates XR/fullscreen permissions; this SDK release does not programmatically start XR sessions.
  • Serve assets with correct CORS headers. If your website uses CSP, permit the deployment host in frame-src; the deployment host must permit the renderer host.
  • Reserve the container height to avoid layout shift. Measure first interactive frame on representative mobile devices, network conditions, and your actual model sizes.
  • A public deployment URL and its public assets are not private credentials or DRM. Never put management tokens into a URL, iframe, or browser bundle.

Diagnose integration problems

Blank or unavailable viewer
Open the deployment URL directly. Check that the deployment is active and the product is published, not deleted, and has a generated manifest. Check container height, CSP, and asset requests.
TIMEOUT / LOAD_FAILED
Confirm the model and environment are reachable. Inspect the browser console and network panel. Increase timeoutMs for heavy assets; a timeout is not evidence that loading succeeded.
NOT_FOUND / NOT_ALLOWED
Refresh getState() and use the IDs and material choices it returns. Only published hideable components may be hidden.
UNSUPPORTED_FEATURE
Screenshots are not enabled for public embeds in 0.1.0. takeScreenshot() explicitly rejects with this code. Editor capture/authoring tools are not part of this public contract.
NOT_READY / RELOADED / DESTROYED
Await ready() before use. After reload, await it again; after destroy(), create a new client. The React wrapper handles mount/unmount cleanup.
INVALID_COMMAND / INVALID_RESPONSE / PROTOCOL_MISMATCH / INTERNAL_ERROR
Check parameters and matching SDK/viewer versions. Invalid protocol responses and renderer operations are failures, not successful empty results. Keep the error code and reproduction details when reporting a problem.

Availability, releases, and next steps

0.1.0 / protocol v1 - local integration preview

Versioned request/response transport, origin-checked nested iframe relay, core viewer controls, capability discovery, typed events, and local JavaScript/React packages.

REST management APIs, API-key generation, external webhooks, configuration persistence, public engine extensions, and a hosted status service are not available in this release. No uptime claim or support SLA is implied.

Before a public SDK release: validate your supported browser/device matrix, configure a published demo deployment, publish versioned packages, and establish support and deprecation policies. Report integration issues through the repository issue tracker with SDK version, browser/device, error code, and a minimal reproduction. Do not include private assets or tokens.