Introduction

How does it work?

The integration is done by creating a new instance of the "Instapack3D" 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.instapack3d.com/integration-v3.0.0.js"></script>

Instantiation

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

<script>
 // Create the instance
 const instapack = new Instapack3D({
  // 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 instapack = new Instapack3D({
 // parameters
});

and also in the open method.

instapack.open({
 // parameters
});

Static parameters such as the client and optional or event parameters are usually defined at the time of instantiation. The productRef is 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 Instapack 3D

If your Instapack 3D URL is "https://my-company.instapack3d.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

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.

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

language: String

If your InstaPack 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 InstaPack 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

onFinish: Function

Once the user completes the configuration, the data is saved on the Instapack 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 an argument.

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 files uploaded by the user.
• config: JavaScript object including options (only in case of Instapack 3D Pro) and parts with their respective names and values chosen by user.

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

{
 title: "Product title",
 image: "https://example.instapack3d.com/files/image.png",
 instaviewer: "https://example.instapack3d.com/viewer/example",
 pdf: "https://example.instapack3d.com/files/summary.pdf",
 artwork: "https://example.instapack3d.com/files/artwork.zip",
 sourceFiles: "https://example.instapack3d.com/files/source.zip",
 config: {
  options: {
   selectRef: {
    name: { en: "Name", es: "Nombre"},
    selected: {
     ref: "optionRef",
     name: { en: "Name", es: "Nombre"}
    }
   },
   _keys: ["selectRef"]
  },
  parts: {
   partRef: {
    name: { en: "Name", es: "Nombre"},
    appearance: {
     ref: "AppearanceRef",
     name: { en: "Name", es: "Nombre"}
    },
    artwork: true,
    color: "#ffffff",
    artworkPdf: "https://example.instapack3d.com/files/part-artwork.pdf",
    combinedPdf: "https://example.instapack3d.com/files/part-combined.pdf",
   },
   _keys: ["partRef"]
  },
  form: {
   fieldRef: {
    name: { en: "Name", es: "Nombre"},
    value: "Field value"
   },
   _keys: ["fieldRef"],
  }
 }
}

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 an argument a JavaScript object with the options and parts, including the current values and the available values.

{
 optionGroups: [
  {
   id: "Group1",
   name: "Group 1",
   selected: true,
   options: [
    {
     id: "Option1",
     name: "Option 1",
     selected: false,
    },
    {
     id: "Option2",
     name: "Option 2",
     selected: true,
    },
   ],
  },
  {
   id: "Group2",
   name: "Group 2",
   selected: false,
   options: [
    {
     id: "Option3",
     name: "Option 3",
     selected: false,
    },
    {
     id: "Option4",
     name: "Option 4",
     selected: true,
    },
   ],
  },
 ],
 partGroups: [
  {
   id: "Part1",
   name: "Part 1",
   selected: true,
   materials: [
    {
     id: "Material1",
     name: "Material 1",
     selected: true,
    },
    {
     id: "Material2",
     name: "Material 2",
     selected: false,
    },
    {
     id: "Material3",
     name: "Material 3",
     selected: false,
    },
   ],
   color: "#ffffff",
   artwork: true,
  },
  {
   id: "Part2",
   name: "Part 2",
   selected: false,
   materials: [
    {
     id: "Material4",
     name: "Material 4",
     selected: true,
    },
    {
     id: "Material5",
     name: "Material 5",
     selected: false,
    },
   ],
   color: "#ffffff",
   artwork: false,
  },
 ],
}

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

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

// ...

onChange: onChangeHandler,

onOptionGroupSelected: Function

When an option group is selected, this function is executed passing the option group ID as an argument.

onOptionGroupSelected: id => console.log("Option Group selected", id),

function onOptionGroupSelectedHandler(id) {
 console.log("Option Group selected", id);
}

// ...

onOptionGroupSelected: onOptionGroupSelectedHandler,

onPartGroupSelected: Function

When a part group is selected, this function is executed passing the part group ID as an argument.

onPartGroupSelected: id => console.log("Part Group selected", id),

function onPartGroupSelectedHandler(id) {
 console.log("Part Group selected", id);
}

// ...

onPartGroupSelected: onPartGroupSelectedHandler,

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,

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.

instapack.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("InstaPack is ready");
}

function onError(error) {
 console.log("InstaPack Error", error);
}

// callbacks
instapack.open({ productRef: "aerosol" }, onReady, onError);

// promises
instapack.open({ productRef: "aerosol" }).then(onReady).catch(onError);

// promises with async/await
try {
 await instapack.open({ productRef: "aerosol" });
 onReady();
} catch (error) {
 onError(error);
}

close()

If once the configurator is opened 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.

instapack.close();

selectOptionGroup(optionGroupId)

The selectOptionGroup method can be used to change the selected option group, passing the option group ID as an argument.

instapack.selectOptionGroup(optionGroupId);

selectOption(optionGroupId, optionId)

The selectOption method can be used to change the selected option, passing the option group ID as the first argument and the option ID as the second.

instapack.selectOption(optionGroupId, optionId);

selectPartGroup(partGroupId)

The selectPartGroup method can be used to change the selected part group, passing the part group ID as an argument.

instapack.selectPartGroup(partGroupId);

selectMaterial(partGroupId, materialId)

The selectMaterial method can be used to change the selected material (appearance of a specific part), by passing the part group ID as the first argument and the material ID as the second.

instapack.selectMaterial(partGroupId, materialId);

changeColor(partGroupId, color)

The changeColor method can be used to change the part color, by passing the part group ID as the first argument and the color (in hexadecimal format) as the second.

instapack.changeColor(partGroupId, color);

openArtwork(partGroupId)

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

instapack.openArtwork(partGroupId);

closeArtwork()

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

instapack.closeArtwork();

finishConfiguration()

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

instapack.finishConfiguration();

getIframe()

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

instapack.getIframe();

Example codes

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 "demo" and the value of productRef will be "aerosol" .

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.instapack3d.com/integration-v3.0.0.js"></script>

<script>
 // Create the instance
 const instapack = new Instapack3D({
  client: "demo",
  productRef: "aerosol",
  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.instapack3d.com/integration-v3.0.0.js"></script>

<script>
 // Create the instance 
 const instapack = new Instapack3D({
  client: "demo",
  productRef: "aerosol",
  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 openInstapack function to open the configurator -->
<button onclick="openInstapack()" id="open-btn">Open configurator</button>

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

<!-- Include the script -->
<script src="https://www.instapack3d.com/integration-v3.0.0.js"></script>

<script>
 function openInstapack() {
  instapack.open(
   { productRef: "aerosol" },
   onInstapackOpen,
   onInstapackError
  );
 }

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

 function onInstapackError(error) {
  console.log("InstaPack Error", error);
 }

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

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

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

Two-way integration example

Two-way integration is the most advanced and flexible integration where you can disable the configurator sidebar to use it as a 3D viewer and implement the layout directly on your website.

This example is not a fully functional implementation. It is a template with the necessary methods and events as a starting point.

<div style="display: flex; gap: 1rem">
 <!-- Container HTML element with id and style (including display: flex;) -->
 <div
  id="configurator-container"
  style="width: 100%; height: 75vh; border: 1px solid black; display: flex"
 ></div>
 <div style="width: 30%"><h3>Your custom layout</h3></div>
</div>

<!-- Include the script -->
<script src="https://www.instapack3d.com/integration-v3.0.0.js"></script>

<script>
 /**
  * The following functions are examples for sending data to the InstaPack when an action occurs in your layout.
  */

 function onSelectOption() {
  // get the option group ID and the option ID

  instapack.selectOption(optionGroupId, optionId);
 }

 function onSelectMaterial() {
  // get the part group ID and the material ID

  instapack.selectMaterial(partGroupId, materialId);
 }

 function onChangeColor() {
  // get the part group ID and the hexadecimal color code

  instapack.changeColor(partGroupID, color);
 }

 function onSelectOptionGroup() {
  // get the option group ID

  instapack.selectOptionGroup(optionGroupId);
 }

 function onSelectPartGroup() {
  // get the part group ID

  instapack.selectPartGroup(partGroupId);
 }

 function onClickOpenArtwork() {
  // get part group ID if needed

  instapack.openArtwork(partGroupID);
 }

 function onClickCloseArtwork() {
  instapack.closeArtwork();
 }

 function onClickFinish() {
  instapack.finishConfiguration();
 }

 /**
  * The following functions are used to handle InstaPack events and update your layout
  */

 function onInstapackOpen() {
  console.log("InstaPack Opened");
 }

 function onInstapackError(error) {
  console.log("InstaPack Error", error);

  // show some message to the user
 }

 function onChange(configuration) {
  console.log("Configuration changed", configuration);

  // update your layout with the options, materials and colors available
 }

 function onOptionGroupSelected(id) {
  console.log("Option group selected", id);

  // update the selected option group in your layout if needed
 }

 function onPartGroupSelected(id) {
  console.log("Part group selected", id);

  // update the selected part group in your layout if needed
 }

 function onArtworkOpened() {
  console.log("2D Editor opened");

  // update the artwork button in your layout if needed
 }

 function onArtworkClosed() {
  console.log("2D Editor closed");

  // update the artwork button in your layout if needed
 }

 function onFinish(output) {
  console.log("Instapack Output", output);

  // handle the InstaPack outputs.
  // E.g: show a configuration summary, show a quotation form, add the data to the checkout, etc.
 }

 // Instantiation without productRef so you can use the open method to handle onInstapackOpen and onInstapackError
 const instapack = new Instapack3D({
  client: "demo",
  debug: true,
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
  hiddenSidebar: true,
  onChange,
  onOptionGroupSelected,
  onPartGroupSelected,
  onArtworkOpened,
  onArtworkClosed,
  onFinish,
 });

 // Open the InstaPack
 instapack.open({ productRef: "aerosol" }, onInstapackOpen, onInstapackError);
</script>

Migrating from v2.1.0 to v3.0.0

Include the new script

Replace the old script with the one shown below:

<script src="https://www.instapack3d.com/integration-v3.0.0.js"></script>

Methods

It is no longer necessary to check instapack.isReady before executing a method.

Now the methods are available directly in the variable created at instantiation time

// Before
if (instapack.isReady) {
 instapack.configurator.open();
}
// Now
instapack.open();

Asynchronous loading and error handling

Now asynchronous loading and error handling is much easier (and also faster) as there is only one asynchronous process instead of two.

The only thing to do is not pass the productRef parameter at instantiation time and use the open method, either directly after instantiation (to open the configurator at loading the page) or pressing a button.

For more information see the section "open(params, onReady, onError)"

Contact

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