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

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

<script src="https://www.instabox3d.com/integration-v4.1.0.js"></script>

Instantiation

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

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

Parameters

The parameters establish which product is going to be displayed and the appearance of the configurator.

There are 3 types of parameters:

• Required parameters: They are necessary to open the configurator.
• Optional parameters: Define how the configurator will be displayed.
• Event parameters: Define events to perform actions when something happens within the configurator

These parameters can be passed at instantiation time

const instabox = new Instabox3D({
 // parameters
});

and also in the open method.

instabox.open({
 // parameters
});

Static parameters such as the client and optional or event parameters are usually defined at the time of instantiation. The productRef and the boxParams are usually defined in the open method.

In the open method it is also possible to modify or overwrite a previously defined parameter.

Required Parameters

client: String

The first parameter that we will see refers to the name of the client.

The value should be the subdomain name of your Instabox 3D

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

It is usually the name of the company, in lowercase and replacing the spaces with hyphens if there are any.

productRef: String

productRef and projectRef are exclusive parameters. One or the other must be added. Not both at the same time

In order for the configurator to show 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 open until the moment of its execution.

projectRef: String

productRef and projectRef are exclusive parameters. One or the other must be added. Not both at the same time

In order for the configurator to show the desired project, it is necessary to specify the project reference.

The reference of each project is the one returned in the onFinish callback

This parameter can be specified:

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

projectToken: String

projectToken is required only if projectRef is defined

In order for the configurator to show the desired project, it is necessary to specify the project token.

The token of each project is the one returned in the onFinish callback

Optional Parameters

modal: Boolean = true

As we said 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 behavior, the modal parameter is defined (by default true).

modalWidth: String = "100vw"

By default, the configurator appears in 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.

This parameter only has an effect when the modal parameter is true

modalHeight : String = "100vh"

Similar to modalWidth, controls the height of the popup 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.

This parameter only has an effect when the modal parameter is true

containerId: String

Defines the id of the HTML element that will be the container for the configurator.

This parameter only has an effect when the modal parameter is false

iframeWidth : String = "100%"

Once we have defined the id of the container element, we 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.

This parameter only has an effect when the modal parameter is false

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.

One of the most common cases is to adjust the height of the iframe according to the height of the parent element. This can be done as follows:

• iframeHeight: "auto" is defined.
• display: flex is added to the style of the container element.

This parameter only has an effect when the modal parameter is false

boxParams: Object

The boxParams parameter (Object type) is in charge of collecting the default variable values of the box, setting the variable reference as key and the desired number or option reference as value.

The variable and option references will be those specified in the briefing during the setup phase of the configurator.

If the box had the following variables defined:

• length: length in mm
• breadth: width in mm
• height: height in mm
• color: cardboard color on each side ["raw-raw", "white-raw", "white-white"]
• flute: cardboard thickness ["E", "P", "B", "C", "EB", "BC"]

We could pass the boxParams parameter with the following object

{
 length: 320,
 breadth: 240,
 height: 160,
 color: "white-raw",
 flute: "B"
}

to assign default values to the parametric boxes variables. For example to make the box appear with certain dimensions or material.

Another very common case are fixed boxes created from parametric models. A single parametric box is created (with the variables hidden from the user) and then in the integration, the measurements of the fixed box are passed.

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.

language: "es",

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.

disableForm: true,

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.

hiddenSidebar: true,

Event Parameters

onSave: Function

When the configuration is saved, this function is executed.

The data returned is the same as in "onFinish: Function", except for file related data, which is not generated as the project has not yet been finished.

onSave: data => console.log("Configurator data", data),

function onSaveHandler(data) {
 console.log("Configurator data", data);
}

// ...

onSave: onSaveHandler,

onFinish: Function

Once the user completes the configuration, the data is saved on the Instabox leads page, but it may be interesting to collect the data, either to show a summary, calculate a price, save 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.

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 summary 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.
• sourceFiles: url of the .zip file containing the original graphics uploaded by the user. This value will not be returned if the user has not applied any graphics to the product.
• dieline: url of the .zip file containing a dieline (.pdf file) for each part of the box.
• projectRef: Project reference to open the project or use it in the REST API.
• projectToken: Project token to open the project or use it in the REST API.
• config: JavaScript object that contains the variables, options, and other configuration data.

Like the product reference, the references of the variables, options and dielines 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",
 "sourceFiles": "https://example.instabox3d.com/files/source_files.zip",
 "dieline": "https://example.instabox3d.com/files/dieline.zip",
 "projectRef": "123456",
 "projectToken": "WbeBXfLqxc4fyFii_Ct26mytocWt-wqh-hHhkYWt0vk",
 "config": {
  "title": "Product title",
  "variables": {
   "variableReference1": {
    "name": {
     "en": "Variable 1",
     "es": "Variable 1"
    },
    "value": 100
   },
   "variableReference2": {
    "name": {
     "en": "Variable 1",
     "es": "Variable 2"
    },
    "value": 200
   },
   "_keys": ["variableReference1", "variableReference2"]
  },
  "options": {
   "selectorReference1": {
    "name": {
     "en": "Selector 1",
     "es": "Selector 1"
    },
    "selected": {
     "ref": "optionReference2",
     "name": {
      "en": "Option 2",
      "es": "Opción 2"
     }
    }
   },
   "selectorReference2": {
    "name": {
     "en": "Selector 2",
     "es": "Selector 2"
    },
    "selected": {
     "ref": "optionReference4",
     "name": {
      "en": "Option 4",
      "es": "Opción 4"
     }
    }
   },
   "_keys": ["selectorReference1", "selectorReference2"]
  },
  "dielines": {
   "dielineReference1": {
    "name": {
     "en": "Dieline 1",
     "es": "Troquel 1"
    },
    "out": {
     "artwork": true,
     "artworkPdf": "https://example.instabox3d.com/files/dieline1_artwork_out.pdf",
     "combinedPdf": "https://example.instabox3d.com/files/dieline1_combined_out.pdf"
    },
    "in": {
     "artwork": false
    },
    "dieline": "https://example.instabox3d.com/files/dieline1_dieline.pdf"
   },
   "dielineReference2": {
    "name": {
     "en": "Dieline 2",
     "es": "Troquel 2"
    },
    "out": {
     "artwork": false
    },
    "in": {
     "artwork": true,
     "artworkPdf": "https://example.instabox3d.com/files/dieline2_artwork_in.pdf",
     "combinedPdf": "https://example.instabox3d.com/files/dieline2_combined_in.pdf"
    },
    "dieline": "https://example.instabox3d.com/files/dieline2_dieline.pdf"
   },
   "_keys": ["dielineReference1", "dielineReference2"]
  },
  "form": {
   "fieldReference1": {
    "name": {
     "en": "Field",
     "es": "Campo"
    },
    "type": "text",
    "value": "Example"
   },
   "fieldReference2": {
    "name": {
     "en": "Email",
     "es": "Email"
    },
    "type": "email",
    "value": "[email protected]"
   },
   "fieldReference3": {
    "name": {
     "en": "Number",
     "es": "Número"
    },
    "type": "number",
    "value": "123"
   },
   "fieldReference4": {
    "name": {
     "en": "Selector",
     "es": "Selector"
    },
    "type": "select",
    "selected": {
     "ref": "optionReference1",
     "name": {
      "en": "Option 1",
      "es": "Opción 1"
     }
    }
   },
   "fieldReference5": {
    "name": {
     "en": "Multiple Selector",
     "es": "Selector Múltiple"
    },
    "type": "multiple-select",
    "selected": [
     {
      "ref": "optionReference2",
      "name": {
       "en": "Option 2",
       "es": "Opción 2"
      }
     },
     {
      "ref": "optionReference4",
      "name": {
       "en": "Option 4",
       "es": "Opción 4"
      }
     }
    ]
   },
   "_keys": [
    "fieldReference1",
    "fieldReference2",
    "fieldReference3",
    "fieldReference4",
    "fieldReference5"
   ]
  }
 }
}

If you do not receive the data with this structure, you should contact us to activate the latest output version.

onFinish: data => console.log("Configurator data", data),

function onFinishHandler(data) {
 console.log("Configurator data", data);
}

// ...

onFinish: onFinishHandler,

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, ref: "optionReference"},
  {name: "Material 2", value: 1, ref: "optionReference"},
  {name: "Material 3", value: 2, ref: "optionReference"}
 ],
 publicName: "Material",
 ref: "variableReference",
 type: "SelectVariable",
 value: 0
}

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

onChange: data => console.log("Box Variables", data),

function onChangeHandler(data) {
 console.log("Box Variables", data);
}

// ...

onChange: onChangeHandler,

onArtworkOpened: Function

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

onArtworkOpened: () => console.log("2D Editor has been opened"),

function onArtworkOpenedHandler() {
 console.log("2D Editor has been opened");
}

// ...

onArtworkOpened: onArtworkOpenedHandler,

onArtworkClosed: Function

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

onArtworkClosed: () => console.log("2D Editor has been closed"),

function onArtworkClosedHandler() {
 console.log("2D Editor has been closed");
}

// ...

onArtworkClosed: onArtworkClosedHandler,

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.

onError: error => console.log("Invalid box", error),

function onErrorHandler(error) {
 console.log("Invalid box", error);
}

// ...

onError: onErrorHandler,

Other parameters

debug: Boolean = false

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.

debug: true,

Methods

open(params, onReady, onError)

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

In the open method it is also possible to modify or overwrite any previously defined parameter.

instabox.open(params);

The open method allows you to handle asynchronous loading and error handling. It is possible to do it through callbacks or promises as shown below:

function onReady() {
 console.log("InstaBox is ready");
}
function onError(error) {
 console.log("InstaBox Error", error);
}

// callbacks
instabox.open({ productRef: "fefco-0201" }, onReady, onError);

// promises
instabox.open({ productRef: "fefco-0201" }).then(onReady).catch(onError);

// promises with async/await
try {
 await instabox.open({ productRef: "fefco-0201" });
 onReady();
} catch (error) {
 onError(error);
}

close()

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.

instabox.close();

changeBoxParams(config)

The changeBoxParams method works similarly to the boxParams parameter, and can be executed by passing an object that will have the variable reference as key and the desired number or option reference as value.

The variable and option references will be those specified in the briefing during the setup phase of the configurator.

If the box had the following variables defined:

• length: length in mm
• breadth: width in mm
• height: height in mm
• color: cardboard color on each side ["raw-raw", "white-raw", "white-white"]
• flute: cardboard thickness ["E", "P", "B", "C", "EB", "BC"]

We could send the following object with the changeBoxParams method to change the values dynamically:

{
 length: 320,
 breadth: 240,
 height: 160,
 color: "white-raw",
 flute: "B"
}

instabox.changeBoxParams(params);

openArtwork(dielineReference)

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

instabox.openArtwork();

closeArtwork()

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

instabox.closeArtwork();

saveConfiguration(externalData)

The saveConfiguration method can be used to save the configuration at any time.

When the configuration is saved, production files are not generated.
To generate the production files it is necessary to finish the project. It can be done synchronously using the finishConfiguration() method or it can be done asynchronously with the configurator closed through InstaBox API (for example, once the product has been purchased)

It is possible to pass an object with the structure shown in finishConfiguration() section to add external data that will be displayed in the project data sheet on the projects page.

instabox.saveConfiguration(externalData);

finishConfiguration(externalData)

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

When the configuration is finished, the production files are generated (this may take some time) and the project is finalized so it cannot be edited again.
This can also be done asynchronously with the configurator closed through InstaBox API (for example, once the product has been purchased)

It is possible to pass an object with the structure shown below to add external data that will be displayed in the project data sheet on the projects page.

Rules:

• name (required): can only be a string in case of non-translation and an object (following the structure shown below) in case of translation
• value (required): can only be a string, number, or boolean
• _keys (optional): can be used to define a specific order

{
 key1: {
  name: "Name 1",
  value: "test"
 },
 key2: {
  name: "Name 2",
  value: 12345
 },
 key3: {
  name: "Name 3",
  value: true
 },
 _keys: ["key1", "key2", "key3"]
}

{
 key1: {
  name: { es: "Nombre 1", en: "Name 1" },
  value: "test"
 },
 key2: {
  name: { es: "Nombre 2", en: "Name 2" },
  value: 12345
 },
 key3: {
  name: { es: "Nombre 3", en: "Name 3" },
  value: true
 },
 _keys: ["key1", "key2", "key3"]
}

There are some special keys that have a specific use:

• title: if defined, sets the project title. The "name" key in this case is ignored.

instabox.finishConfiguration(externalData);

getIframe()

The getIframe method can be used to get the iframe for example to add some styling

instabox.getIframe();

Code examples

Things to consider

Different codes are shown below as an example in order to serve as a template and mark a starting point. Code snippets from different examples can be used.

It is important that the values of client and productRef are modified with the values of your configurator. More information can be found in the "Required Parameters" section.

In these examples the value of client will be "trial" and the value of productRef will be "fefco-0201" .

If you want to do integration tests and your configurator is not yet available, you can contact us through [email protected] and ask us for access to the trial.

Example as modal at 80% of the screen

Adding these parameters should show the configurator as a pop-up window at 80% of the screen.

<!-- Include the script -->
<script src="https://www.instabox3d.com/integration-v4.1.0.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("Configurator data", data),
 });
</script>

Example inside an HTML 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 shown below, and 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.

<!-- Container HTML 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/integration-v4.1.0.js"></script>

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

Example with buttons to open and close

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 instantiation time, but will be passed at the time of executing the open method.

<!-- Button that executes the openInstabox function to open the configurator -->
<button onclick="openInstabox()" id="open-btn">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/integration-v4.1.0.js"></script>

<script>
 function openInstabox() {
  instabox.open(
   { productRef: "fefco-0201" },
   onInstaboxOpen,
   onInstaboxError
  );
 }

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

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

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

 function onInstaboxFinish(output) {
  console.log("Instabox Output", output);
  document.getElementById("close-btn").style.display = "none";
 }

 // Instantiation without productRef so that it does not open the configurator automatically
 const instabox = new Instabox3D({
  client: "trial",
  modalWidth: "80vw",
  modalHeight: "80vh",
  onFinish: onInstaboxFinish,
 });
 
</script>

Two-way integration example

In this example:

• An input is added to define the length externally to the configurator
• The current values of the box are collected to display them in the input
• A button is added to finish the configuration externally to the configurator
• A button is added to open and close the 2D editor externally to the configurator

<!-- Container HTML 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/integration-v4.1.0.js"></script>

<script>
 function changeBoxLength(input) {
  instabox.changeBoxParams({
   length: input.value
  });
 }

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

 function onBoxError(error) {
  console.log("Invalid box", error);
 }

 function openArtworkEditor() {
   instabox.openArtwork();
  }

 function closeArtworkEditor() {
  instabox.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;
 }

 function finishConfiguration() {
  instabox.finishConfiguration();
 }

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

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

Migrating from v4.0.0 to v4.1.0

Include the new script

Replace the old script with the one shown below:

<script src="https://www.instabox3d.com/integration-v4.1.0.js"></script>

New parameters

You can now use the projectRef and projectToken parameters to open the project and edit a previously created configuration.
For more information see the section "projectRef: String" and "projectToken: String"

New output data in onFinish callback

The output data now includes projectRef and projectToken.
For more information see the section "onFinish: Function"

New saveConfiguration method and onSave event

You can now use the saveConfiguration method to save the project without closing the configurator. You can also use the onSave event to handle this action and collect the returned data.
For more information see the section "saveConfiguration()" and "onSave: Function"

Additional data to the project

You can now add additional information to the project, for example, the title or other data such as the user ID or the order ID.
For more information see the section "finishConfiguration()" and "saveConfiguration()"

Contact

If you have any problems during the integration or migration process, do not hesitate to contact us through [email protected]