API
- 🔧 GitHub Repository: github.com/orbitalvision/ov25-ui - Forks welcome!
1. Overview
The Orbital Vision 3D Configurator is a self-contained application embedded inside an <iframe>. The parent application can communicate with it to:
- Load or switch between products or ranges.
- Select product options (e.g., fabrics, legs, sizes).
- View or hide product dimensions.
- Enter AR or VR modes (where supported).
- Listen for updates (e.g., current price, SKU, etc.).
Communication is done via the standard Window.postMessage API.
2. iFrame URL Requirements
When embedding the configurator, you must include:
- Your API key, which authenticates the request.
You can create a new API key in your dashboard at app.orbital.vision/api-keys. Please select the Product Configurator Access type from the dropdown list.
- Either a product ID or a range ID.
You can find your desired product ID or range ID by going to app.orbital.vision/products. On the lefthand side of the table there is an ID field for both ranges and products.
This requirement gives two possible URL structures:
- Product-Based
- Structure: https://configurator.orbital.vision***/[API_KEY]/[PRODUCT_ID]***
- Example:
https://configurator.orbital.vision/abc123/45
- Range-Based
- Structure: https://configurator.orbital.vision***/[API_KEY]/***range***/[RANGE_ID]***
- Example:
https://configurator.orbital.vision/abc123/range/99
- Authorised Domain
- The site where the iframe is hosted must be one of your authorised domains listed on your dashboard at app.orbital.vision/authorized-domains
The [API_KEY] ensures that only authorised integrations can load the 3D environment. Without it, the server hosting the configurator will reject the request.
Required <iframe> Attributes
To enable a full range of features—particularly WebXR (AR/VR) support—the following allow attributes are required:
accelerometer: Allows the 3D configurator to access device orientation data, used for augmented reality interactions on mobile.autoplay: Permits automatic playback of any embedded 3D or media assets without explicit user interaction.clipboard-write: Allows copying data to the user's clipboard. This may be used for future feature support (for example, quickly sharing config data).encrypted-media: Enables playback of protected or DRM-encrypted content if the configurator requires secure media streams.gyroscope: Grants access to motion sensors needed for advanced AR or VR features on mobile devices.picture-in-picture: Allows the configurator to enter picture-in-picture mode in future updates.xr-spatial-tracking: Essential for AR or VR sessions under WebXR, enabling correct spatial tracking of the virtual object in a real-world environment.fullscreen: Permits the configurator to be viewed in full screen, improving the immersive 3D or AR/VR experience.
3. Initial Handshake: Messages from the Configurator
When the configurator finishes loading, it will send messages to the parent window detailing its initial state. These messages will then resend any time the data in the previous messages becomes stale.
ALL_PRODUCTS
Description:
A complete list of products the configurator can display at load time, this will have a single product only if you did not use the range path.
Example:
priceandpricingare always in the lowest form of that currency, for example in pence (e.g.,150000= £1,500.00).
RANGE
Description:
Information about the range currently in use (if you're loading a range-based URL).
Example:
idmatches the[RANGE_ID]passed in the URL.
CURRENT_PRODUCT_ID
Description:
Tells you which specific product is currently loaded by the configurator.
Example:
payloadis a simple number in this case (the product ID).
CONFIGURATOR_STATE
Description:
The complete structure of the configurator, detailing available options, groups, selections, and the user's current selections.
Quite often the group name will be 'Default Group' or 'Default' if there is only one group, so when designing your UI we recommend hiding groups and just showing the selections directly nested within their option when there exists only a single group.
Example:
- Each selection comes with a thumbnail, and mini thumbnails. The mini thumnails are sized 50px, 150px and 250px (small, medium large)
- They are all webp which as you can see from https://caniuse.com/webp is supported in nearly all browsers. In 2025 it is completely safe to use and we recommend that you use these performant mini thumbnails. If you do not want to use them, there is also the original thumbnail jpg for you to use with an image service/cdn.
- Each option can contain one or more groups. Each group can contain one or more selections.
- selectedSelections tells you exactly which
selectionIdthe user has chosen for each option/group.
CURRENT_PRICE
Description:
The calculated price based on the user's current selections.
Example:
formattedPriceis a user-facing string (localized).totalPriceis an integer in the lowest form of that currency (103600 = £1,036.00).subtotalis the price before any discounts are applied (129500 = £1,295.00).formattedSubtotalis the formatted string representation of the subtotal.discountcontains the discount information withamount(in lowest currency form),formattedAmount(localized string), andpercentage(discount percentage).priceBreakdownis a breakdown of the total price, including the price of the range, product, and any selections such as fabric or legs. This will sum to subtotal.
CURRENT_SKU
Description:
The SKU representing the current product configuration. Helpful for backend or e-commerce tracking.
Example:
skuStringis a combination of selected options/selections.skuMapshows how each option name maps to the underlying SKU.
AR_PREVIEW_LINK
Description:
A direct link to an AR experience, used when the current device is not appropriate.
Example:
- It is recommended that you display this link with a QR code to scan from a mobile device.
- On iOS devices, this will open AR Quick Look. Unfortunately apple refuses to support other methods such as webXR which are otherwise universally supported. Additionally, USDZ does not have full support for lighting/custom shaders and there is also a hard limit on textures that we can use in the material. This leads to a huge loss of quality when using AR on any IOS device, such as an iPhone. We are actively monitoring changes from apple and if it becomes possible in the future, we will address this.
How to Use These Messages
-
All messages are posted to the parent window. You can intercept them with:
-
Parse
payloadwithJSON.parse(...)if the configurator sends it as a string. -
Update your UI or application state with product data, pricing, SKU, or AR links as needed.
4. Listening for Messages (Parent Application)
In your parent application, add an event listener for message:
5. Sending Messages to the Configurator
You can control the configurator by sending messages from the parent app to the iframe's contentWindow. For example:
Below are the most common commands:
-
SELECT_PRODUCT
Instructs the configurator to switch to another product:
-
SELECT_SELECTION
Applies a user's choice (e.g., new fabric or color) for a specific option:
-
VIEW_DIMENSIONS
Shows or hides dimension lines on the 3D model:
-
ENTER_AR
Attempts to start an augmented reality session or, if necessary, returns an
AR_PREVIEW_LINKthat you can display: -
ENTER_VR
(If supported) instructs the configurator to begin a VR session:
6. Configurator → Parent Message Types (Detailed)
Below is a reference table for all inbound messages the configurator sends and their payload content:
| Type | Meaning | Payload (JSON) |
|---|---|---|
ALL_PRODUCTS | Full list of available products. | Array of product objects, each with dimensionX, dimensionY, dimensionZ, id, manufacturerId, name, price, pricing, productId, retailerAccess, retailerId, sku and other data. |
RANGE | Data about the current range or collection. | An object with id, name, skuand possibly other range-specific fields. |
CURRENT_PRODUCT_ID | Indicates which product is actively displayed. | A single number (e.g., 45). |
CONFIGURATOR_STATE | The complete nested structure of options, groups, selections, etc. | An object that includes retailerId, screenshotThumbnail, configuratorSettings (object), options (array) and selectedSelections (array). |
CURRENT_PRICE | The item's total price based on user selections. | An object with formattedPrice (e.g., "£1,200") and totalPrice (the numeric value in the lowest form of that currency IE pence), and priceBreakdown (array of objects with category, formattedPrice, name, price, sku). |
CURRENT_SKU | The SKU representing the user's current configuration. | An object with skuString (e.g., "SOFA/GREY/OAK") and skuMap (an object of option name → sku). |
AR_PREVIEW_LINK | A direct link to an AR preview for compatible devices. | A string containing the URL. |
SELECT_PRODUCT_RECEIVED | Confirms the configurator has received and processed a SELECT_PRODUCT command. | Typically the same ID you sent (useful for showing loading states). |
ANIMATION_STATE | Notifies the parent of the current animation state. | A string representing the current animation state (e.g., "unavailable", "stop", "loop", "open", "close"). |
7. Parent → Configurator Message Types (Detailed)
Below is a reference table for outbound messages you can send to the configurator:
| Type | Description | Expected Payload |
|---|---|---|
SELECT_PRODUCT | Loads a specific product by its ID. | A single integer representing the product ID. |
SELECT_SELECTION | Updates the user's choice for a specific option. | An object with { optionId: string, groupId: string, selectionId: string }. |
VIEW_DIMENSIONS | Shows or hides product dimension lines. | An object with { dimensions: boolean }. |
ENTER_AR | Initiates augmented reality mode, if supported. | An empty object {} or custom data if needed. |
ENTER_VR | Tries to start a virtual reality session, if supported. | An empty object {}. |
TOGGLE_ANIMATION | Cycles through animation states (stop→loop, loop→stop, open→close, close→open). | An empty object {}. Note: Affects all animation mixers in the scene. |
8. Typical Integration Flow
- Embed the iFrame
- Provide the correct URL (with your API key + product or range).
- Include the required
allowattributes for AR/VR, fullscreen, etc.
- Listen for the Handshake
- As soon as the iframe loads, it sends
ALL_PRODUCTS,CURRENT_PRODUCT_ID,CONFIGURATOR_STATE, etc. - Parse and store these details (e.g., in your parent app's state).
- As soon as the iframe loads, it sends
- User Interaction in the Parent
-
When a user selects a different product from your UI:
-
The configurator reloads to that product and returns updated messages (price, SKU, etc.).
-
- Configurator Updates
- On any selection change, the configurator posts back
CURRENT_PRICE,CURRENT_SKU, etc. - Update your parent UI or e-commerce logic accordingly.
- On any selection change, the configurator posts back
- Special Actions
- AR:
ENTER_ARleads to a WebXR session on Android or anAR_PREVIEW_LINKfor iOS. - Dimensions: Toggle rendering of dimension helpers on or off via
VIEW_DIMENSIONS.
- AR:
9. Example Minimal Code
Below is an extremely simplified example (plain HTML + JS) showing a typical integration:
10. Tips & Troubleshooting
- Cross-Origin: Ensure you have the correct CORS or target origins set.
- Performance: Since real-time 3D rendering can be resource-intensive, consider deferring the iframe load until it's needed, or show a placeholder until loading completes. A good idea can be showing an image of the product, then when the user selects a configuration item switching to the iframe. This way the iframe will have already loaded in the second or two it takes them to make a selection, hiding the loading state.
- AR/VR Compatibility: The
ENTER_ARandENTER_VRfeatures rely on the browser's WebXR implementation. Unsupported devices may fall back to returning anAR_PREVIEW_LINK. - Event Parsing: Always wrap
JSON.parse(payload)in a try/catch block to handle any unexpected responses gracefully. - Product Switches: After sending
SELECT_PRODUCT, wait until you receive an update before updating the UI, as our system debounces updates.