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.
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-v3.3.0.js"></script>
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>
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 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.
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.
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
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.
The variable names will be those specified in the briefing during the setup phase of the configurator.
If the box had the following variables defined:
We could pass the boxParams parameter with the following object
boxParams: { l: 320, b: 270, h: 150 },
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.
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",
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,
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 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:
Like the product reference, the variable 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.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", dieline: "https://example.instabox3d.com/files/dieline.zip", config: { variable1: 300, variable2: 200, variable3: 100 } }Example creating the function directly
onFinish: data => console.log("Configurator data", data),Example defining the function and then passing the name in the parameter
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 parameter an array with the variables of the box, including the current values and available values in case of selection variables.
Example of a selection variable:{ name: "mat", options: [ {name: "Material 1", value: 0} {name: "Material 2", value: 1} {name: "Material 3", value: 2} ], publicName: "Material", type: "SelectVariable", value: 0 }Example of a numerical variable:
{ name: "l", publicName: "Length", type: "Variable", value: 350 }Example creating the function directly
onChange: data => console.log("Box Variables", data),Example defining the function and then passing the name in the parameter
function onChangeHandler(data) {
console.log("Box Variables", data);
}
// ...
onChange: onChangeHandler,
When the 2D editor is opened, this function is executed
Example creating the function directlyonArtworkOpened: () => console.log("2D Editor has been opened"),Example defining the function and then passing the name in the parameter
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 directlyonArtworkClosed: () => console.log("2D Editor has been closed"),Example defining the function and then passing the name in the parameter
function onArtworkClosedHandler() {
console.log("2D Editor has been closed");
}
// ...
onArtworkClosed: onArtworkClosedHandler,
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.
Example creating the function directlyonError: error => console.log("Invalid box", error),Example defining the function and then passing the name in the parameter
function onErrorHandler(error) {
console.log("Invalid box", error);
}
// ...
onError: onErrorHandler,
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 timeinstabox.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); }
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.
The method is available in the variable created at instantiation timeinstabox.close();
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.
If the box had the following variables defined:
We could send the following object with the changeBoxParams method to change the length value dynamically:
{ l: 320 }The method is available in the variable created at instantiation time
instabox.changeBoxParams(params);
The openArtwork method can be used to open the 2D editor, where the user can upload and place graphics on the box.
The method is available in the variable created at instantiation timeinstabox.openArtwork();
The closeArtwork method can be used to close the 2D editor.
The method is available in the variable created at instantiation timeinstabox.closeArtwork();
The finishConfiguration method can be used to end the configuration at any time.
The method is available in the variable created at instantiation timeinstabox.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 timeinstabox.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 "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.
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-v3.3.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>
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.instabox3d.com/integration-v3.3.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>
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-v3.3.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>
In this example:
<!-- 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-v3.3.0.js"></script> <script> function changeBoxLength(input) { instabox.changeBoxParams({ l: 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>
Replace the old script with the one shown below:
<script src="https://www.instabox3d.com/integration-v3.3.0.js"></script>
It is no longer necessary to check instabox.isReady before executing a method.
Now the methods are available directly in the variable created at instantiation time
// Before if (instabox.isReady) { instabox.configurator.open(); } // Now instabox.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]