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 simple 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.
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.
Exports
Exports can be requested easily as well.
Credit usage of exports
Each export triggered consumes a credit.
Additional CodeSandBoxes
Content Update
Updating the content of an output with custom data, in this case, material data. Freezing the output not to be overwritten by parameter value changes.Persistence Between Updates
Updating simple properties like the visibility of nodes and making such changes persist across parameter value changes.Persistence Between Updates (advanced)
Updating advanced outputs like HTMLElements added to the scene and making such changes persist across parameter value changes.Automatic Scene Updates
Automatic triggering of scene updates on parameter value changes.Parallel Customization
Request multiple customizations in parallel. The results will only be returned to you, but not stored in the scene. Note: Depending on the plan you are subscribed to, your parallel customization requests will be rate limited.Initial Parameter Values
Parameter values can be provided on initialization.Catching Errors
Errors that happen during the initialization (and customization) can be caught and mapped.
Parameters
File Parameters
How to use file parameters that allow using files as parameter values.File Parameters - advanced
How to use file parameters that allow using files as parameter values. In this example mime types and file endings are considered.
Exports
Export Request with Parameters
Export request using parameter values.Export Request with JWT Token download
Export request where the download uses a JWT token for authorization.
Outputs
Data Outputs
Receiving and reading data outputs.