Viewrium Docs

Embed the viewer

Drop the <viewrium-viewer> web component on any page to render the 3D/AR viewer.

The Viewrium embed is a framework-free web component, <viewrium-viewer>, served from https://cdn.viewrium.com/v1/embed.js. Add two things to a page and a published product's model renders as an interactive 3D viewer with an AR button - no build step, no framework.

The two lines

<!-- 1. Load the Viewrium embed once per page. -->
<script src="https://cdn.viewrium.com/v1/embed.js" data-pk-key="pk_live_..."></script>

<!-- 2. Drop a component wherever you want the viewer. -->
<viewrium-viewer product-id="0b1e...-product-uuid" style="width: 100%; height: 480px;"></viewrium-viewer>

That is the whole integration. The embed reads your publishable key once, opens the product, and renders its model.

product-id is the product's id. A product's custom_id defaults to that same id, so the key you embed with always exists - see custom_id.

Embed by your own id

If you gave a product your own custom_id (a SKU, say), embed it by that instead, so your storefront template can print the id it already knows:

<viewrium-viewer custom-id="SKU-123" style="width: 100%; height: 480px;"></viewrium-viewer>
  • Scoped to your organization. A custom id is unique within an organization, and the embed looks it up within the organization of the page's publishable key only. Another organization's products are never found, whatever their custom ids.
  • The same rules as product-id. The key's allowed domains, and the product being published with a ready model, apply exactly as they do to an id. A custom id that does not resolve hides the viewer exactly as an unknown product id does, and no model loads.
  • custom-id wins. If a component carries both custom-id and product-id, it shows the product the custom id names.
  • Publishable keys only. custom-id is for the pk_ embed. Write the value as an HTML attribute: ", &, < and > in it are escaped as &quot;, &amp;, &lt; and &gt; (the dashboard's Embed dialog does this for you).

The lookup is GET /v1/products/lookup?custom_id=...; the viewer then opens the product by the id it answers, exactly as with product-id.

The publishable key goes on the script, once

Your publishable (pk_) key lives on the data-pk-key attribute of the embed <script> tag - once per page, not on each component. Every <viewrium-viewer> on the page uses it. (A single component can carry its own key in a pk attribute instead.)

  • Publishable keys are safe to expose in the browser. They are origin-gated: a key only works from your organization's allowed domains, so add your site's domain under Settings -> Advanced -> Allowed domains. With no domains listed, the key works nowhere but on Viewrium's own pages.
  • A pk_ key can only read published products, open them in the viewer, and send analytics beacons - it cannot generate or modify anything, and it receives an allow-listed subset of the product rather than the whole of it. See Authentication.

The viewer never receives a permanent URL to the model file, and there is no attribute to give it one (src is refused). Each time it renders, it asks the API for a short-lived, single-use ticket for that product, and the model is fetched once through it. AR on Android opens Google's Scene Viewer, which downloads the model itself, so the AR button asks for a second ticket of its own. You do not handle any of this: place the component, and it does the rest.

model-viewer loads itself

<viewrium-viewer> wraps Google's <model-viewer>. If your page has not already loaded it, the embed adds one type="module" script for a copy hosted by Viewrium (once per page, however many components you place) and renders when it is ready. If your page already loads model-viewer, the embed uses yours and adds nothing. To pin the version yourself, load it before the embed script - Android AR is built against model-viewer 4.4.0, and on another version the embed falls back to WebXR-only AR on Android rather than risk a broken Scene Viewer launch.

Everything the viewer loads comes from Viewrium: model-viewer itself and the decoders it needs (Draco mesh compression, KTX2 textures, meshopt, Lottie) are served from www.viewrium.com, so your visitors' browsers never contact a third-party CDN on the viewer's behalf. If your page configures model-viewer's decoder locations itself (self.ModelViewerElement), your settings are kept.

Component attributes

AttributeDefaultDescription
product-id(required unless custom-id)The id of a published product whose model is ready.
custom-idYour own custom_id for the product, looked up within your key's organization. Wins over product-id. Publishable keys only. See Embed by your own id.
camera-controlsonLet the user orbit/zoom. Set camera-controls="false" to disable.
auto-rotateoffSlowly spin the model. Set auto-rotate (or ="true") to enable.
aronShow the AR button (WebXR / Scene Viewer / Quick Look). Set ar="false" to hide.
ar-placementthe product'sWhere Scene Viewer and WebXR place the model: floor or wall. Defaults to the product's own setting (a wall-mounted product opens on a wall); set it to override that on this page. Quick Look picks the surface the shopper points at.
posterproduct thumbnailImage shown while the model loads. Defaults to the product's thumbnail.
altproduct titleAccessible description. Defaults to the product's title.
desktopthe product's, else viewerWhat a computer shows: viewer, qr, button or hidden. See Display modes.
mobilethe product's, else viewerWhat a phone or tablet that can do AR shows: viewer, button or hidden (qr means button there).
themeautoThe color theme of the View in your room button, its dialog and the QR card: auto (follows the shopper's light or dark system setting), light or dark. Any other value means auto. See Theme.
pkthe script's keyThis component's own publishable key, instead of the page-wide one.
api-basehttps://api.viewrium.comOverride the API origin (rarely needed).

Boolean attributes follow the HTML convention used here: omit for the default, or set ="false" to turn one off. Example:

<viewrium-viewer
  product-id="0b1e...-product-uuid"
  auto-rotate
  ar="false"
  style="width: 100%; height: 480px;"
></viewrium-viewer>

The earlier tag, <viewrium-model model-id="...">, still works and behaves identically. It is deprecated: use <viewrium-viewer product-id="..."> in new pages.

Desktop and mobile display

Each product stores how the embed shows it, separately for desktops and for phones:

SettingValuesDefault
viewer_desktopviewer (the inline 3D viewer), qr (a QR code that opens the product on a phone), button (a button that opens it), hidden (nothing)viewer
viewer_mobileviewer, button, hidden - no qr, since a phone cannot scan its own screenviewer

Set them per product with PATCH /v1/products/{id} (products.update in both SDKs); the embed reads them from the product it loads. The element's desktop and mobile attributes override the stored setting on the page that sets them. The hosted Viewrium viewer page (the one the QR code opens) ignores both and always shows the viewer.

The View in your room button

The viewer shows one branded View in your room button, the same on every device, with a soft pulse: one gentle ring every few seconds while the button is on screen. It pauses while the viewer is scrolled out of view or the tab is in the background, and stays still if the shopper prefers reduced motion. On phones and tablets that can do AR, it starts AR directly. A computer cannot place a model in your room, so there it opens a short dialog: three steps, and a QR code that opens the product's Viewrium viewer page on the shopper's phone, where AR starts with one tap. A Copy link instead button copies the same link. The code is drawn in the page - nothing extra is downloaded - and the button and dialog are styled inside the component, so your page's CSS neither changes them nor is changed by them.

If AR cannot start on a shopper's device, the button goes away for the rest of the visit and the 3D view stays. The viewer reports it as an ar-status event with detail.status of failed; it is not an error.

Testing on a computer with your browser pretending to be a phone (Chrome DevTools' device toolbar, a user-agent switcher): the button behaves as on that phone and tries to open the phone's AR app. When nothing opens it, the viewer shows the QR dialog after a few seconds and keeps doing so for the rest of the visit. To see AR itself, open the page on a real phone.

Theme

theme sets the colors of the View in your room button, its dialog and the inline QR card:

<viewrium-viewer product-id="0b1e...-product-uuid" theme="dark"></viewrium-viewer>
ValueColors
auto (default)Light, or dark when the shopper's system is set to dark.
lightAlways light.
darkAlways dark.

Any other value is treated as auto. The QR code itself is always dark on white, in every theme, so every phone camera reads it. In the React wrapper, pass the same values as the theme prop.

Display modes

Choose what the component shows on computers and on phones separately, with the desktop and mobile attributes:

ModeOn a computerOn a phone or tablet
viewer (default)The 3D viewer with its View in your room button.The same.
qrThe QR card from the dialog - the three steps, the QR code and Copy link instead - in place of the viewer.Treated as button.
buttonOnly the View in your room button; it opens the QR dialog.Only the button; a tap goes straight into AR.
hiddenNothing.Nothing.
<!-- The 3D viewer on phones, the QR card on computers. -->
<viewrium-viewer product-id="0b1e...-product-uuid" desktop="qr" mobile="viewer"></viewrium-viewer>
  • "Mobile" means a device that can do AR - an iPhone or iPad with Quick Look, an Android phone with Scene Viewer, or a WebXR AR device. Everything else counts as a computer.
  • Which mode wins. The component's attribute, then the product's own display setting, then viewer. A value that is not one of the four is ignored, and the next one applies.
  • Nothing is loaded that is not shown. qr and hidden never download the model. In button mode the model is downloaded only when a shopper taps the button on a phone, and the button shows that it is busy for a moment on iPhone and iPad, where the model loads before AR opens. With the attribute set to hidden, the component makes no request at all.
  • hidden is not an error. The component sets hidden on itself as it does after a failure, but dispatches no error event. Instead it reports its mode in a viewrium-status event - detail.mode, and detail.reason of configured when hidden - and keeps it on its mode property. Every mode reports itself this way.
  • In qr and button modes the component takes its content's height, whatever height you gave it for the viewer.
  • Only viewer counts as a view in your analytics; AR sessions started from the button count as AR sessions as usual.

AR shows the real size

In AR the model always appears at its real-world size, on every device: Android's Scene Viewer, WebXR and iOS Quick Look all open it unscaled, and pinch-to-resize is off. This is not configurable - a shopper judging whether a sofa fits needs the sofa's true size.

Products marked wall-mounted (a mirror, a shelf, wall art) open on a wall in Android's Scene Viewer and in WebXR; everything else opens on the floor. The AR button becomes available once the viewer knows which, so a wall product never opens on the floor there. On iPhone and iPad, Quick Look places the model on whichever surface the shopper points at - a wall or the floor - upright either way. To place differently on one page, set ar-placement:

<viewrium-viewer product-id="0b1e...-product-uuid" ar-placement="wall"></viewrium-viewer>

The in-page 3D view looks the same either way; only AR changes.

Analytics come for free

The embed emits beacons automatically: a view when the viewer opens a product, ar_enter when a viewer starts an AR session, and ar_session_ended (with duration) when they leave it. These show up in your usage analytics - you do not need to wire anything up.

Traffic from your own organization - your team, your agency, Viewrium staff - is tagged internal and is excluded from GET /v1/usage unless you ask for include_internal. Testing your own embed while signed in therefore shows nothing by default.

If something goes wrong, the viewer hides

The viewer never shows an error message or an empty placeholder to your shoppers. If the product cannot be shown - it does not exist, is not published, or your key's allowed domains do not include the page - or the model cannot load, the component hides itself (it sets hidden), writes nothing to the browser console, and dispatches an error event whose detail.code says why:

detail.codeWhy
not-foundNo such product, or it is not published (or its model is not ready).
forbiddenThe key is not valid, or this page's domain is not in its allowed domains.
invalid-configA component attribute is missing or not valid (for example src, which is refused).
lookup-failed, metadata-failed, ticket-failed, load-failedOpening the product or loading its model failed (after the viewer has already retried).

Listen for it if you want your page to react - to show a still image in its place, say:

document.querySelector("viewrium-viewer").addEventListener("error", (event) => {
  console.log("Viewer hidden:", event.detail.code);
});

A component that failed before your listener was attached keeps the code on its errorCode property.

Using it in React / Next.js

<viewrium-viewer> is a standard custom element, so you can render the tag directly. Load the script once (for example in your root layout), then use the element in JSX. Because it is not a React component, pass attributes as plain strings/booleans and give it a size via style or CSS.

// Ensure the <script> tag from above is present in your document <head>.
export function ProductViewer({ productId }: { productId: string }) {
  return (
    <viewrium-viewer
      product-id={productId}
      style={{ width: "100%", height: 480 }}
    />
  );
}

In TypeScript you may need to declare the custom element on JSX's intrinsic elements so the compiler accepts the tag.

Requirements

  • The product must be published and its model ready. Anything else - unpublished, still generating, or a failed model - is refused to a pk_ key, and the viewer hides.
  • The page must serve over HTTPS for AR to work on mobile.
  • If your page sends a Content-Security-Policy, allow https://cdn.viewrium.com and https://www.viewrium.com in script-src, 'wasm-unsafe-eval' in script-src (the model decoder is WebAssembly), and https://api.viewrium.com and blob: in connect-src. Without 'wasm-unsafe-eval' the model cannot be decoded and the viewer hides; without blob: it still loads, with an extra request.

On this page