Skip to content

3D Embed API guide


The 3D Embed API enables you to create interactive, customizable 3d embeds in your website.

Getting started


npm install @archilogic/embed-api


// importing as ES module via npm
import ArchilogicEmbed from '@archilogic/embed-api'
// importing as ES module via public CDN
import ArchilogicEmbed from ''
// importing as UMD bundle via public CDN
;<script type="text/javascript" src=""></script>

Startup options

const viewer = new ArchilogicEmbed(document.body, {
  transparentBackground: true,
  presentationMode: PresentationMode.jumpToCameraDefault,
  minimap: false,
  showTitle: false,
  showLogo: false,
  lowResTexturesOnly: false, // prevent hi-res textures from loading, gives a loading-time performance boost at the cost of visual quality
  bookmarksActive: false, // control whether the bookmarks menu should be open or closed
  uiButtons: {
    birdMode: false,
    personMode: false,
    fullscreen: false,
    bookmarkStrip: false,
    share: false,
    help: false,
    presentation: false,
    exportImage: false
// await for the viewer embed to be ready
await viewer.viewerReadyPromise.catch(err => console.error('viewer couldnt be initialized', err))

Startup options correspond to different features in the Archilogic Viewer

Updating startup options

It's possible to update the startup options after initialization

// any value from the startup options can be updated
await viewer.set({
  minimap: true

// the passed update object will be deep merged with the current options
await viewer.set({
  showTitle: true,
  uiButtons: {
    birdMode: false

Presentation modes

  • PresentationMode.goToCameraDefault - transition to the default camera position
  • PresentationMode.goToFirstBookmark- transition to the first bookmark
  • PresentationMode.jumpToCameraDefault - go immediately to the default camera position
  • PresentationMode.jumpToFirstBookmark - go immediately to the first bookmark
  • PresentationMode.none - do nothing
  • PresentationMode.tourLoop - loop through the scene bookmarks
  • PresentationMode.tourOnce - loop through the scene bookmarks once
  • PresentationMode.tourOnceAndGoBack - loop through the scene bookmarks and return to the first bookmark

The presentation mode passed to the startup options controls how the scene behaves as it begins to load.

import { PresentationMode } from '@archilogic/embed-api'

// Update after a scene has loaded. This will not start a new presentation, but will take effect once a new scene is loaded or a presentation is started
await viewer.set({ presentationMode: PresentationMode.tourLoop })
// Explicitly start a presentation


The Embed API is promise-based; all actions return promises by default

Load scene


type loadScene = (sceneId: string, tokenOptions: TokenOptions) => Promise<void>

interface TokenOptions {
  // Create publishable access tokens at:
  publishableAccessToken?: string
  temporaryAccessToken?: TemporaryAccessToken

// Returned by Space API v2 create temporary access token.
export type TemporaryAccessToken = {
  authorization: string
  expiresAt: number

Example usage

const demoSceneId = 'a9aaafdf-d5b6-4b4a-82a0-9efb6d5b155a'
// Publishable tokens for the 3D Embed API should allow the `` domain.
const publishableAccessToken = 'c7ab862a-101d-4d2d-a360-7ed8d18ab7ee'
const tokenOptions = { publishableAccessToken }
await viewer.loadScene(demoSceneId, tokenOptions).catch(err => {
  // scene couldn't be loaded - it may be private or the ID couldn't be found
  console.error('There was an error loading the scene:', err)

Common navigation

Common navigation actions are exposed as methods. Promises will be resolved if a navigation transition is interupted by a user-action

// zoomExtents, goToBirdMode and goToPersonMode all accept an `{ animate }` property, which is true by default
await viewer.goToBirdMode({ animate: true })
await viewer.goToPersonMode({ animate: false })
await viewer.zoomExtents({ animate: true })

Bookmark navigation

// list the bookmarks of the currently loaded scene
const bookmarks = await viewer.listBookmarks()
const randomBookmark = bookmarks[Math.floor(Math.random() * bookmarks.length)]

await viewer.goToBookmark({ bookmarkId:, animate: true })

Zoom extents

viewer.zoomExtents accepts additional options for more control over the camera behavior.

zoomMin and zoomMax options can prevent the camera from travelling too close or too far from its target

await viewer.zoomExtents({ zoomMin: 10 }) // the camera will stay further than 10 meters (from the target)
await viewer.zoomExtents({ zoomMax: 30 }) // the camera will stay closer than 30 meters
await viewer.zoomExtents({ zoomMin: 20, zoomMin: 40 }) // the camera will stay within 20 and 40 meters

spaceId can be used to navigate to the extents of a specific space

// list the spaces of the currently loaded scene
const spaces = await viewer.listSpaces()
const randomSpace = spaces[Math.floor(Math.random() * spaces.length)]

await viewer.zoomExtents({ animate: false, spaceId: }) // zoom to the extents of "randomSpace"

Removing an instance

// will immediately stop the embedded viewer from receiving messages
// and clean up any existing event listeners


Supported events: sceneDefined, loadingStart, loadingDone

// listening for user input
const eventId = viewer.on('loadingDone', () => {
  // loading is done
  // remove the listener

Sync usage

Used syncronously, methods will cancel each other, this can be used to interupt and cancel actions when needed

// only `goToPersonMode` will have effect

// only scene4 will be loaded, the rest will be cancelled