Skip to main content

Getting started

Intro

Smplrspace lets developers add digital and interactive floor plans to their apps easily. Floor plans can be viewed in 2D or 3D. Data layers can be added on the floor plans.

To get started with Smplrspace, you will need an account. You can sign up from the website. All features come with a free tier so you can test things out and start building without friction (no credit card required).

Embed options

To embed our floor plans in your app, you can either use an iframe or our Javascript library, smplr.js. The iframe option is the easiest to use but provides limited features โ€” you can only display a floor plan. The Javascript library provides a full API that lets you control the rendering of the floor plans with custom color, behaviours and data layers.

Iframe embeds

You can find the code snippet for iframe embeds from the editor. Click on the name of the space (top left), then head to the "Services" tab in the right pane, and click "Get embed snippet". It will look something like this:

<iframe
title="Space name - Smplrspace"
src="https://smplr.me/xxxxxxx"
style="border: 0px none; width: 100%; height: 100%;"
scrolling="no"
allowfullscreen=""
webkitallowfullscreen=""
mozallowfullscreen=""
></iframe>

To control the size of the embed, put it inside a div element, the iframe will fill up the div over which you have full control.

You can also add position: absolute; in your iframe's style and then set position: relative; padding-bottom: 66%; on the parent div to get a responsive embed with a fixed ratio. Replace 66% by your preferred ratio.

Smplr.js embeds

To embed floor plans using our Javascript library, first load it from our CDN. You will need the JS script itself and the CSS stylesheets.

You should not try to use a copy of these files that you self host. Our frontend and backend resources need to be synced at the commit level to avoid data corruption, loading a copy might break your integration as you might not be using the latest version if we deploy a new version of the platform.

An npm package is on our roadmap but not ready yet due to blockers on the versioning side of things in our database. This remains a priority for us as we understand most engineering team prefer to include pinned versions of their dependencies in their own bundles. We will update our clients once this is available.

UMD bundle (single JS file)

The simplest way to get started is to use our Universal Module Definition (UMD) bundle which loads all the required frontend code at once. The disadvantage is a longer loading time on the first visit, subsequent visits will usually be cached. To use the UMD bundle, add these 2 lines to the <head> section of your app.

<script src="https://app.smplrspace.com/lib/smplr.js"></script>
<link href="https://app.smplrspace.com/lib/smplr.css" rel="stylesheet" />

To start the viewer for a space, you should append the following script at the end of the <body> section of your app.

<script>
const space = new smplr.Space({
spaceId: "fbc5617e-5a27-4138-851e-839446121b2e",
clientToken: "pub_eb760fee77634cdab2fe31146fc371c2",
containerId: "test",
});
space.startViewer({
preview: true,
onReady: () => console.log("Viewer is ready"),
onError: (error) => console.error("Could not start viewer", error),
});
</script>

ESM bundle (supports runtime tree shaking)

In many cases, it is advisable to lazy load third party code to ensure a faster initial load time. Smplr.js supports "tree shaking" at runtime through our ES Modules (ESM) bundle. The ESM bundle provides an entry point with the minimal code required to get started. It pulls additional resources from our CDN depending on the features you use. We code-split, bundle, and lazy-load to ensure your application loads as fast as possible. To use the ESM bundle, add our stylesheet in the <head> section of your app.

<link href="https://app.smplrspace.com/lib/smplr.css" rel="stylesheet" />

And then load the ESM bundle through a dynamic import in your code. Below is the equivalent to the example above.

<script>
import("https://app.smplrspace.com/lib/smplr.mjs").then((smplr) => {
const space = new smplr.Space({
spaceId: "fbc5617e-5a27-4138-851e-839446121b2e",
clientToken: "pub_eb760fee77634cdab2fe31146fc371c2",
containerId: "test",
});
space.startViewer({
preview: true,
onReady: () => console.log("Viewer is ready"),
onError: (error) => console.error("Could not start viewer", error),
});
});
</script>

Advanced usage

If you use a frontend framework like React, you can refer to the embedding spaces guide to learn more about loading smplr.js.

Preview images

Embeds are usually displayed with a static preview image and a button to initiate the interactive session. It works similarly to YouTube videos that require for the user to click "start" before loading the actual video. This is to ensure the page loads fast, and the interactive content is only loaded (and charged) for actual interactive sessions.

For a better experience, remember to generate a preview image once your space is ready. To do so, click on the name of the space (top left) in the editor, then head to the "Services" tab in the right pane, and click "Create preview image". A modal will open to let you position the viewer, you can change the size of the preview image you would like to save, and click "Snap" once ready. It will be saved to our servers and loaded automatically when required.

How to use this documentation

This documentation is built around two types of content: docs and examples. Both are accessible from the top navigation menu.

You are currently on the first page of the docs, the menu pane on the left (it's under the menu button on mobile) lets you navigate sections. It includes guides on how to use Smplrspace, as well as the API reference. Do reach out for anything that's not clear or could be improved, or directly click the "Edit this page" button at the bottom of each doc page to propose changes.

The examples provide code templates that you can reuse and combine to build your app, it's a convenient starting point to better understand how to build on top of Smplrspace. Should you want to share and propose an new example to be added, you can simply open a PR on this repo. The examples are in the src/pages/examples folder.