LiveModel Viewer SDK

The unified way to embed and optionally control LiveModel on any website.

A lightweight JavaScript wrapper for controlling a LiveModel iframe.

v1.5.1 · ~4 KB · No dependencies · ES5 compatible
v2.3.0 No dependencies Automatic iframe setup Automatic page scrolling

V2 creates the LiveModel iframe, resolves the correct project URL, securely handles postMessage communication, and preserves parent-page scrolling. The returned controller is optional: basic integrations can embed LiveModel without using any control methods.

The LiveModel Viewer is embedded as an <iframe> and communicates with the parent page via the browser's postMessage API. The SDK wraps this protocol so you don't need to manage message formats or READY handshake timing yourself.

Without the SDK you must manage the iframe and browser integration yourself. With the SDK you get a supported embed path plus optional named methods and events.

If you only need one or two integrations, the DIY HTML examples show the raw protocol and may be simpler to adapt directly.

Installation

Include the SDK via a <script> tag. No build step required.

<!-- CDN -->
<script src="https://sdk.aa3d.ee/v1/livemodel-sdk.js"></script>

Or copy livemodel-sdk.js to your own server if you prefer self-hosting. The SDK is also compatible with CommonJS require() for bundled projects.

// CommonJS / bundler
const LiveModelViewer = require('./livemodel-sdk');

Quick Start

Add an <iframe> without a src attribute, then provide your complete LiveModel viewer URL through the SDK's src option. Replace the template values with the project name, project ID, access key, and language supplied for your project.

Add a container and call LiveModel.embed(). V2 resolves the project URL and creates the iframe automatically. The returned viewer controller is only needed if you want to use methods or events later.

<!-- 1. iframe placeholder -->
<iframe id="viewer" style="width:100%;height:600px;border:0" allowfullscreen></iframe>

<!-- 2. SDK -->
<script src="https://sdk.aa3d.ee/v1/livemodel-sdk.js"></script>
<script>
  const viewer = new LiveModelViewer('#viewer', {
    src: 'https://aa3d.ee/{projectName}/?projectId={projectId}&key=YOUR_KEY&lang=et',
    sheetMode: 'hidden' // optional: hide built-in sheet for custom parent-page lists
  });
</script>
<div id="livemodel"></div>

<script src="https://sdk.aa3d.ee/v2/livemodel-sdk.js"></script>
<script>
  const viewer = LiveModel.embed('#livemodel', {
    projectId: 133,
    key: 'YOUR_KEY',
    lang: 'et', // optional
    environment: 'development', // optional
    sheetMode: 'hidden' // optional: hide built-in sheet for custom parent-page lists
  });
</script>

Production is the default. While developing, set environment: "development" to load the project from dev.aa3d.ee. Omit this option to load production from aa3d.ee. The embed key is a browser-visible access key, not a secret server credential.

The parent website's origin must be enabled in the project's allowed-origin settings. Add both production and local development origins when applicable.

Parent Page Scrolling

Add this handler to every parent page that embeds LiveModel in an iframe when viewer wheel zoom is disabled. Chromium-based browsers can trap wheel input inside the iframe, preventing the surrounding page from scrolling while the pointer is over the viewer.

Place the following JavaScript in the parent website, after the iframe exists (for example in the site's main JavaScript file or just before the closing </body> tag):

const frame = document.querySelector('#viewer');

window.addEventListener('message', function (event) {
  const message = event.data;

  if (event.source !== frame.contentWindow) return;
  if (!message || message.source !== 'livemodel-viewer' || message.type !== 'WHEEL') return;

  window.scrollBy(message.deltaX || 0, message.deltaY || 0);
});

Replace #viewer if your iframe uses a different selector. The viewer sends WHEEL only when its own wheel zoom is disabled, so this does not interfere with configurations where the mouse wheel intentionally zooms the 3D view.

Do not add a click-to-interact shield. Avoid overlays or pointer-events: none on the iframe: they block immediate hover, click, and drag interaction, and make the first click appear unresponsive. Keep the iframe interactive and use the handler above to preserve normal parent-page scrolling.

No additional scrolling code is required. V2 automatically handles wheel messages from the viewer and scrolls the parent page when viewer wheel zoom is disabled.

Set forwardWheel: false only if your integration intentionally handles these messages itself. For layouts with a custom scrollable element, pass that element or its selector as scrollTarget.

Do not add a click-to-interact shield. Keep the iframe immediately interactive; V2 preserves page scrolling without overlays or pointer-events: none.

ConstructorEmbedding API

new LiveModelViewer(iframe, options) → LiveModelViewer
ParameterTypeDescription
iframe string | Element CSS selector string or an existing HTMLIFrameElement reference.
options object Configuration — see Options below. All optional.
LiveModel.embed(container, options) → Controller

Creates a LiveModel iframe inside a container and returns its controller immediately. Commands called while the project URL or viewer is loading are queued.

LiveModel.attach(iframe, options?) → Controller

Attaches V2 messaging and scrolling behavior to an existing iframe. Prefer embed() for new integrations.

ParameterTypeDescription
container string | Element CSS selector or container element that will receive the iframe.
options object Project, iframe, scrolling, and optional viewer configuration.

Options

Options passed to the constructor are automatically applied to the viewer as soon as it signals READY.

Pass project and embed options to LiveModel.embed(). Optional viewer configuration is applied automatically after READY.

OptionTypeDefaultDescription
projectId number | string required LiveModel project ID. Not required when an explicit src is supplied.
key string required Browser-visible project access key. Not required when an explicit src is supplied.
environment string "production" "production" or "development". Development loads from dev.aa3d.ee.
lang string optional Viewer language passed as the lang query parameter.
src string — Explicit complete viewer URL. In V2 this bypasses backend URL resolution.
origin string "*" postMessage target origin. Set to the viewer's exact origin for tighter security (e.g. "https://viewer.example.com").
width / height string "100%" / "600px" Dimensions applied to the generated iframe.
forwardWheel boolean true Automatically preserve parent-page scrolling over the iframe.
scrollTarget string | Element window Optional custom scroll container for forwarded wheel input.
billboardMode string "full" "full" keeps billboard visuals and interaction. "no-tooltips" keeps billboards visible/clickable but suppresses billboard tooltip UI. "hidden" suppresses billboard visuals and billboard interaction for clean embeds.
tooltipMode string "internal" "external" suppresses the viewer's built-in tooltip layer, including billboard tooltips, so you can render your own. "internal" keeps it.
unitTooltipMode string "internal" "external" suppresses only apartment/unit tooltips while leaving billboard tooltips available. tooltipMode: "external" still overrides this and suppresses both.
sheetMode string "full" "full" keeps the viewer's built-in apartment sheet. "minimized" starts it collapsed; "collapsed" is accepted as an alias. "hidden" suppresses the built-in sheet so a parent page can render its own list.
autorotate object — { enabled: true, delayMs: 3000 } — starts a slow camera spin after idle.
orbitToUnit object — { enabled: true, duration: 500 } — camera eases toward the hovered unit.
hoverTooltip boolean false true — hoverMesh() also opens the viewer's built-in unit tooltip (as the built-in sheet does). Leave off when the page draws its own tooltip from aptHoverMove. Also setHoverTooltip(enabled) / SET_HOVER_TOOLTIP.
mainControls boolean true false — hides all of the viewer's built-in controls (building view toggle, unit / walk pill, Auto Tour, fullscreen), for pages that provide their own navigation. Overrides the project setting; sent as the showMainControls=0 URL param.
controls boolean | object — Show or hide control groups separately once the viewer is ready: { header, unitView, autoTour, fullscreen }. Same as setControls().
startBillboard string — 'USER_BILLBOARD_9L8GA' — opens the viewer already inside that userBillboard destination (no intro zoom, no flight). Fires userBillboardState as normal; navigateBack() returns to the default view. Sent as the startBillboard URL param.
zoomFactor number 1 Projection zoom multiplier applied on top of the authored camera view. 1 = default, values above 1 zoom in, below 1 zoom out slightly.
meshColors object — Per-mesh hover colour overrides. See setMeshColors().
meshVisibility object — Per-mesh visibility map. See setMeshVisibility().

Methods

All methods return this for chaining. Commands sent before the viewer signals ready are queued and flushed automatically once it loads.

navigateBillboard( billboard )

navigateBillboard(billboard: string) → this

Move the camera to a legacy billboard or a camera-navigable USER_BILLBOARD_*. Link, text, enter-walk, and no-action userBillboards return ok: false; SDK navigation never triggers those actions.

viewer.navigateBillboard('BILLBOARD_000');           // overview
viewer.navigateBillboard('BILLBOARD_BUILDING_A');    // building A view
viewer.navigateBillboard('USER_BILLBOARD_K9X2Q');    // userBillboard camera action

navigateBack( )

navigateBack() → this

Same as the viewer's own back button / ESC: exits the current userBillboard destination (render, panorama, fixed camera) or visited billboard and returns to the default view. Listen to userBillboardState to keep your own "back" UI in sync.

viewer.navigateBack();

viewer.on('userBillboardState', (e) => {
  backButton.hidden = !e.active;   // show your own back button while inside a render
});

setViewMode( mode )

setViewMode(mode: "3d" | "floorplans") → this

Switch between the 3D building view and floor plans, same as the viewer's view toggle. Fires viewModeSet (ACK) and viewModeChanged.

viewer.setViewMode('floorplans');
viewer.setViewMode('3d');

selectFloor( floor )

selectFloor(floor: number | null) → this

Pick the floor plan shown (1-based), or null to clear. Floor plans mode only — call setViewMode("floorplans") first. The available floors arrive as floors on viewModeChanged.

viewer.setViewMode('floorplans').selectFloor(3);

setUnitView( view )

setUnitView(view: "building" | "unit" | "walk" | "tour" | "stopTour") → this

Press the viewer's unit buttons from the parent page: Building, 3D View ("unit", or "3d"), Walk Around, Auto Tour and Stop. Fires unitViewSet (ACK) and unitViewChanged. A request that isn't possible right now (no walk entry, no auto tour, not in a unit) comes back with ok: false and an error. Asking for another view while the auto tour plays stops the tour first (pending: true on the ACK).

Shortcuts: backToBuilding(), showUnit3DView(), enterWalkMode(), startAutoTour(), stopAutoTour().

let tourActive = false;
viewer.on('unitViewChanged', (s) => {
  // s.view: "building" | "unit" | "walk" | "ar" | "tour"
  tourActive = s.view === 'tour';
  walkBtn.hidden = !s.walkAvailable;
  tourBtn.hidden = !s.autoTourAvailable;
  tourBtn.textContent = tourActive ? 'Stop' : 'Auto Tour';
});

walkBtn.onclick = () => viewer.enterWalkMode();
tourBtn.onclick = () => tourActive ? viewer.stopAutoTour() : viewer.startAutoTour();
backBtn.onclick = () => viewer.backToBuilding();

getUnitViewState()

getUnitViewState() → this

Ask for the current unit view state; it arrives as a unitViewState event with the same fields as unitViewChanged.

setControls( controls )

setControls(controls: boolean | null | { header?, unitView?, autoTour?, fullscreen? }) → this

Show or hide the viewer's on-screen controls at runtime, separately from the project's Show Main Controls setting. true / false sets every group; an object sets only the groups it names. null (for all, or per group) goes back to the project setting. Fires controlsChanged with the active overrides.

GroupControls
headerThe building-level view toggle (building / floor plans / walk)
unitViewThe Building | 3D View | Walk Around pill in unit and walk mode
autoTourThe Auto Tour / Stop pill (follows unitView unless set)
fullscreenThe fullscreen button beside the unit pill (follows unitView unless set; only shown while the unit pill is)
viewer.setControls(false);                              // hide everything
viewer.setControls({ unitView: false, autoTour: true });  // own nav, keep the tour pill
viewer.setControls(null);                               // back to the project setting

hoverMesh( name, action )

hoverMesh(name: string, action: "start" | "end") → this

Trigger a hover highlight on a unit mesh from the parent page — for example when the user mouses over a row in your custom list. Mesh names are case-insensitive.

viewer.hoverMesh('building_a_unit_005', 'start');
viewer.hoverMesh('building_a_unit_005', 'end');

setTooltipMode( mode )

setTooltipMode(mode: "external" | "internal") → this

Switch between the viewer's built-in tooltip layer ("internal") and suppressed mode where you render your own ("external"). In external mode the viewer suppresses both unit and billboard tooltips.

setHoverTooltip( enabled )

setHoverTooltip(enabled: boolean) → this

When true, hoverMesh() also opens the viewer's built-in unit tooltip, as the built-in sheet does. Off by default, so pages that draw their own tooltip from aptHoverMove are unaffected. Same as the hoverTooltip option. Fires hoverTooltipChanged.

setUnitTooltipMode( mode )

setUnitTooltipMode(mode: "external" | "internal") → this

Suppress only the built-in apartment/unit tooltips while leaving billboard tooltips available. This is useful when you want custom unit tooltips but still want the viewer's own billboard tooltip UI. If setTooltipMode("external") is also active, it still suppresses both.

setBillboardMode( mode )

setBillboardMode(mode: "full" | "no-tooltips" | "hidden") → this

Control legacy billboards and userBillboards together. "full" keeps the default viewer behaviour. "no-tooltips" keeps billboards visible and clickable but suppresses billboard tooltip UI. "hidden" suppresses billboard visuals and billboard interaction entirely.

setSheetMode( mode )

setSheetMode(mode: "full" | "minimized" | "collapsed" | "hidden") → this

Control the viewer's built-in apartment sheet. Use "hidden" when your embed renders its own parent-page sheet/list and you want the viewer canvas to occupy the full iframe. Use "minimized" or "collapsed" to keep the built-in sheet available but collapsed.

// Constructor option
const viewer = LiveModel.attach('#viewer', {
  sheetMode: 'hidden'
});

// Runtime change
viewer.setSheetMode('hidden');

For raw iframe integrations without the SDK, append showSheet=0 to the iframe URL for early suppression, then send SET_SHEET_MODE after READY. To start collapsed instead, use sheetMinimized=1 or setSheetMode("minimized"); setSheetMode("collapsed") is equivalent.

This control requires a viewer build that supports showSheet URL overrides and SET_SHEET_MODE. Updating only sdk.aa3d.ee is not enough if the embedded viewer on aa3d.ee is still an older build.

setAutorotate( enabled, delayMs? )

setAutorotate(enabled: boolean, delayMs?: number) → this

Enable or disable the idle camera autorotate. delayMs is the idle delay before spin starts, default 3000.

setOrbitToUnit( enabled, duration? )

setOrbitToUnit(enabled: boolean, duration?: number) → this

When enabled, the camera eases toward the hovered unit. duration is the tween length in ms, default 500.

setZoomFactor( factor )

setZoomFactor(factor: number) → this

Apply a projection zoom multiplier without moving the camera. 1 keeps the default framing, values above 1 zoom in, and values below 1 zoom out. Recommended working range for embeds is roughly 0.75 to 2.

viewer.setZoomFactor(1.15);  // zoom in a little
viewer.setZoomFactor(0.9);   // zoom out a little

setActiveApartment( nameOrId, action?, useId? )

setActiveApartment(nameOrId: string, action?: "start" | "end" | "toggle", useId?: boolean) → this

Set or clear the active apartment selection from the parent page. This drives the same locked selection state as a canvas click, so successful changes emit aptActive.

// Select by mesh name
viewer.setActiveApartment('korter_4a_22', 'start');

// Toggle by mesh name
viewer.setActiveApartment('korter_4a_22', 'toggle');

// Clear by apartment id
viewer.setActiveApartment('3DV5H', 'end', true);

setMeshColors( colors, opacity? )

setMeshColors(colors: object, opacity?: number) → this

Override the hover highlight colour for specific meshes. Colours only appear when a mesh is hovered — they do not permanently tint meshes.

Each entry can be a hex string (uses opacity fallback) or an object with per-mesh opacity:

// All listed meshes → red at opacity 1 when hovered
viewer.setMeshColors({
  'building_a_unit_001': '#ef4444',
  'building_a_unit_002': '#ef4444',
}, 1.0);

// Per-mesh colour AND opacity
viewer.setMeshColors({
  'building_a_unit_001': { color: '#ef4444', opacity: 1.0 },
  'building_b_unit_003': { color: '#22c55e', opacity: 0.7 },
});

setMeshVisibility( meshes )

setMeshVisibility(meshes: { [name]: boolean }) → this

Show or completely disable specific unit hover meshes. Hidden meshes cannot be hovered, clicked, or highlighted — they are fully removed from interaction.

viewer.setMeshVisibility({
  'building_a_unit_045': false,  // sold out — remove from interaction
  'building_b_unit_012': false,
});

ping()

ping() → this

Send a ping to measure round-trip latency. The viewer responds with a pong event containing a ts timestamp.

listMeshes()

listMeshes() → this

Request all mesh names in the scene. The viewer responds with a meshList event.

listApartments()

listApartments() → this

Request all mapped apartment mesh names and their IDs. The viewer responds with an apartmentList event.

listBillboards()

listBillboards() → this

Request legacy billboard and userBillboard metadata. The billboardList response includes each item's kind, visibility, action type, and SDK navigability. Invisible userBillboards remain listed for camera control by permanent ID.

destroy()

destroy() → void

Remove the message listener and clean up. Call this if you remove the iframe from the DOM.

Events

Subscribe with viewer.on(eventName, callback). The callback receives a single data object.

EventTriggerKey data fields
ready Viewer finished loading and is accepting commands. { version }
error Project URL resolution or iframe setup failed. { error, message }
wheel A forwarded viewer wheel message was handled. { deltaX, deltaY, deltaMode }
aptHovered A unit mesh is hovered or un-hovered in the canvas. { name, id, action: "start"|"end" }
aptHoverMove The cursor moves over a hovered unit (throttled ~30Hz). { name, id, screen: { x, y } }
aptClicked A unit mesh is clicked/tapped in the canvas. { name, id, row, screen: { x, y } }
aptActive The selected/locked apartment changes state. { name, id, row?, action: "start"|"end" }
billboardHovered A billboard mesh is hovered or un-hovered in the canvas. { billboard, name, action: "start"|"end", origin: "canvas" }
buildingHovered A BILLBOARD_BUILDING_* hover starts or ends (alias of billboardHovered for building billboards only). { billboard, name, action: "start"|"end", origin: "canvas" }
billboardHoverMove Projected screen position for a hovered billboard (throttled ~30Hz). { billboard, name, screen: { x, y }, origin: "canvas" }
buildingHoverMove Projected screen position for a hovered BILLBOARD_BUILDING_* (alias of billboardHoverMove for building billboards only). { billboard, name, screen: { x, y }, origin: "canvas" }
navigateBillboard ACK after a navigateBillboard() call, or viewer-initiated navigation. { billboard, ok, origin? }
navigateBack ACK after navigateBack(). { ok }
hoverTooltipChanged ACK after setHoverTooltip() or the hoverTooltip option. { ok, enabled }
userBillboardState A userBillboard destination was entered or exited (canvas click, ESC, back button, or SDK). { active, billboard, mode }
viewModeChanged Building / floor plans mode or the selected floor changed (toolbar, ESC, back button, or setViewMode() / selectFloor()). { mode: "3d" | "floorplans" | "walk", floor, floors }
viewModeSet / floorSelected ACK after setViewMode() / selectFloor(). { ok, mode } / { ok, floor }, plus error when ok is false
unitViewChanged Building / unit 3D view / walk / AR / auto tour state changed, from any origin (viewer buttons, ESC, SDK). Also unitViewState, the reply to getUnitViewState(). { view: "building" | "unit" | "walk" | "ar" | "tour", isUnitView, walkAvailable, autoTourAvailable, buildingAvailable }
unitViewSet / controlsChanged ACK after setUnitView() (and its shortcuts) / setControls(). { ok, view, pending?, error? } / { ok, controls }
cameraArrived A billboard camera move finished (useful for chaining moves). {}
buildingSelected User clicked a building mesh in the 3D canvas (fires alongside navigateBillboard). { billboard, origin: "canvas" }
tooltipModeChanged ACK after setTooltipMode(). { mode, ok }
unitTooltipModeChanged ACK after setUnitTooltipMode(). { mode, ok }
billboardModeChanged ACK after setBillboardMode(). { mode, ok }
sheetModeChanged ACK after setSheetMode(). { mode, ok }
autorotateChanged ACK after setAutorotate(). { enabled, delayMs, ok }
orbitToUnitChanged ACK after setOrbitToUnit(). { enabled, duration, ok }
zoomFactorChanged ACK after setZoomFactor(). { factor, ok }
activeApartmentChanged ACK after setActiveApartment(). { action, id?, name?, ok, reason? }
meshColorsApplied ACK after setMeshColors(). { ok }
meshVisibilityApplied ACK after setMeshVisibility(). { ok }
pong Response to ping(). { ts }
meshList Response to listMeshes(). { items: string[] }
apartmentList Response to listApartments(). { items: { name, id }[] }
billboardList Response to listBillboards(). { items: { id, displayName, kind, actionType?, navigable, visible }[] }

Example — Custom Tooltip

Suppress the viewer's tooltip layer and render your own, positioned at the cursor. In tooltipMode: "external" the viewer suppresses both unit and billboard tooltips.

To keep billboard meshes interactive while using your own tooltip UI, leave billboardMode at "full". Use "no-tooltips" only when you want billboard tooltip UI suppressed without switching the whole viewer to external tooltip mode.

If you only want to replace apartment/unit tooltips and keep the viewer's billboard tooltip UI, use unitTooltipMode: "external" instead of tooltipMode: "external".

viewer.setTooltipMode('external');

const tip = document.getElementById('my-tooltip');

viewer.on('aptHovered', function (data) {
  if (data.action === 'end') {
    tip.style.display = 'none';
  }
});

viewer.on('aptHoverMove', function (data) {
  const frame = document.getElementById('viewer');const frame = viewer.iframe;
  const rect  = frame.getBoundingClientRect();
  tip.style.display = 'block';
  tip.style.left    = (rect.left + data.screen.x + 12) + 'px';
  tip.style.top     = (rect.top  + data.screen.y - 8)  + 'px';
  tip.textContent   = data.name;
});

The same pattern also works for billboard meshes. Listen to billboardHovered / billboardHoverMove for general billboards, or buildingHovered / buildingHoverMove if you only care about BILLBOARD_BUILDING_* anchors.

const billboardTip = document.getElementById('my-billboard-tooltip');

viewer.on('billboardHovered', function (data) {
  if (data.action === 'end') {
    billboardTip.style.display = 'none';
  }
});

viewer.on('billboardHoverMove', function (data) {
  const frame = document.getElementById('viewer');const frame = viewer.iframe;
  const rect  = frame.getBoundingClientRect();
  billboardTip.style.display = 'block';
  billboardTip.style.left    = (rect.left + data.screen.x) + 'px';
  billboardTip.style.top     = (rect.top  + data.screen.y) + 'px';
  billboardTip.textContent   = data.billboard;
});

Example — Building Navigation

Sync a custom navigation UI with the viewer. Building hovers can preview your UI; building clicks select it; UI button clicks update the camera.

const BUILDINGS = {
  A: 'BILLBOARD_BUILDING_A',
  B: 'BILLBOARD_BUILDING_B',
  C: 'BILLBOARD_BUILDING_C',
};

// Canvas hover -> preview parent UI
viewer.on('buildingHovered', function (data) {
  const key = Object.keys(BUILDINGS).find(function(k) {
    return BUILDINGS[k] === data.billboard;
  });
  if (key && data.action === 'start') previewTab(key);
  if (data.action === 'end') clearPreviewTab();
});

// Canvas hover position -> move parent tooltip
viewer.on('buildingHoverMove', function (data) {
  const key = Object.keys(BUILDINGS).find(function(k) {
    return BUILDINGS[k] === data.billboard;
  });
  if (key) moveBuildingTooltip(key, data.screen);
});

// Canvas click -> update parent UI (no feedback loop)
viewer.on('buildingSelected', function (data) {
  const key = Object.keys(BUILDINGS).find(function(k) {
    return BUILDINGS[k] === data.billboard;
  });
  if (key) setActiveTab(key);
});

// UI button → navigate viewer camera
document.getElementById('btn-building-a').addEventListener('click', function () {
  viewer.navigateBillboard(BUILDINGS.A);
  setActiveTab('A');
});

Example — Mesh Colors from Your Data

Drive hover colours from your own availability data — no dependency on the viewer's internal status colours.

// Your data: { meshName → status }
const availability = {
  'building_a_unit_001': 'available',
  'building_a_unit_002': 'sold',
  'building_a_unit_003': 'reserved',
};

const STATUS_COLORS = {
  available: '#22c55e',
  sold:      '#ef4444',
  reserved: '#eab308',
};

const colors = {};
Object.entries(availability).forEach(function ([mesh, status]) {
  colors[mesh] = STATUS_COLORS[status] || '#3b82f6';
});

viewer.setMeshColors(colors);

// Or update later (e.g. after fetching fresh data)
viewer.on('ready', function () {
  viewer.setMeshVisibility({ 'building_a_unit_002': false }); // sold — remove entirely
});

Example — Desktop vs Mobile Tooltip

On desktop, show a floating tooltip that follows the cursor. On mobile (touch devices), show a fixed bottom panel on tap instead.

const isMobile = window.matchMedia('(hover: none)').matches;

viewer.setTooltipMode('external');

// Desktop: floating tooltip following cursor
if (!isMobile) {
  viewer.on('aptHoverMove', function (data) {
    showFloatingTip(data.name, data.screen.x, data.screen.y);
  });
  viewer.on('aptHovered', function (data) {
    if (data.action === 'end') hideFloatingTip();
  });
}

// Mobile: bottom panel on tap
viewer.on('aptClicked', function (data) {
  if (isMobile) {
    showBottomSheet(data.id, data.row);
  } else {
    toggleLockedTooltip(data.name);
  }
});

Raw Protocol Reference

The SDK sends and receives standard postMessage messages. All messages use source: "livemodel-parent" (parent → viewer) or source: "livemodel-viewer" (viewer → parent).

You don't need this section when using the SDK. It's here for debugging or if you're building a custom integration without the SDK.

Parent → Viewer commands

typeRequired fieldsDescription
NAVIGATE_BILLBOARDbillboardMove camera to billboard
NAVIGATE_BACK—Same as the viewer's back button / ESC (exits a userBillboard destination or visited billboard)
SET_VIEW_MODEmodeSwitch between '3d' (building) and 'floorplans', same as the viewer's view toggle
SELECT_FLOORfloorPick the floor plan shown (1-based, or null to clear). Floor plans mode only
SET_UNIT_VIEWview'building' | 'unit' ('3d') | 'walk' | 'tour' | 'stopTour' — the viewer's unit buttons
GET_UNIT_VIEW_STATE—Replies with UNIT_VIEW_STATE
SET_CONTROLScontrolstrue | false | null | { header, unitView, autoTour, fullscreen }
HOVER_MESHname, actionExternal hover start/end
SET_TOOLTIP_MODEmode"external" | "internal"
SET_HOVER_TOOLTIPenabledHOVER_MESH also opens the built-in unit tooltip
SET_UNIT_TOOLTIP_MODEmode"external" | "internal"
SET_BILLBOARD_MODEmode"full" | "no-tooltips" | "hidden"
SET_SHEET_MODEmode"full" | "minimized" | "collapsed" | "hidden"
SET_AUTOROTATEenabled, delayMsIdle camera spin
SET_ORBIT_TO_UNITenabled, durationHover camera orbit
SET_ZOOM_FACTORfactorProjection zoom multiplier for embed framing
SET_ACTIVE_APARTMENTname?, id?, actionSet, clear, or toggle the active apartment selection
SET_MESH_COLORScolors, opacity?Hover colour overrides
SET_MESH_VISIBILITYmeshesShow/hide meshes
PING—Latency check
LIST_MESHES—Get all mesh names
LIST_APARTMENTS—Get mapped apartments
LIST_BILLBOARDS—Get legacy billboard and userBillboard metadata

Iframe URL parameters

Read once when the viewer loads, so they take effect before the first frame. The SDK sets these from the matching options.

ParamSDK optionEffect
showSheet=0sheetMode: "hidden"No built-in apartment sheet
sheetMinimized=1sheetMode: "minimized"Built-in sheet starts collapsed
showMainControls=0mainControls: falseNo built-in view-toggle controls
startBillboard=<id>startBillboardOpen inside that userBillboard destination (no intro, no flight)

Viewer → Parent messages

typeKey fieldsWhen
READY—Viewer loaded, accepting commands
APT_HOVEREDname, id, actionCanvas hover start/end
APT_HOVER_MOVEname, id, screenCursor position update (~30Hz)
APT_CLICKEDname, id, row, screenUnit click/tap
APT_ACTIVEname, id, row?, actionSelected apartment start/end
WHEELdeltaX, deltaY, deltaModeForwarded wheel input when viewer wheel zoom is disabled
BILLBOARD_HOVEREDbillboard, name, action, originBillboard hover start/end
BILLBOARD_HOVER_MOVEbillboard, name, screen, originBillboard projected position (~30Hz)
NAVIGATE_BILLBOARDbillboard, ok, origin?ACK or canvas-initiated navigation
USER_BILLBOARD_STATEactive, billboard, modeuserBillboard destination entered/exited, from any origin (canvas, ESC, SDK)
VIEW_MODE_CHANGEDmode, floor, floorsView mode or selected floor changed, from any origin (toolbar, ESC, back button, SDK)
CAMERA_ARRIVED—A billboard camera move finished
UNIT_VIEW_CHANGED / UNIT_VIEW_STATEview, isUnitView, walkAvailable, autoTourAvailable, buildingAvailableUnit view state changed (any origin) / reply to GET_UNIT_VIEW_STATE
SET_UNIT_VIEWview, ok, pending?, error?ACK / error
SET_CONTROLScontrols, okACK
NAVIGATE_BACKokACK
SET_VIEW_MODEmode, ok, error?ACK / error
SELECT_FLOORfloor, ok, error?ACK / error
SET_TOOLTIP_MODEmode, okACK
SET_HOVER_TOOLTIPenabled, okACK
SET_UNIT_TOOLTIP_MODEmode, okACK
SET_BILLBOARD_MODEmode, okACK
SET_SHEET_MODEmode, okACK
SET_AUTOROTATEenabled, delayMs, okACK
SET_ORBIT_TO_UNITenabled, duration, okACK
SET_ZOOM_FACTORfactor, okACK
SET_ACTIVE_APARTMENTaction, id?, name?, ok, reason?ACK / error
SET_MESH_COLORSokACK
SET_MESH_VISIBILITYokACK
PONGtsResponse to PING
MESH_LISTitemsResponse to LIST_MESHES
APARTMENT_LISTitemsResponse to LIST_APARTMENTS
BILLBOARD_LISTitemsResponse to LIST_BILLBOARDS

Changelog

v2.3.0 2026-10-12

Unit view buttons and control visibility from the parent page.

  • Added setUnitView() with backToBuilding(), showUnit3DView(), enterWalkMode(), startAutoTour(), stopAutoTour()
  • Added the unitViewChanged event and getUnitViewState()
  • Added setControls() and the controls option — show or hide the header, unit pill, Auto Tour and fullscreen controls separately
  • mainControls: false and the project's Show Main Controls setting now also hide the unit / walk / Auto Tour controls
v2.2.0 2026-10-12

Parent-page navigation for fully custom embed UIs.

  • Added navigateBack() and the userBillboardState event
  • Added floor plans control: setViewMode(), selectFloor() and the viewModeChanged event
  • Added startBillboard option — open directly inside a userBillboard render
  • Added hoverTooltip option and setHoverTooltip() — hoverMesh() can open the built-in unit tooltip
  • Added mainControls: false option — hide the viewer's built-in view toggle
  • Idle autorotate no longer runs while inside a render, panorama or fixed-camera userBillboard
v2.1.0 2026-08-19

Runtime support for portal-authored userBillboards.

  • navigateBillboard(), billboard hover events, and billboard display modes now support userBillboards
  • Added listBillboards() and the billboardList event
  • Authoring remains private to the portal and is not part of the public SDK
v2.0.2 2026-07-07

Built-in sheet suppression for custom parent-page lists.

  • Added sheetMode constructor option and setSheetMode()
  • sheetMode: "hidden" suppresses the viewer's built-in apartment sheet
  • sheetMode: "minimized" starts the built-in sheet collapsed; "collapsed" is accepted as an alias
  • Raw protocol support documented for SET_SHEET_MODE
v2.0.0 2026-06-24

Unified embedding and controller API.

  • Added LiveModel.embed() with automatic iframe creation and project URL resolution
  • Added production and development environment selection
  • Added automatic parent-page wheel scrolling
  • Added strict iframe window and origin validation for incoming messages
  • Added LiveModel.attach() for existing iframe integrations
v1.6.0 2026-08-19

Added runtime userBillboard parity and listBillboards().

v1.5.1 2026-07-07

Built-in sheet suppression for custom parent-page lists.

  • Added sheetMode constructor option and setSheetMode()
  • "collapsed" is accepted as an alias for "minimized"
  • Added sheetModeChanged ACK event
  • Raw protocol support documented for SET_SHEET_MODE
v1.4 2026-05-14

Granular tooltip suppression for unit-only embeds.

  • Added unitTooltipMode constructor option and setUnitTooltipMode()
  • Added unitTooltipModeChanged ACK event
  • Unit tooltips can now be suppressed without suppressing billboard tooltips
v1.3 2026-05-04

Parent-driven apartment selection parity.

  • Added setActiveApartment() to SDK v1
  • Added activeApartmentChanged ACK event
  • Raw protocol support documented for SET_ACTIVE_APARTMENT
v1.2 2026-05-04

Embed framing controls.

  • Added zoomFactor constructor option and setZoomFactor()
  • Projection zoom uses camera zoom rather than moving the camera closer to the model
  • Raw protocol now supports SET_ZOOM_FACTOR for non-SDK embeds
  • Added aptActive event for selected apartment start/end state
v1.1 2026-04-23

Embed-focused billboard controls and unified tooltip suppression.

  • Added billboardMode constructor option and setBillboardMode()
  • billboardMode: "hidden" suppresses billboard visuals and billboard interaction for clean embeds
  • billboardMode: "no-tooltips" keeps billboards visible while suppressing billboard tooltip UI
  • tooltipMode: "external" now suppresses billboard tooltips as part of the shared tooltip layer
v1.0 2026-03-27

Initial release.

  • Constructor with auto-config on READY
  • Command queue for pre-READY calls
  • navigateBillboard, hoverMesh, setTooltipMode, setAutorotate, setOrbitToUnit
  • setMeshColors — per-mesh hover colour overrides
  • setMeshVisibility — disable meshes from interaction
  • buildingSelected event for canvas-initiated building navigation
  • ping / listMeshes / listApartments utilities
  • destroy() for cleanup