ProductBuilder Iframe API V0

The Iframe API lets you embed a ProductBuilder Viewer on your website and control its behavior using JavaScript. This is our first attempt at creating such an API and we expect to make changes in the future, as first attempts are usually not final.

Using the API's JavaScript functions you can select presets; save and load projects; share designs; get a project's current price and take screenshots. You can also add event listeners that will execute in response to certain viewer events, such as a design update.

This guide explains how to use the Iframe API. It identifies the different types of events that the API can send and explains how to write event listeners to respond to those events. It also details the different JavaScript functions that you can call to control the viewer as well as the viewer parameters you can use to customize the viewer.

Requirements

The user's browser must support the HTML5 postMessage feature. Most modern browsers support postMessage.

Getting started

The sample HTML page below creates an embedded viewer that will load a Package and display the first preset. The numbered comments in the HTML are explained in the list below the example.

<!DOCTYPE html>
<html lang="en">

   <body>

        <!-- The package id is in the URL -->
        <iframe width=800 height=600 id="pbapp" src="https://live.productbuilder.nl/demo"></iframe>

        <script type="module" async="true">

            import PBIframeApi from 'https://cdn.productbuilder.nl/iframe-api.v0.js';

            // the iframe to communicate with
            const iframe = document.getElementById( 'target' );

            // create the control object
            const viewer = new PBIframeApi( iframe );

            // wait for the connection to be made
            await viewer.connectionPromise;

            // start controlling the viewer
            await viewer.selectPreset( 0 );

        </script>
    </body>
</html>

Initialisation

A viewer can simply be embedded by embedding an Iframe with the appropriate URL. To control the API, the iframe-api script must be loaded from https://cdn.productbuilder.nl/iframe-api.v0.js. The script is a module and must be loaded as such. It exports the PBIframeApi class, which can be instantiated by providing a reference to a ProductBuilder Iframe DOM element. The new PBIframeApi object will attempt to connect to the code inside the Iframe by checking whether the

content is indeed a ProductBuilder viewer
versions are compatible
origin of the parent is allowed by the viewer

The PBIframeApi object has a property called connectionPromise which is should be awaited. If any of the above checks fail, the promise is rejected resulting in an error which you can catch and deal with gracefully. If the promise resolves, the connection has been made and it is now safe to start communicating with the viewer.

Operations

Change the locale

Only possible after the viewer is connected to the ProductBuilder cloud.

viewer.setLocale(locale:String):Boolean

Get the id of the current project

viewer.projectId():String

Get the slug of the current project

viewer.projectSlug():String

Creates a copy with a different id/slug and make it readonly.

viewer.shareProject():Object<string,string>

Save the current project to the ProductBuilder cloud

viewer.saveProject():Object<string,string>

Load a project from the cloud.

viewer.loadProject(identifier:String):Object<string,string>

Get the configurators in the current design

Returns an array of objects with the configurator id and pkg id.

viewer.listConfigurators():Array<Object<string,string>>

Get the presets of a package

Returns a flat list of objects with the preset id and package id.

viewer.listPresets(pkgId:String):Array<Object<string,string>>

Take a screenshot

Returns a DataURI of a screenshot of the current camera angle.

viewer.screenshot():String

Select a preset

Update the current design by changing it into a preset.

viewer.selectPreset({ configuratorId:String, presetId:String }):Boolean

Get project price

Returns the current price object if the viewer is connected to the ProductBuilder cloud.

viewer.price():Object

Call template specific methods

viewer.ui(data:any):any

List the available packages

Returns an array of {id:string} objects.

viewer.listLoadedPackages():Array<Object<string,string>>

ProductBuilder Docs