LiveModel Viewer SDK
The unified way to embed and optionally control LiveModel on any website.
A lightweight JavaScript wrapper for controlling a LiveModel iframe.
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.
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
| Parameter | Type | Description |
|---|---|---|
iframe |
string | Element | CSS selector string or an existing HTMLIFrameElement reference. |
options |
object | Configuration — see Options below. All optional. |
Creates a LiveModel iframe inside a container and returns its controller immediately. Commands called while the project URL or viewer is loading are queued.
Attaches V2 messaging and scrolling behavior to an existing iframe. Prefer embed() for new integrations.
| Parameter | Type | Description |
|---|---|---|
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.
| Option | Type | Default | Description |
|---|---|---|---|
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 )
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( )
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 )
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 )
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 )
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()
Ask for the current unit view state; it arrives as a unitViewState event with the same fields as unitViewChanged.
setControls( controls )
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.
| Group | Controls |
|---|---|
header | The building-level view toggle (building / floor plans / walk) |
unitView | The Building | 3D View | Walk Around pill in unit and walk mode |
autoTour | The Auto Tour / Stop pill (follows unitView unless set) |
fullscreen | The 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 )
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 )
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 )
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 )
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 )
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 )
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.
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? )
Enable or disable the idle camera autorotate. delayMs is the idle delay before spin starts, default 3000.
setOrbitToUnit( enabled, duration? )
When enabled, the camera eases toward the hovered unit. duration is the tween length in ms, default 500.
setZoomFactor( factor )
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? )
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? )
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 )
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()
Send a ping to measure round-trip latency. The viewer responds with a pong event containing a ts timestamp.
listMeshes()
Request all mesh names in the scene. The viewer responds with a meshList event.
listApartments()
Request all mapped apartment mesh names and their IDs. The viewer responds with an apartmentList event.
listBillboards()
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()
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.
| Event | Trigger | Key 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).
Parent → Viewer commands
| type | Required fields | Description |
|---|---|---|
NAVIGATE_BILLBOARD | billboard | Move camera to billboard |
NAVIGATE_BACK | — | Same as the viewer's back button / ESC (exits a userBillboard destination or visited billboard) |
SET_VIEW_MODE | mode | Switch between '3d' (building) and 'floorplans', same as the viewer's view toggle |
SELECT_FLOOR | floor | Pick the floor plan shown (1-based, or null to clear). Floor plans mode only |
SET_UNIT_VIEW | view | 'building' | 'unit' ('3d') | 'walk' | 'tour' | 'stopTour' — the viewer's unit buttons |
GET_UNIT_VIEW_STATE | — | Replies with UNIT_VIEW_STATE |
SET_CONTROLS | controls | true | false | null | { header, unitView, autoTour, fullscreen } |
HOVER_MESH | name, action | External hover start/end |
SET_TOOLTIP_MODE | mode | "external" | "internal" |
SET_HOVER_TOOLTIP | enabled | HOVER_MESH also opens the built-in unit tooltip |
SET_UNIT_TOOLTIP_MODE | mode | "external" | "internal" |
SET_BILLBOARD_MODE | mode | "full" | "no-tooltips" | "hidden" |
SET_SHEET_MODE | mode | "full" | "minimized" | "collapsed" | "hidden" |
SET_AUTOROTATE | enabled, delayMs | Idle camera spin |
SET_ORBIT_TO_UNIT | enabled, duration | Hover camera orbit |
SET_ZOOM_FACTOR | factor | Projection zoom multiplier for embed framing |
SET_ACTIVE_APARTMENT | name?, id?, action | Set, clear, or toggle the active apartment selection |
SET_MESH_COLORS | colors, opacity? | Hover colour overrides |
SET_MESH_VISIBILITY | meshes | Show/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.
| Param | SDK option | Effect |
|---|---|---|
showSheet=0 | sheetMode: "hidden" | No built-in apartment sheet |
sheetMinimized=1 | sheetMode: "minimized" | Built-in sheet starts collapsed |
showMainControls=0 | mainControls: false | No built-in view-toggle controls |
startBillboard=<id> | startBillboard | Open inside that userBillboard destination (no intro, no flight) |
Viewer → Parent messages
| type | Key fields | When |
|---|---|---|
READY | — | Viewer loaded, accepting commands |
APT_HOVERED | name, id, action | Canvas hover start/end |
APT_HOVER_MOVE | name, id, screen | Cursor position update (~30Hz) |
APT_CLICKED | name, id, row, screen | Unit click/tap |
APT_ACTIVE | name, id, row?, action | Selected apartment start/end |
WHEEL | deltaX, deltaY, deltaMode | Forwarded wheel input when viewer wheel zoom is disabled |
BILLBOARD_HOVERED | billboard, name, action, origin | Billboard hover start/end |
BILLBOARD_HOVER_MOVE | billboard, name, screen, origin | Billboard projected position (~30Hz) |
NAVIGATE_BILLBOARD | billboard, ok, origin? | ACK or canvas-initiated navigation |
USER_BILLBOARD_STATE | active, billboard, mode | userBillboard destination entered/exited, from any origin (canvas, ESC, SDK) |
VIEW_MODE_CHANGED | mode, floor, floors | View 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_STATE | view, isUnitView, walkAvailable, autoTourAvailable, buildingAvailable | Unit view state changed (any origin) / reply to GET_UNIT_VIEW_STATE |
SET_UNIT_VIEW | view, ok, pending?, error? | ACK / error |
SET_CONTROLS | controls, ok | ACK |
NAVIGATE_BACK | ok | ACK |
SET_VIEW_MODE | mode, ok, error? | ACK / error |
SELECT_FLOOR | floor, ok, error? | ACK / error |
SET_TOOLTIP_MODE | mode, ok | ACK |
SET_HOVER_TOOLTIP | enabled, ok | ACK |
SET_UNIT_TOOLTIP_MODE | mode, ok | ACK |
SET_BILLBOARD_MODE | mode, ok | ACK |
SET_SHEET_MODE | mode, ok | ACK |
SET_AUTOROTATE | enabled, delayMs, ok | ACK |
SET_ORBIT_TO_UNIT | enabled, duration, ok | ACK |
SET_ZOOM_FACTOR | factor, ok | ACK |
SET_ACTIVE_APARTMENT | action, id?, name?, ok, reason? | ACK / error |
SET_MESH_COLORS | ok | ACK |
SET_MESH_VISIBILITY | ok | ACK |
PONG | ts | Response to PING |
MESH_LIST | items | Response to LIST_MESHES |
APARTMENT_LIST | items | Response to LIST_APARTMENTS |
BILLBOARD_LIST | items | Response to LIST_BILLBOARDS |
Changelog
Unit view buttons and control visibility from the parent page.
- Added
setUnitView()withbackToBuilding(),showUnit3DView(),enterWalkMode(),startAutoTour(),stopAutoTour() - Added the
unitViewChangedevent andgetUnitViewState() - Added
setControls()and thecontrolsoption — show or hide the header, unit pill, Auto Tour and fullscreen controls separately mainControls: falseand the project's Show Main Controls setting now also hide the unit / walk / Auto Tour controls
Parent-page navigation for fully custom embed UIs.
- Added
navigateBack()and theuserBillboardStateevent - Added floor plans control:
setViewMode(),selectFloor()and theviewModeChangedevent - Added
startBillboardoption — open directly inside a userBillboard render - Added
hoverTooltipoption andsetHoverTooltip()—hoverMesh()can open the built-in unit tooltip - Added
mainControls: falseoption — hide the viewer's built-in view toggle - Idle autorotate no longer runs while inside a render, panorama or fixed-camera userBillboard
Runtime support for portal-authored userBillboards.
navigateBillboard(), billboard hover events, and billboard display modes now support userBillboards- Added
listBillboards()and thebillboardListevent - Authoring remains private to the portal and is not part of the public SDK
Built-in sheet suppression for custom parent-page lists.
- Added
sheetModeconstructor option andsetSheetMode() sheetMode: "hidden"suppresses the viewer's built-in apartment sheetsheetMode: "minimized"starts the built-in sheet collapsed;"collapsed"is accepted as an alias- Raw protocol support documented for
SET_SHEET_MODE
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
Added runtime userBillboard parity and listBillboards().
Built-in sheet suppression for custom parent-page lists.
- Added
sheetModeconstructor option andsetSheetMode() "collapsed"is accepted as an alias for"minimized"- Added
sheetModeChangedACK event - Raw protocol support documented for
SET_SHEET_MODE
Granular tooltip suppression for unit-only embeds.
- Added
unitTooltipModeconstructor option andsetUnitTooltipMode() - Added
unitTooltipModeChangedACK event - Unit tooltips can now be suppressed without suppressing billboard tooltips
Parent-driven apartment selection parity.
- Added
setActiveApartment()to SDK v1 - Added
activeApartmentChangedACK event - Raw protocol support documented for
SET_ACTIVE_APARTMENT
Embed framing controls.
- Added
zoomFactorconstructor option andsetZoomFactor() - Projection zoom uses camera zoom rather than moving the camera closer to the model
- Raw protocol now supports
SET_ZOOM_FACTORfor non-SDK embeds - Added
aptActiveevent for selected apartment start/end state
Embed-focused billboard controls and unified tooltip suppression.
- Added
billboardModeconstructor option andsetBillboardMode() billboardMode: "hidden"suppresses billboard visuals and billboard interaction for clean embedsbillboardMode: "no-tooltips"keeps billboards visible while suppressing billboard tooltip UItooltipMode: "external"now suppresses billboard tooltips as part of the shared tooltip layer
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