Embed a presentation, or control it with the SDK.
Use an iframe when the website only needs to show the published viewer. Use the SDK when the website needs its own controls to dispatch 3DVizi actions.
TL;DR embed and API video
Add a short walkthrough showing the Embed tab, iframe snippet, SDK snippet, and a custom button dispatching an action.
Overview
There are two embed options.
The iframe embed places the published viewer on a page. It uses the controls, overlays, snapshots, and viewer options already configured in 3DVizi.
The SDK embed renders a tdp-viewer element and lets the host page dispatch actions, list available actions, and read current action state.
The main idea
Actions are the API contract. Create the behaviour in 3DVizi, then dispatch values to those action names from the host page.
Choose an embed
Use iframe for display, SDK for external controls
iframe embed
Use this when the page only needs to display the published viewer. The presentation uses the overlays, snapshots, and viewer controls configured in 3DVizi.
SDK web component
Use this when the host page has its own controls. Load the SDK, render tdp-viewer, then dispatch action values from buttons, selects, forms, or colour inputs.
Simple embed
Use an iframe when the page only needs to display the viewer.
Publish the project, open Viewer Options, then copy the iframe code from the Embed tab. The code includes the published viewer URL and the ?embed parameter.
Use this when the presentation already contains the controls the viewer needs, such as overlays, snapshot navigation, and built-in viewer options.
<iframe
src="https://share.3dvizi.com/p/PROJECT_ID?embed"
width="100%"
height="600"
style="border:none;"
allow="xr-spatial-tracking"
loading="lazy"
></iframe>SDK embed
Use the SDK when your page needs to control the viewer.
The SDK loads the web component, creates the internal viewer iframe, and exposes the methods the host page needs: dispatch, getActions, and getState.
<script type="module" src="https://cdn.3dvizi.com/sdk/v1/viewer.js"></script>
<tdp-viewer
project="PROJECT_ID"
style="width:100%;height:600px;display:block;"
></tdp-viewer>Setup
Choose the iframe path or SDK/API path
Use this path when the published viewer already contains the controls the viewer needs.
Create the presentation
Build the scene in 3DVizi. Add the overlays, snapshots, viewer options, and built-in controls that should be available in the embedded viewer.
Actions and API
How actions and the SDK work together
1. Create the action in 3DVizi
In the Actions dialog, create a Visibility, Material, Alternative, Snapshot, or Animation action. Configure its target and give it a clear label.
2. Use the action API name
3DVizi gives the action an API name slug. Your external page must dispatch that exact name, such as show-wheels or maincolour.
3. Send the value
Call dispatch with the action name and the value. The action receives the value just like it would from an overlay control.
const viewer = document.querySelector("tdp-viewer");
viewer.addEventListener("ready", async () => {
const actions = await viewer.getActions();
console.log(actions);
// Trigger a named action once the scene is ready.
viewer.dispatch("show-wheels", true);
});Visibility actions expect true or false. true shows the target, false hides it.
Material actions receive the value for the selected property. For color, send a CSS-style hex value such as #aae915.
Alternative actions receive an alternative item label or a numeric index. The value default restores the original target parts.
Snapshot actions activate the snapshot configured in the action. The incoming value is normally not used.
Animation actions start the configured model clip using the playback settings saved in the action.
The special name 3dViziScene can receive scene-level values such as { colour: '#ffffff' }.
Events and state
Listen for changes when the viewer or page needs to stay in sync.
The SDK fires a ready event when the scene has loaded. Wait for this before applying startup choices. It also fires action-change whenever an action changes from inside the viewer or from an SDK dispatch.
Use getActions while building or debugging to confirm which action names are available in the published viewer. Use getState when your page needs the current action values.
viewer.addEventListener("action-change", (event) => {
console.log(event.detail.name, event.detail.value);
});
const state = await viewer.getState();
console.log(state);Configurator example
External controls dispatch action values
The configurator example in this website loads the SDK, renders a tdp-viewer, keeps a reference to it, then dispatches action values from custom React controls.
Colour swatches dispatch a scene background colour and a material action. Visibility switches dispatch true or false to the action names for the optional parts.
Implementation rule
Website controls should send action names and values. The action itself owns the 3D behaviour in 3DVizi.
function setMainColour(colour) {
const viewer = document.querySelector("tdp-viewer");
// Scene-level background colour used by the website example.
viewer.dispatch("3dViziScene", { colour });
// A material action created in the 3DVizi editor.
viewer.dispatch("maincolour", colour);
}
function setPartVisible(actionName, visible) {
const viewer = document.querySelector("tdp-viewer");
viewer.dispatch(actionName, visible);
}
setMainColour("#aae915");
setPartVisible("wheels", true);Publishing
Embeds use the published version.
If you change actions, overlays, materials, alternative sets, snapshots, viewer options, or the scene itself, republish before expecting the external page to change. The project ID and embed code can stay the same.
Publish the project before copying or testing embed code.
Create actions in the editor for anything the external page needs to control.
Use the exact API name slug from the Actions dialog.
Wait for the ready event before dispatching startup values.
Use getActions during development to confirm what the published viewer exposes.
Republish after changing scene content, overlays, actions, bindings, viewer options, or alternative sets.
Troubleshooting
Common API issues to check first
The embed shows an old version
Republish the project. Existing embeds keep the same project ID, but they read the latest published version, not the latest unsaved draft.
dispatch does nothing
Check the exact action API name, confirm the project is published, and use getActions to verify the action is available in the viewer.
The value is wrong
Check the action type. Visibility wants booleans, material colour wants a colour value, and alternatives need an item label or index.
The viewer asks for a password
Password protection is part of the published viewer settings. Either enter the password, update Privacy settings, or remove password protection if the embed should be open.
The Embed tab has no code
Publish the project first. Embed snippets are only available once a public viewer exists.
Use actions as the boundary between website and viewer.
Create the scene behaviour in 3DVizi. From the host page, dispatch action names and values, then republish whenever the published viewer needs updated project content.