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 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-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 loads itself

<viewrium-model> 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 - any version - the embed uses yours and adds nothing. To pin the version yourself, load it before the embed script.

Component attributes

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 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({ 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.