3D Embed API guide

Overview

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

Getting started

Installation

npm install @archilogic/embed-api

Usage

// importing as ES module via npm
import ArchilogicEmbed from '@archilogic/embed-api'
// importing as ES module via public CDN
import ArchilogicEmbed from 'https://unpkg.com/@archilogic/embed-api?module'
// importing as UMD bundle via public CDN
;<script type="text/javascript" src="https://unpkg.com/@archilogic/embed-api"></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
viewer.startPresentation()

Methods

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

Load scene

Interface

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

interface TokenOptions {
  // Create publishable access tokens at:
  // https://app.archilogic.com/organization/settings/access-tokens
  publishableAccessToken?: string
  temporaryAccessToken?: TemporaryAccessToken
}

// Returned by Space API v2 create temporary access token.
// https://developers.archilogic.com/space-api/v2/introduction.html#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 `viewer.archilogic.com` 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: randomBookmark.id, 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: randomSpace.id }) // 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
viewer.destroy()

Events

Supported events: sceneDefined, loadingStart, loadingDone

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

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
viewer.goToBirdMode()
viewer.goToPersonMode()

// only scene4 will be loaded, the rest will be cancelled
viewer.loadScene(scene1)
viewer.loadScene(scene2)
viewer.loadScene(scene3)
viewer.loadScene(scene4)