Embed Apps in external websites

This feature is only available for ShapeDiver users with a paid subscription.

You can embed ShapeDiver Apps as iframes on any website. In the future, the platform will include a way to customize and copy the iframe code directly. At the moment, this can be done by following the below steps:

1. Whitelist the website’s domain

First, you need to whitelist your website’s domain, which is necessary for any type of model embedding (i.e for legacy iframe embedding as well as direct embedding).

2. Allow iframe embedding

In order, to embed Apps, one also needs to allow iframe embedding for the model. This can be done in the Iframe settings of the model edit page.

3. Copy the iframe embed code

In the model view page, you will find a section called App iframe. In this section, you can update the width and height of the iframe in the embed code, and copy it at the click of a button.

In the future, more iframe options will be available from this section.

URL parameters

You can use the following URL parameters (aka query string parameters) to augment the behavior of App Builder. If you want to include these parameters in your embedded iframes, just add them to the URL included in the iframe code. For example, include a model state like such:

HTML

<iframe width="100%" 
        height="480" 
        src="https://appbuilder.shapediver.com/v1/main/latest/?slug=MODEL_SLUG&modelStateId=O52ZCglVEegUEpax" 
        referrerpolicy="origin" 
        allowfullscreen 
        style="overflow: hidden; border-width: 0;
        ">
    <p>Your browser does not support iframes.</p>
</iframe>

Parameter name	Description
`slug`	The slug (aka URL identifier) of the model to load. You need to allow iframe embedding for this to work. This method supports the protection of your model by a short-lived token. You can use the Require strong authorization setting for your model. This protection can be enabled in the Embedding settings for all of your models or individually for each model in the Developer settings.
`ticket`	The ticket (aka API key) of the model to load. You need to allow direct embedding for this to work. When specifying a `ticket`, you also need to provide a `modelViewUrl`. This method does not support protection of your model by a short lived token. You need to disable the Require strong authorization setting for your model.
`modelViewUrl`	The modelViewUrl (aka API endpoint) of the model to load. You need to allow direct embedding for this to work. When specifying a `modelViewUrl`, you also need to provide a `ticket`.
`g`	Link to a JSON file that defines theme settings. The JSON file can also define the `slug`, or `ticket` and `modelViewUrl`.
`modelStateId`	Id of the model state to load initially.
`context`	This can be used to provide contextual information to the Grasshopper model. Typical context values are cart and order. The WordPress / WooCommerce plugin uses these values when opening an App Builder configurator from the cart or order pages. Further values can be used freely. If a direct text input named `"context"` exists in the loaded model, the value of `context` will be mapped to it. Otherwise, the value is ignored.
`_{YOUR_PARAMETER_NAME}`	You can set initial values for any parameter in your model by prefixing the parameter’s `name` or `id` by an underscore `_` character. An Example: Appending `&_Width=10&_extended=false` to the query string will set the parameter named `Width` to `10` and the parameter named `extended` to `false`. The parameters you specify must exist for the given model; otherwise, loading the model will fail.
`trackingDomain`	Allows to define a domain for tracking web analytics to plausible.io. You can join an onboarding call if you'd like to learn more about this feature.
`utm_source` `utm_medium` `utm_campaign` `utm_term` `utm_content`	Classic parameters for tracking the effectiveness of marketing campaigns (https://en.wikipedia.org/wiki/UTM_parameters). You can use these parameters if you specify a `trackingDomain`.
`utm_user`	Non-standard parameter for tracking individual users. You can use this parameter if you specify a `trackingDomain`. Be aware of the implications this might have regarding data protection regulations.

App Builder Versioning

The iframe embed code shown above makes use of the base URL https://appbuilder.shapediver.com/v1/main/latest/. This URL always uses the latest released version of App Builder. In some cases you might want to lock in a specific version of App Builder. You can do this by replacing the last part of this URL (latest) by the specific version you want to use. An example:

https://appbuilder.shapediver.com/v1/main/1.0.12/ uses version 1.0.12.

You can always look up the version you are currently using in the browser console. Look for a line like this: ShapeDiver App Builder SDK v1.0.12