Introduction

How does it work?

The integration is done by creating a new instance of the "Instabox3D" class, passing an object with some configuration parameters. The configurator will appear in an iframe, depending on these parameters, as a pop-up window or within an existing HTML element on the web page.

Include the script

Integration requires the inclusion of the following script (as shown below) near the end of your HTML pages.

<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

JavaScript code

We will need to write JavaScript code and this can be done in a JavaScript file or directly within the <script> tags.

For these examples, it will be done between the <script> tags to keep all the code in the same file and simplify its reading.

In addition, the code is complemented by comments with explanations (they do not affect its functionality):

<!-- HTML Comment -->

// JavaScript Comment

Basic integration

Creating the instance

To create the instance of the class "Instabox3D" we write the following code:

<script>
 // Create the instance
 const instabox = new Instabox3D({
  // we will include the parameters here
 });
</script>

Parameter ( client: String )

The first parameter we will see refers to the name of the client. This is also the only mandatory parameter for instantiation.

The value must be the name of the subdomain of your InstaBox 3D

If the URL of your InstaBox 3D is "https://my-company.instabox3d.com", the value of this parameter will be "my-company".

This is usually the name of the company, in lower case, with spaces replaced by hyphens if there are any.

In these examples the value will be "trial".

Parameter ( productRef: String )

In order for the configurator to display the desired product, it is necessary to specify the product reference.

The reference of each product is the one specified in the briefing during the setup phase of the configurator.

This parameter can be specified:

• At the time of instantiation. In which case the configurator will open showing the specified product.
• In the execution of the open method (explained in the methods section). In which case the configurator will not be opened until the execution of the method.

In these examples the value will be "fefco-0201".

Example of basic integration

If we add the two parameters we just explained to the code we already had, we should see the configurator as a full-screen pop-up window:

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 // Create the instance
 const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
 });
</script>

Debug mode ( debug: Boolean = false )

If you followed the steps and copied the code above, you shouldn't have any problems. However, if you've been encouraged to add your own values (for "client" and "productRef") and something went wrong, don't worry because this will help you:

If the debug parameter (default false) is true, it prints (in the console) errors that may occur during the integration process.

It is very useful to activate this mode during the development phase to detect possible problems, but it is recommended to deactivate it in a production environment.

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 // Create the instance
 const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
  debug: true,
 });
</script>

Customizing the size of the pop-up window

Parameter ( modal: Boolean = true)

As mentioned earlier in the introduction, the configurator can appear as a pop-up window or within an HTML element of the web page.

To control this behaviour, the modal parameter is defined (default true).

As this section deals with the customisation of the modal, we will leave the code as it is, as not defining this parameter is the same as setting modal: true.

Parameter ( modalWidth: String = "100vw")

By default the configurator appears full screen, because the default value of modalWidth is "100vw".

It would be enough to assign in a text string (following the CSS syntax) the desired value to change the width.

Parameter ( modalHeight : String = "100vh")

Similar to modalWidth, it controls the height of the popup window with a default value of "100vh".

Again, it would be enough to assign in a text string (following the CSS syntax) the desired value to change the height.

Example at 80% of the screen

By adding these parameters you should again see the configurator as a pop-up window, but this time, at 80% of the screen.

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 // Create the instance
 const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
  debug: true,
  modalWidth: "80vw",
  modalHeight: "80vh",
 });
</script>

Configurator within an HTML element

Parameter ( modal: Boolean = true )

Previously we explained the modal parameter with its default value true.

As a first step for the configurator to appear inside an HTML element, false must be assigned to this parameter.

Parameter ( containerId: String )

When modal is false, it is necessary to define the id of the HTML element that will contain the configurator.

Parámetro ( iframeWidth : String = "100%" )

Once you have defined the id of the container element, you can define the size of the configurator relative to it.

By default the value is "100%" so it will cover the full width of the parent element.

It would be enough to assign in a text string (following CSS syntax) the desired value to change the width relative to the container element.

Parameter ( iframeHeight : String = "600px" )

Similar to iframeWidth, iframeHeight controls the height of the configurator relative to the container element.

By default the value is "600px" so it will be 600 pixels high.

It would be enough to assign in a text string (following CSS syntax) the desired value to change the height relative to the container element.

Fitting to the container element

One of the most common cases is to adjust the size of the iframe according to the size of the parent element.

This will be the case in the example below, where:

• iframeWidth is not defined because it is already 100% by default.
• iframeHeight: "auto" is defined.
• display: flex; is added to the style of the container element.

<!-- HTML container element with id and style (including display: flex;) -->
<div id="configurator-container" style="width: 75vw; height: 75vh; border: 1px solid black; display: flex;"></div>

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 // Create the instance 
 const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
  debug: true,
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
 });
</script>

Retrieving configuration data

Parameter / Event (onFinish: Function)

Once the user finishes the configuration, the data is saved in the leads page of InstaBox 3D, but it can be interesting to collect the data, either to display a summary, calculate a price, save it in a database, etc.

For this purpose, there is the onFinish parameter (function type), which is executed when the user finishes the configuration by passing a JavaScript object with the configuration data as a parameter.

Example retrieving data

If we add the onFinish parameter to any of the above codes, we are ready to receive the configuration data.

In this case, the data will simply be displayed in the console, so I will use an anonymous function, but you can declare a function and pass it as the value of this parameter without any problem:

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 // Create the instance
 const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
  debug: true,
  modalWidth: "80vw",
  modalHeight: "80vh",
  onFinish: data => console.log("Datos del configurador", data),
 });
</script>

Structure of the returned data

The object will contain the following values:

• title: title or name of the product.
• image: url of the image of the customized product.
• instaviewer: url of the 3D visualisation of the customised product.
• pdf: url of the pdf with the information chosen in the configuration.
• artwork: url of the .zip file containing the original graphics and a .pdf file for each part (to which the user has applied at least one graphic) with the position of these files. This value will not be returned if the user has not applied any graphics to the product.
• config: JavaScript object in which each variable will appear as a property, along with its value.

Like the product reference, the variable names will be those specified in the briefing during the setup phase of the configurator.

{
 title: "Product title",
 image: "https://example.instabox3d.com/files/image.png",
 instaviewer: "https://example.instabox3d.com/viewer/example",
 pdf: "https://example.instabox3d.com/files/summary.pdf",
 artwork: "https://example.instabox3d.com/files/artwork.zip",
 config: {
  variable1: 300,
  variable2: 200,
  variable3: 100
 }
}

Assigning default values to the box (parametric only)

Use cases

In the case of parametric boxes it is possible to assign default values to the variables. For example to make the box appear with a certain size.

Another very common case are fixed boxes created from parametric models, i.e. a single parametric box is created and then in the integration the measurements of the fixed box are passed on.

Parameter ( boxParams: Object )

The boxParams parameter (Object type) is in charge of collecting the default variables of the box, setting the name of the variable as the key and its desired value.

Again, the variable names will be those specified in the briefing during the setup phase of the configurator.

In this case, the box has the following variables:

• l: length in mm
• b: breadth in mm
• h: height in mm

We could then create the following object:

{
 l: 320,
 b: 270,
 h: 150
}

And if we add this to the code we should see how the box now starts with those values:

<!-- HTML container element with id -->
<div id="configurator-container" style="width: 75vw; height: 75vh; border: 1px solid black; display: flex;"></div>

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 // Create the instance
 const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
  debug: true,
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
  boxParams: {
   l: 320,
   b: 270,
   h: 150,
  },
 });
</script>

Other useful parameters

Parameter ( language: String )

If your InstaBox has multiple languages, you can force the configurator to appear in one of those languages. Just type the language code (two characters), for example "en" for English or "es" for Spanish.

 const instabox = new Instabox3D({
  // Other parameters
  language: "en",
 });

Parameter ( disableForm: Boolean )

If you have chosen the form (contact form) option, you will see that this form appears when you integrate the configurator

On some occasions, this won’t be a convenient option; for example, if you use the InstaBox as an internal tool (including the contact form) and you want to integrate it into your e-commerce as well, in the second case the contact form would not make sense. It would cut off the correct e-commerce flow. In that case, you can use the disableForm parameter to deactivate the contact form in the integration.

 const instabox = new Instabox3D({
  // Other parameters
  disableForm: true,
 });

Open and close methods

Use cases

It is quite common that the configurator needs to be opened after some action by the user, e.g. after pressing a button.

Going back to what we said in the explanation of the productRef parameter, this parameter can be specified at the time of instantiation or in the open method.

In the case we were talking about opening the configurator after an action, it doesn't make sense to define the productRef in the instantiation because this would make the configurator open at that moment, and that's not what we want.

Open method

To open the configurator manually, the open method must be executed, passing as parameter a configuration object that contains the parameter productRef.

It should be noted that in the argument (Object type) other parameters can be defined in addition to the productRef, overwriting the old values in case they were already defined at the time of instantiation.

Close method

If once the configurator is open we want to give the user the option to exit without finishing, the most logical thing to do is to have some kind of interaction to close the configurator. This is possible by executing the close method which does not take any arguments.

Implementing buttons

Using the concepts explained above we will implement the integration with buttons to open and close the configurator.

In this case the productRef parameter will not be passed at the time of instantiation, but will be passed at the time of executing the open method.

if (instabox.isReady) {
 // execute methods
}

<!-- Button that executes the openInstabox function to open the configurator. -->
<button onclick="openInstabox()" id="open-btn" disabled>Open configurator</button>

<!-- Button that executes the closeInstabox function to close the configurator. -->
<button onclick="closeInstabox()" id="close-btn" style="position: absolute; top: 1rem; right: 1rem; display: none">
 Close configurator
</button>

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 function openInstabox() {
  if (instabox.isReady) {
   instabox.configurator.open(
    { productRef: "fefco-0201" },
    onInstaboxOpen, // explained in the "Loading and errors with callbacks #2" section
    onInstaboxError // explained in the "Loading and errors with callbacks #2" section
   );
  }
 }

 function closeInstabox() {
  if (instabox.isReady) {
   instabox.configurator.close();
   document.getElementById("close-btn").style.display = "none";
  }
 }

 function onInstaboxError() {
  console.log("InstaBox Error");
 }

 function onInstaboxLoad() {
  console.log("InstaBox Loaded");
  document.getElementById("open-btn").removeAttribute("disabled");
 }

 function onInstaboxOpen() {
  console.log("InstaBox Opened");
  document.getElementById("close-btn").style.display = "block";
 }

 function onInstaboxFinish(output) {
  console.log("Instabox Output", output);
 }

 // Configuration object without productRef so that it does not open the configurator automatically
 const configObject = {
  client: "trial",
  modalWidth: "80vw",
  modalHeight: "80vh",
  onFinish: onInstaboxFinish,
 }

 // Create the instance with callbacks (explained in the "Loading and errors with callbacks #1" section)
 const instabox = new Instabox3D(configObject, onInstaboxLoad, onInstaboxError);

</script>

Asynchronous loading and error handling with Callbacks

Loading and errors

It's time to get into a bit more advanced topics. In the methods section we discussed the need to check if the instabox is ready before executing any method, but why?

Because the loading process is asynchronous, meaning that the code is still running and the user can still interact with the page while the InstaBox 3D is loading. This can lead to a method being executed before it has even fully loaded, either because the user has clicked a button or because it has been defined as such in the code.

This simple check avoids possible problems, but it can be interesting to know when it has finished loading in order to carry out some action, or even to know if it has not been able to load successfully.

There are two ways to do this:

• with callbacks
• with promises

Loading and errors with Callbacks #1

First we will deal with the case where the productRef parameter is defined at instantiation time.

The constructor of the Instabox3D class receives two optional parameters in addition to the configuration object:

• The second parameter is a callback function that will be executed as soon as it has been successfully instantiated and the configurator has finished loading.
• The third parameter is a callback function that shall be executed in case of an error, passing an error message as parameter.

For this example:

• The configuration object is pre-defined for clarity in the code
• Two functions are created that simply display messages in the console
• debug mode is not activated as we are displaying possible errors with the onInstaboxError function

<!-- HTML container element with id -->
<div id="configurator-container" style="width: 75vw; height: 75vh; border: 1px solid black; display: flex"></div>

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 function onInstaboxReady() {
  console.log("Instabox is ready");
 }

 function onInstaboxError(error) {
  console.warn(error);
 }

 // Configuration object
 const configObject = {
  client: "trial",
  productRef: "fefco-0201",
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
 };

 // Create instance with callbacks
 const instabox = new Instabox3D(configObject, onInstaboxReady, onInstaboxError);
</script>

Loading and errors with Callbacks #2

Let us now deal with the case where productRef parameter is not defined at instantiation time.

As we already know, in this case the configurator will not be opened until the open method is executed with the productRef desired, so the callback functions that we have defined in the previous example will be used to know when it has been instantiated or, otherwise, if an error has occurred.

So how do we know when the configurator has opened and finished loading?

The open method also receives two optional parameters in addition to the configuration object:

• The second parameter is a callback function that will be executed as soon as the configurator has finished loading.
• The third parameter is a callback function to be executed in case of an error, passing an error message as a parameter.

In this example:

• No productRef added in the instantiation
• Button implementation is added
• A function is created for when the configurator has loaded successfully
• Same error function used for configurator and instantiation

<!-- HTML container element with id -->
<div id="configurator-container" style="width: 75vw; height: 75vh; border: 1px solid black; display: flex"></div>

<!-- Button that executes the openConfigurator function to open the configurator. -->
<button onclick="openConfigurator()">Abrir configurador</button>

<!-- Button that executes the closeConfigurator function to close the configurator. -->
<button onclick="closeConfigurator()">Cerrar configurador</button>

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 function openConfigurator() {
  if (instabox.isReady) {
    // Abrir el configurador con calbacks
   instabox.configurator.open(
    { productRef: "fefco-0201" },
    onConfiguratorReady,
    onInstaboxError
   );
  }
 }

 function closeConfigurator() {
  if (instabox.isReady) {
   instabox.configurator.close();
  }
 }

 function onInstaboxReady() {
  console.log("Instabox is ready");
 }

 function onInstaboxError(error) {
  console.warn(error);
 }

 function onConfiguratorReady() {
  console.log("Configurator is ready");
 }

 // Configuration object
 const configObject = {
  client: "trial",
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
 };

 // Create instance with callbacks
 const instabox = new Instabox3D(configObject, onInstaboxReady, onInstaboxError);
</script>

Loading and errors with Promises #1

Let's go back to the case where the productRef parameter is defined at instantiation time, but this time with promises.

The code is pretty much the same but this time we need to add a parameter that we haven't seen before:

This parameter is used to be able to manually start the loading in case we want to manage the asynchronous part with promises.

In this example:

• The autoInit parameter is set to false
• Manually start with the init method which returns a promise
• The promise is managed (in this case with a then and catch, but it could be perfectly with an async / await and its corresponding try ... catch)

<!-- HTML container element with id -->
<div id="configurator-container" style="width: 75vw; height: 75vh; border: 1px solid black; display: flex"></div>

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 function onInstaboxReady() {
  console.log("Instabox is ready");
 }

 function onInstaboxError(error) {
  console.warn(error);
 }

 // Configuration object
 const configObject = {
  client: "trial",
  productRef: "fefco-0201",
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
  autoInit: false,
 };

 // Create the instance
 const instabox = new Instabox3D(configObject);

 // Manually initiate with promises
 instabox.init().then(onInstaboxReady).catch(onInstaboxError);
</script>

Loading and errors with Promises #2

In the case where the productRef parameter is not defined at instantiation time, the asynchronous part can also be handled with promises, since the open method returns one.

In this example:

• No productRef added in the instantiation
• Button implementation is added
• A function is created for when the configurator has loaded successfully
• The same error function is used for the configurator and for instantiation
• The promise is managed (in this case with a then and catch, but it could be perfectly well with an async / await and its corresponding try ... catch)

<!-- HTML container element with id -->
<div id="configurator-container" style="width: 75vw; height: 75vh; border: 1px solid black; display: flex"></div>

<!-- Button that executes the openConfigurator function to open the configurator. -->
<button onclick="openConfigurator()">Abrir configurador</button>

<!-- Button that executes the closeConfigurator function to close the configurator. -->
<button onclick="closeConfigurator()">Cerrar configurador</button>

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 function openConfigurator() {
  if (instabox.isReady) {
    // Abrir el configurador con promesas
   instabox.configurator
    .open({ productRef: "fefco-0201" })
    .then(onConfiguratorReady)
    .catch(onInstaboxError);
  }
 }

 function closeConfigurator() {
  if (instabox.isReady) {
   instabox.configurator.close();
  }
 }

 function onInstaboxReady() {
  console.log("Instabox is ready");
 }

 function onInstaboxError(error) {
  console.warn(error);
 }

 function onConfiguratorReady() {
  console.log("Configurator is ready");
 }

 // Configuration object
 const configObject = {
  client: "trial",
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
  autoInit: false,
 };

 // Create the instance
 const instabox = new Instabox3D(configObject);

 // Manually initiate with promises
 instabox.init().then(onInstaboxReady).catch(onInstaboxError);
</script>

Two-way communication

Use cases

We have reached the last and perhaps the most powerful section, in which we will see how to establish a fluid two-way communication.

This will allow, among other things, to calculate prices dynamically (without waiting for the user to finish the configuration) or to control the inputs externally to the configurator and therefore make validations or apply desired styles.

Parameter ( hiddenSidebar: Boolean )

If you want to create a unique integration by adding the inputs and buttons to the layout of your website, you can disable the sidebar of the configurator by setting hiddenSidebar to true.

Parameter / Event (onChange: Function)

Every time the user makes a change in the configuration, this function is executed by passing as parameter an array with the variables of the box, including the current values and available values in case of selection variables.

{
 name: "mat",
 options: [
  {name: "Material 1", value: 0}
  {name: "Material 2", value: 1}
  {name: "Material 3", value: 2}
 ],
 publicName: "Material",
 type: "SelectVariable",
 value: 0
}

{
 name: "l",
 publicName: "Length",
 type: "Variable",
 value: 350
}

ChangeBoxParams method

The changeBoxParams method works similarly to the boxParams parameter, and can be executed by passing an object that will have the variable name as a key and its desired value.

The variable names will be those specified in the briefing during the setup phase of the configurator.

In this case, the box being used has the following variables:

• l: length in mm
• b: width in mm
• h: height in mm

Then we could send the following object with the changeBoxParams method to change the length value dynamically:

{
 l: 320;
}

OpenArtwork method

The openArtwork method can be used to open the 2D editor, where the user can upload and place graphics on the box.

Parameter / Event (onArtworkOpened: Function)

When the 2D editor is opened, this function is executed

CloseArtwork method

The closeArtwork method can be used to close the 2D editor.

Parameter / Event (onArtworkClosed: Function)

When the 2D editor is closed, this function is executed

Parameter/Event (onError: Function)

If the values entered are not valid, the configurator displays an error message and this function is executed passing that error message as a parameter.

FinishConfiguration method

The finishConfiguration method can be used to end the configuration at any time.

Example of two-way integration

In this example:

• Add an input to define the length externally to the configurator
• Collect the current values of the box to show them in the input
• A button is added to finalise the configuration externally to the configurator

<!-- HTML container element with id -->
<div id="configurator-container" style="width: 75vw; height: 75vh; border: 1px solid black; display: flex"></div>

<!-- Input to modify the length of the box -->
<input id="length" type="number" placeholder="Length" onchange="changeBoxLength(this)" />

<!-- Button that opens or closes the 2D editor -->
<button id="artwork" onclick="openArtworkEditor()">Open 2D Editor</button>

<!-- Button that executes the finishConfiguration function to finish the configuration. -->
<button onclick="finishConfiguration()">Finish Configuration</button>

<!-- Include the script -->
<script src="https://www.instabox3d.com/output/default/js/integration.js"></script>

<script>
 function changeBoxLength(input) {
  if (instabox.isReady) {
   instabox.configurator.changeBoxParams({
    l: input.value
   });
  }
 }

 function onInstaboxChange(data) {
  const variable = data.find(variable => variable.name === "l");
  if (variable) {
   document.getElementById("length").value = variable.value;
  }
 }

 function finishConfiguration() {
  if (instabox.isReady) {
   instabox.configurator.finishConfiguration();
  }
 }

 function openArtworkEditor() {
  if (instabox.isReady) {
   instabox.configurator.openArtwork();
  }
 }

 function closeArtworkEditor() {
  if (instabox.isReady) {
   instabox.configurator.closeArtwork();
  }
 }

 function onArtworkOpened() {
  const artworkElement = document.getElementById("artwork");
  artworkElement.innerHTML = "Close 2D Editor";
  artworkElement.onclick = closeArtworkEditor;
 }

 function onArtworkClosed() {
  const artworkElement = document.getElementById("artwork");
  artworkElement.innerHTML = "Open 2D Editor";
  artworkElement.onclick = openArtworkEditor;
 }

 // Create the instance
 const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
  debug: true,
  onChange: onInstaboxChange,
  onArtworkOpened: onArtworkOpened,
   onArtworkClosed: onArtworkClosed,
 });
</script>