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-idwins. If a component carries bothcustom-idandproduct-id, it shows the product the custom id names.- Publishable keys only.
custom-idis for thepk_embed. Write the value as an HTML attribute:",&,<and>in it are escaped as",&,<and>(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.
Models are never a download link
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
| Attribute | Default | Description |
|---|---|---|
product-id | (required unless custom-id) | The id of a published product whose model is ready. |
custom-id | Your 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-controls | on | Let the user orbit/zoom. Set camera-controls="false" to disable. |
auto-rotate | off | Slowly spin the model. Set auto-rotate (or ="true") to enable. |
ar | on | Show the AR button (WebXR / Scene Viewer / Quick Look). Set ar="false" to hide. |
ar-placement | the product's | Where 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. |
poster | product thumbnail | Image shown while the model loads. Defaults to the product's thumbnail. |
alt | product title | Accessible description. Defaults to the product's title. |
desktop | the product's, else viewer | What a computer shows: viewer, qr, button or hidden. See Display modes. |
mobile | the product's, else viewer | What a phone or tablet that can do AR shows: viewer, button or hidden (qr means button there). |
theme | auto | The 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. |
pk | the script's key | This component's own publishable key, instead of the page-wide one. |
api-base | https://api.viewrium.com | Override 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:
| Setting | Values | Default |
|---|---|---|
viewer_desktop | viewer (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_mobile | viewer, button, hidden - no qr, since a phone cannot scan its own screen | viewer |
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>| Value | Colors |
|---|---|
auto (default) | Light, or dark when the shopper's system is set to dark. |
light | Always light. |
dark | Always 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:
| Mode | On a computer | On a phone or tablet |
|---|---|---|
viewer (default) | The 3D viewer with its View in your room button. | The same. |
qr | The QR card from the dialog - the three steps, the QR code and Copy link instead - in place of the viewer. | Treated as button. |
button | Only the View in your room button; it opens the QR dialog. | Only the button; a tap goes straight into AR. |
hidden | Nothing. | 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.
qrandhiddennever download the model. Inbuttonmode 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 tohidden, the component makes no request at all. hiddenis not an error. The component setshiddenon itself as it does after a failure, but dispatches noerrorevent. Instead it reports its mode in aviewrium-statusevent -detail.mode, anddetail.reasonofconfiguredwhen hidden - and keeps it on itsmodeproperty. Every mode reports itself this way.- In
qrandbuttonmodes the component takes its content's height, whatever height you gave it for the viewer. - Only
viewercounts 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.code | Why |
|---|---|
not-found | No such product, or it is not published (or its model is not ready). |
forbidden | The key is not valid, or this page's domain is not in its allowed domains. |
invalid-config | A component attribute is missing or not valid (for example src, which is refused). |
lookup-failed, metadata-failed, ticket-failed, load-failed | Opening 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.comandhttps://www.viewrium.cominscript-src,'wasm-unsafe-eval'inscript-src(the model decoder is WebAssembly), andhttps://api.viewrium.comandblob:inconnect-src. Without'wasm-unsafe-eval'the model cannot be decoded and the viewer hides; withoutblob:it still loads, with an extra request.