Embed the viewer

The Viewrium embed is a framework-free web component, <viewrium-model>, 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 ingredients

<!-- 1. Load model-viewer (the underlying renderer) and the Viewrium embed once per page. -->
<script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"></script>
<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-model model-id="0b1e...-product-uuid" style="width: 100%; height: 480px;"></viewrium-model>

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

model-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.

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-model> on the page uses it.

Publishable keys are safe to expose in the browser. They are origin-gated: a key only works from the domains on its project's allowed_domains, so add your site's domain there.
A pk_ key can only read published products 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.

model-viewer is loaded by your page

<viewrium-model> wraps Google's <model-viewer> and deliberately does not bundle it. Load model-viewer yourself from its CDN (the type="module" script above). Pin a specific version in production rather than tracking latest.

Component attributes

Attribute	Default	Description
`model-id`	(required)	The id of a published product whose model is ready.
`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.
`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.
`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-model
  model-id="0b1e...-product-uuid"
  auto-rotate
  ar="false"
  style="width: 100%; height: 480px;"
></viewrium-model>

Analytics come for free

The embed emits beacons automatically: a view when the model loads, 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.

Using it in React / Next.js

<viewrium-model> is a standard custom element, so you can render the tag directly. Load the two scripts 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 two <script> tags from above are present in your document <head>.
export function ProductViewer({ modelId }: { modelId: string }) {
  return (
    <viewrium-model
      model-id={modelId}
      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 - answers 404 to a pk_ key and will not render.
The page must serve over HTTPS for AR to work on mobile.