Sessions

Your models running on ShapeDiver are hosted on one of our Geometry Backend systems. The access to triggering customizations and downloading computation results is controlled by sessions. In order to create a session from an instance of the viewer embedded in a website, you need to provide a ticket for embedding.

In our initial example we already created an instance of the Viewport and opened a Session with a model. Using a Session object you can do things such as change Parameter values and request computation results for them (aka requesting a customization), and request Exports.

The data resulting from computations of a model is available through the Outputs of the session object. Each session corresponds to a node in the scene tree. This node and its children are updated automatically depending on the data resulting from a customization.

You can open simultaneous Sessions with one or several models from a single instance of the viewer, but in most cases you will only be using one.

A Session can exist completely without a Viewport, as a Viewport can exist without a Session. For more functions and properties, please see our Documentation on Session, Parameter, Export and Output.

Credit usage of embedded sessions

Each session opened from an embedded viewer consumes at least one credit.

In case you open simultaneous sessions with one or several models from a single instance of the viewer, each individual session consumes a credit.

Each credit covers an active session duration of up to 10 minutes during which unlimited customizations (parameter changes) can happen. If a session exceeds 10 minutes of usage, another credit covering a further 10 minute active session duration is deducted as soon as the first customization happens which is not covered by the previous 10 minute period anymore. As an example:

A user opens a web page which embeds one of your models. The user engages with the model for about 5 minutes and does several parameter changes, then leaves the model unattended. After 20 minutes the user comes back and further changes parameters for about 8 minutes. This will consume 2 credits.

Please note that triggering exports consumes further credits as mentioned below.

Read more about ShapeDiver credits in the pricing page.

Parameters

Let's continue with the simple example of our last section and add something to it. The Session that we use as an example can change the length of the provided shelf from values 2 to 10. In our first case we just want to change it to 6.

// read out the parameter with the specific name
const lengthParameter = session.getParameterByName("Length")[0];

// update the value
lengthParameter.value = 6;

// and customize the scene
await session.customize();

Hint: Clicking Click to Run opens a standalone environment with a live preview and direct links to the CodeSandbox project and GitHub source code.

You can also update multiple Parameters together and then customize the Session in the end. We will now update the length to 8 and update the color to #00ff00 (green). Notice that the customization call is only called once. Therefore, only one request is sent to our servers.

// read out the parameter with the specific name
const lengthParameter = session.getParameterByName("Length")[0];

// update the value
lengthParameter.value = 8;

// read out the parameter with the specific name
const colorParameter = session.getParameterByName("Material Color")[0];

// update the value
colorParameter.value = "#00ff00";

// and customize the scene
await session.customize();

Hint: Clicking Click to Run opens a standalone environment with a live preview and direct links to the CodeSandbox project and GitHub source code.

Exports

Exports can be requested easily as well. Exports allow users to generate and download computation results, such as geometry (3DM, DXF, DWG, STL, etc), images, data reports and much more.

Credit usage of exports

Each export triggered consumes a credit.

// read out the export with the specific name
const exportObject = session.getExportByName("Export3DModel")[0];

// request the export
const result = await exportObject.request();

// handle the export result
const fileUrl = result.content?.[0].href;
window.open(fileUrl);

In the example below, the code is already taking authorization into account when downloading the data. This might be necessary depending on your security settings.

Hint: Clicking Click to Run opens a standalone environment with a live preview and direct links to the CodeSandbox project and GitHub source code.

Outputs

Outputs can be used to retrieve data directly. This can be additional information like prices or information about the model.

// "getOutputByName" returns an array with all outputs that have the desired name
const dataOutput = session.getOutputByName("NumberOfSeats")[0];
console.log(`How many seats are there? ${dataOutput.content![0].data}`);

Hint: Clicking Click to Run opens a standalone environment with a live preview and direct links to the CodeSandbox project and GitHub source code.

Parameter Types & Value Formats

Each parameter type expects values in a specific format. Using the wrong format is a common source of errors.

StringList is a common source of confusion: the value must be a string representation of the zero-based index, not the label text. Use parameter.choices to see the available options:

const param = session.getParameterByName("Material")[0];
console.log(param.choices); // ["Wood", "Metal", "Glass"]

// To select "Metal", use index "1":
param.value = "1";
await session.customize();

You can validate a value before setting it using parameter.isValid():

if (!parameter.isValid(newValue, true)) {
  console.warn("Value is not valid for this parameter");
}

Batching & Debouncing Customizations

When updating multiple parameters, always batch the changes into a single customize() call. This sends one request to the server instead of multiple, reducing latency and avoiding rate limiting (HTTP 429).

Option 1: Shorthand — pass values directly to customize()

You can pass a parameter-values map directly to customize() using parameter names or IDs as keys. This is the simplest approach when you know the values upfront:

// Pass all values in one call — by name or parameter ID
await session.customize({
  "Width": 100,
  "Height": 50,
  "Material Color": "#ff0000"
});

Option 2: Set values, then customize

Alternatively, set each parameter's value property first, then call customize() with no arguments. This approach is useful when building dynamic UIs, using param.isValid() checks, or working with type-safe conversions:

// Set all parameter values first
session.getParameterByName("Width")[0].value = 100;
session.getParameterByName("Height")[0].value = 50;
session.getParameterByName("Material Color")[0].value = "#ff0000";

// Then send all changes in one request
await session.customize();

For UI controls that fire rapidly (sliders, color pickers), debounce the customize() call so it only fires after the user stops interacting:

let debounceTimer: ReturnType<typeof setTimeout>;

slider.addEventListener("input", () => {
  clearTimeout(debounceTimer);
  param.value = parseFloat(slider.value);
  debounceTimer = setTimeout(() => session.customize(), 200);
});

Output Update Callbacks

You can register a callback on an output to react whenever its scene tree node is replaced after a customization. This is useful for carrying over data (like interaction flags or material overrides) from the old node to the new one, or for updating UI elements based on the output's updated content.

const output = session.getOutputByName("PricingData")[0];

// The callback receives the new and old scene tree nodes
output.updateCallback = (newNode, oldNode) => {
  // The output's content property is already updated at this point
  const data = output.content?.[0]?.data;
  if (data) {
    document.getElementById("price-display")!.textContent = 
      "Price: " + data;
  }
};

The callback signature is (newNode?: ITreeNode, oldNode?: ITreeNode) => void | Promise<void>. It fires whenever the output's scene tree node is replaced. Access the updated data via output.content (which is already refreshed when the callback runs). If the callback returns a Promise, it is awaited in the execution chain.

JWT Authorization

For models that require additional security, you can enable JWT (JSON Web Token) authorization. When enabled, the session must be created with a valid token, and certain operations (like exports) require authorized access.

Creating a Session with JWT

const session = await SDV.createSession({
  ticket: "YOUR_TICKET",
  modelViewUrl: "YOUR_MODEL_VIEW_URL",
  jwtToken: "YOUR_JWT_TOKEN"
});

Handling Token Refresh

JWT tokens have a limited lifetime. To avoid 403 errors when the token expires, provide a refresh callback:

session.refreshJwtToken = async () => {
  // your code for token generation
  return "YOUR_JWT_TOKEN";
};

The viewer calls this function automatically when a token-protected request fails due to expiration.

For more details on the backend authorization flow, see the API Authorization page.

Additional Examples

Additional example can be found on the viewer examples page in the session section.