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.
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>
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>
The parameters establish which product is going to be displayed and the appearance of the configurator.
There are 3 types of parameters:
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.
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.
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:
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).
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
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
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
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
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:
This parameter only has an effect when the modal parameter is false
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",
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,
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,
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:
Like the product reference, the options and parts names will be those specified in the briefing during the setup phase of the configurator.
Example of data returned:{ 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"], } } }Example creating the function directly in the configuration object
onFinish: data => console.log("Configurator data", data),Example defining the function and then adding it to the configuration object
function onFinishHandler(data) {
console.log("Configurator data", data);
}
// ...
onFinish: onFinishHandler,
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.
Example of data returned:{ 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, }, ], }Example creating the function directly in the configuration object
onChange: data => console.log("onChange data", data),Example defining the function and then adding it to the configuration object
function onChangeHandler(data) {
console.log("onChange data", data);
}
// ...
onChange: onChangeHandler,
When an option group is selected, this function is executed passing the option group ID as an argument.
Example creating the function directly in the configuration objectonOptionGroupSelected: id => console.log("Option Group selected", id),Example defining the function and then adding it to the configuration object
function onOptionGroupSelectedHandler(id) {
console.log("Option Group selected", id);
}
// ...
onOptionGroupSelected: onOptionGroupSelectedHandler,
When a part group is selected, this function is executed passing the part group ID as an argument.
Example creating the function directly in the configuration objectonPartGroupSelected: id => console.log("Part Group selected", id),Example defining the function and then adding it to the configuration object
function onPartGroupSelectedHandler(id) {
console.log("Part Group selected", id);
}
// ...
onPartGroupSelected: onPartGroupSelectedHandler,
When the 2D editor is opened, this function is executed
Example creating the function directly in the configuration objectonArtworkOpened: () => console.log("2D Editor has been opened"),Example defining the function and then adding it to the configuration object
function onArtworkOpenedHandler() {
console.log("2D Editor has been opened");
}
// ...
onArtworkOpened: onArtworkOpenedHandler,
When the 2D editor is closed, this function is executed
Example creating the function directly in the configuration objectonArtworkClosed: () => console.log("2D Editor has been closed"),Example defining the function and then adding it to the configuration object
function onArtworkClosedHandler() {
console.log("2D Editor has been closed");
}
// ...
onArtworkClosed: onArtworkClosedHandler,
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,
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.
The method is available in the variable created at instantiation timeinstapack.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); }
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.
The method is available in the variable created at instantiation timeinstapack.close();
The selectOptionGroup method can be used to change the selected option group, passing the option group ID as an argument.
The method is available in the variable created at instantiation timeinstapack.selectOptionGroup(optionGroupId);
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.
The method is available in the variable created at instantiation timeinstapack.selectOption(optionGroupId, optionId);
The selectPartGroup method can be used to change the selected part group, passing the part group ID as an argument.
The method is available in the variable created at instantiation timeinstapack.selectPartGroup(partGroupId);
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.
The method is available in the variable created at instantiation timeinstapack.selectMaterial(partGroupId, materialId);
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.
The method is available in the variable created at instantiation timeinstapack.changeColor(partGroupId, color);
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);
The closeArtwork method can be used to close the 2D editor.
The method is available in the variable created at instantiation timeinstapack.closeArtwork();
The finishConfiguration method can be used to end the configuration at any time.
The method is available in the variable created at instantiation timeinstapack.finishConfiguration();
The getIframe method can be used to get the iframe for example to add some styling
The method is available in the variable created at instantiation timeinstapack.getIframe();
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.
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>
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:
<!-- 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>
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 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>
Replace the old script with the one shown below:
<script src="https://www.instapack3d.com/integration-v3.0.0.js"></script>
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();
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)"
If you have any problems during the integration or migration process, do not hesitate to contact us through [email protected]