Introducción

¿Cómo funciona?

La integración se realiza creando una nueva instancia de la clase "Instabox3D", pasando un objeto con algunos parámetros de configuración. El configurador aparecerá en un iframe, dependiendo de dichos parámetros, como ventana emergente o dentro de un elemento HTML ya existente en la página web.

Incluir el script

La integración requiere la inclusión del siguiente script (como se muestra a continuación) cerca del final de sus páginas HTML.

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

Instanciación

Para crear la instancia de la clase "Instabox3D" escribimos el siguiente código:

<script>
 // Crear la instancia
 const instabox = new Instabox3D({
  // incluiremos los parámetros aquí
 });
</script>

Parámetros

Los parámetros establecen que producto se va a mostrar y el aspecto del configurador.

Hay 3 tipo de parámetros:

• Parámetros obligatorios: Son necesarios para abrir el configurador
• Parámetros opcionales: Definen de que manera se va a mostrar el configurador.
• Parámetros de eventos: Definen eventos para poder realizar acciones cuando algo pasa dentro del configurador

Estos parámetros se pueden pasar en el momento de la instanciación

const instabox = new Instabox3D({
 // parámetros
});

y también en el método open.

instabox.open({
 // parámetros
});

Por norma general, en el momento de la instanciación se definen los parámetros estáticos como por ejemplo el client y los parámetros opcionales o de evento. En el método open, se define el productRef y los boxParams.

En el método open también es posible modificar o sobrescribir algún parámetro definido anteriormente.

Parámetros obligatorios

client: String

El primer parámetro que veremos hace referencia al nombre del cliente.

El valor debe ser el nombre del subdominio en el que esté su Instabox 3D

Si la URL de su Instabox 3D es "https://mi-empresa.instabox3d.com", el valor de este parámetro será "mi-empresa".

Suele ser el nombre de la empresa, en minúsculas y sustituyendo los espacios por guiones en caso de que los haya.

productRef: String

Para que el configurador muestre el producto deseado es necesario especificar la referencia del producto.

La referencia de cada producto es la que se haya especificado en el briefing durante la fase de setup del configurador.

Este parámetro se puede especificar:

• En el momento de la instanciación. En cuyo caso el configurador se abrirá mostrando el producto especificado.
• En la ejecución del método open (explicado en la sección de métodos). En cuyo caso el configurador no se abrirá hasta el momento de la ejecución del mismo.

Parámetros opcionales

modal: Boolean = true

Como hemos dicho anteriormente en la introducción, el configurador puede aparecer como una ventana emergente o dentro de un elemento HTML de la página web.

Para controlar este comportamiento se define el parámetro modal (por defecto true).

modalWidth: String = "100vw"

Por defecto el configurador aparece a pantalla completa, porque el valor por defecto de modalWidth es "100vw".

Bastaría con asignar en una cadena de texto (siguiendo la sintaxis de CSS) el valor deseado para cambiar la anchura.

Este parámetro solo tiene efecto cuando el parámetro modal es true

modalHeight : String = "100vh"

Similar a modalWidth, controla la altura de la ventana emergente con un valor por defecto de "100vh".

De nuevo, bastaría con asignar en una cadena de texto (siguiendo la sintaxis de CSS) el valor deseado para cambiar la altura.

Este parámetro solo tiene efecto cuando el parámetro modal es true

containerId: String

Define el id del elemento HTML que servirá de contenedor para el configurador.

Este parámetro solo tiene efecto cuando el parámetro modal es false

iframeWidth : String = "100%"

Una vez hemos definido el id del elemento contenedor, se puede definir el tamaño del configurador relativo a él.

Por defecto el valor es "100%" por lo que ocupará el total del ancho del elemento padre.

Bastaría con asignar en una cadena de texto (siguiendo la sintaxis de CSS) el valor deseado para cambiar la anchura relativa al elemento contenedor.

Este parámetro solo tiene efecto cuando el parámetro modal es false

iframeHeight : String = "600px"

Similar a iframeWidth, iframeHeight controla la altura del configurador en relación al elemento contenedor.

Por defecto el valor es "600px" por lo que ocupará 600 píxeles de altura.

Bastaría con asignar en una cadena de texto (siguiendo la sintaxis de CSS) el valor deseado para cambiar la altura relativa al elemento contenedor.

Uno de los casos más comunes es el de ajustar la altura del iframe según la altura del elemento padre. Esto se puede hacer de la siguiente manera:

• Se define iframeHeight: "auto".
• Se le añade display: flex; al estilo del elemento contenedor.

Este parámetro solo tiene efecto cuando el parámetro modal es false

boxParams: Object

El parámetro boxParams (de tipo objeto) es el encargado de recoger los valores por defecto de las variables de la caja, estableciendo el nombre de la variable como clave y su valor deseado.

Los nombres de las variables serán los que se hayan especificado en el briefing durante la fase de setup del configurador.

Si la caja tuviese definidas las siguientes variables:

• l: largo en mm
• b: ancho en mm
• h: alto en mm

Podríamos pasar el parámetro boxParams con el siguiente objeto

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

para asignar los valores por defecto a las variables de cajas paramétricas. Por ejemplo para hacer que la caja aparezca con unas medidas o un material determinado.

Otro caso muy común es el de las cajas fijas creadas a partir de modelos paramétricos, es decir, se crea una única caja paramétrica (con las variables ocultas al usuario) y luego en la integración se pasan las medidas de la caja fija en cuestión.

language: String

Si su InstaBox tiene múltiples idiomas, puede forzar que el configurador aparezca en alguno de esos idiomas. Simplemente escriba el código de idioma (dos caracteres), por ejemplo "en" para inglés o "es" para español.

language: "es",

disableForm: Boolean

Si ha elegido la opción de formulario, verá que al hacer la integración aparece dicho formulario.

Esto no siempre es útil, por ejemplo, si utiliza su InstaBox como herramienta interna (con formulario) y quiere integrarlo también en su e-commerce, en este segundo caso el formulario no tendría sentido y cortaría el flujo correcto de e-commerce. En este caso se puede utilizar el parámetro disableForm para desactivar el formulario en la integración.

disableForm: true,

hiddenSidebar: Boolean

Si desea crear una integración única agregando los campos y botones a su web, puede deshabilitar la barra lateral del configurador utilizando hiddenSidebar.

hiddenSidebar: true,

Parámetros de eventos

onFinish: Function

Una vez el usuario finaliza la configuración se guardan los datos en la página de leads del Instabox, pero puede ser interesante recoger los datos, ya sea para mostrar un resumen, calcular un precio, guardar en base de datos, etc.

Para eso existe el parámetro onFinish, (de tipo función) que se ejecuta cuando el usuario finaliza la configuración pasando como parámetro un objeto JavaScript con los datos de dicha configuración.

El objeto contendrá los siguientes valores:

• title: título o nombre del producto
• image: url de la imagen del producto personalizado
• instaviewer: url de la visualización 3D del producto personalizado
• pdf: url del pdf con la información elegida en la configuración
• artwork: url del archivo .zip que contiene las gráficas originales y un archivo .pdf por cada parte (a la que el usuario haya aplicado al menos una gráfica) con la posición de dichos archivos. Este valor no será devuelto si el usuario no ha aplicado ninguna gráfica al producto.
• dieline: url del archivo .zip que contiene el troquel (en archivo .pdf) de cada parte de la caja.
• config: objeto JavaScript en el que aparecerá cada variable como una propiedad, acompañada de su valor

Al igual que la referencia del producto, los nombres de las variables serán los que se hayan especificado en el briefing durante la fase de setup del configurador.

{
 title: "Título del producto",
 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
 }
}

onFinish: data => console.log("Datos del configurador", data),

function onFinishHandler(data) {
 console.log("Datos del configurador", data);
}

// ...

onFinish: onFinishHandler,

onChange: Function

Cada vez que el usuario realiza un cambio en la configuración se ejecuta esta función pasando como parámetro un array con las variables de la caja, incluyendo lo valores actuales y valores disponibles en caso de variables de selección.

{
 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
}

onChange: data => console.log("Variables de la caja", data),

function onChangeHandler(data) {
 console.log("Variables de la caja", data);
}

// ...

onChange: onChangeHandler,

onArtworkOpened: Function

Cuando se abre el editor 2D se ejecuta esta función

onArtworkOpened: () => console.log("Se ha abierto el Editor 2D"),

function onArtworkOpenedHandler() {
 console.log("Se ha abierto el Editor 2D");
}

// ...

onArtworkOpened: onArtworkOpenedHandler,

onArtworkClosed: Function

Cuando se cierra el editor 2D se ejecuta esta función

onArtworkClosed: () => console.log("Se ha cerrado el Editor 2D"),

function onArtworkClosedHandler() {
 console.log("Se ha cerrado el Editor 2D");
}

// ...

onArtworkClosed: onArtworkClosedHandler,

onError: Function

Si los valores introducidos no son válidos, el configurador muestra un mensaje de error y se ejecuta esta función pasando ese mensaje de error como parámetro.

onError: error => console.log("Caja no válida", error),

function onErrorHandler(error) {
 console.log("Caja no válida", error);
}

// ...

onError: onErrorHandler,

Otros parámetros

debug: Boolean = false

Si el parámetro debug (por defecto false) es true, imprime en consola los errores que puedan ocurrir durante el proceso de integración.

Resulta muy útil activar este modo durante la fase de desarrollo para detectar posibles problemas, pero es aconsejable desactivarlo en entorno de producción.

debug: true,

Métodos

open(params, onReady, onError)

Para abrir el configurador de forma manual, se ha de ejecutar el método open, pasando como primer argumento un objeto de configuración que contenga el parámetro productRef

En el método open también es posible modificar o sobrescribir algún parámetro definido anteriormente.

instabox.open(params);

El método open permite manejar la carga asíncrona y el tratamiento de errores. Es posible hacerlo mediante callbacks o promesas como se muestra a continuación:

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

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

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

// promesas con async/await
try {
 await instabox.open();
 onReady();
} catch (error) {
 onError(error);
}

close()

Si una vez abierto el configurador queremos dar la opción al usuario de salir sin finalizar, lo más lógico es tener algún tipo de interacción para cerrar el configurador. Esto es posible ejecutando el método close que no recibe ningún argumento.

instabox.close();

changeBoxParams(config)

El método changeBoxParams funciona de forma similar al parámetro boxParams, y se puede ejecutar pasando un objeto que tendrá el nombre de la variable como clave y su valor deseado.

Los nombres de las variables serán los que se hayan especificado en el briefing durante la fase de setup del configurador.

Si la caja tuviese definidas las siguientes variables:

• l: largo en mm
• b: ancho en mm
• h: alto en mm

Podríamos enviar el siguiente objeto con el método changeBoxParams para cambiar el valor del largo dinámicamente:

{
 l: 320
}

instabox.changeBoxParams(params);

openArtwork()

El método openArtwork se puede utilizar para abrir el editor 2D, donde el usuario podrá subir y colocar gráficas sobre la caja.

instabox.openArtwork();

closeArtwork()

El método closeArtwork se puede utilizar para cerrar el editor 2D.

instabox.closeArtwork();

finishConfiguration()

El método finishConfiguration se puede utilizar para finalizar la configuración en cualquier momento.

instabox.finishConfiguration();

getIframe()

El método getIframe se puede utilizar para obtener el iframe por ejemplo para añadir algún estilo

instabox.getIframe();

Códigos de ejemplo

Temas a tener en cuenta

A continuación se muestran diferentes códigos a modo de ejemplo con el fin de servir como template y marcar un punto de partida. Se pueden utilizar trozos de código de diferentes ejemplos.

Es importante que los valores de client y productRef se modifiquen con los valores de su configurador. Puede encontrar más información en la sección "Parámetros obligatorios".

En estos ejemplos el valor de client será "trial" y el valor de productRef será "fefco-0201".

Si quiere hacer pruebas de integración y su configurador aún no está disponible, puede ponerse en contacto a través de [email protected] y pedirnos acceso al trial.

Ejemplo como modal al 80% de la pantalla

Agregando estos parámetros debería verse el configurador como una ventana emergente al 80% de la pantalla.

<!-- Incluir el script -->
<script src="https://www.instabox3d.com/integration-v3.3.0.js"></script>

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

Ejemplo dentro de un elemento HTML

Uno de los casos más comunes es el de ajustar el tamaño del iframe según el tamaño del elemento padre.

Este será el caso en el ejemplo que se muestra a continuación, y en el que:

• No se define iframeWidth porque ya es 100% por defecto.
• Se define iframeHeight: "auto".
• Se añade display: flex; al estilo del elemento contenedor.

<!-- Elemento HTML contenedor con id y estilo (incluido el display: flex;) -->
<div id="configurator-container" style="width: 75vw; height: 75vh; border: 1px solid black; display: flex;"></div>

<!-- Incluir el script -->
<script src="https://www.instabox3d.com/integration-v3.3.0.js"></script>

<script>
 // Crear la instancia 
 const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
  debug: true,
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
  onFinish: data => console.log("Datos del configurador", data),
 });
</script>

Ejemplo con botones para abrir y cerrar

Utilizando los conceptos explicados anteriormente implementaremos la integración con botones para abrir y cerrar el configurador.

En este caso no se pasará el parámetro productRef en el momento de la instanciación, sino que se pasará en el momento de ejecutar el método open.

<!-- Botón que ejecuta la función openInstabox para abrir el configurador -->
<button onclick="openInstabox()" id="open-btn">Abrir configurador</button>

<!-- Botón que ejecuta la función closeInstabox para cerrar el configurador -->
<button onclick="closeInstabox()" id="close-btn" style="position: absolute; top: 1rem; right: 1rem; display: none">
 Cerrar configurador
</button>

<!-- Incluir el 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";
 }

 // Instanciación sin productRef para que no abra el configurador automáticamente
 const instabox = new Instabox3D({
  client: "trial",
  modalWidth: "80vw",
  modalHeight: "80vh",
  onFinish: onInstaboxFinish,
 });
 
</script>

Ejemplo de integración bidireccional

En este ejemplo:

• Se añade un input para definir el largo de forma externa al configurador
• Se recogen los valores actuales de la caja para mostrarlos en el input
• Se añade un botón para finalizar la configuración de forma externa al configurador
• Se añade un botón para abrir y cerrar el editor 2D de forma externa al configurador

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

<!-- Input para modificar el largo de la caja -->
<input id="length" type="number" placeholder="Length" onchange="changeBoxLength(this)" />

<!-- Botón que abre o cierra el editor 2D -->
<button id="artwork" onclick="openArtworkEditor()">Abrir Editor 2D</button>

<!-- Botón que ejecuta la función finishConfiguration para finalizar la configuración -->
<button onclick="finishConfiguration()">Finalizar configuración</button>

<!-- Incluir el 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("Caja no válida", error);
 }

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

 function closeArtworkEditor() {
  instabox.closeArtwork();
 }

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

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

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

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

 // Crear la instancia
 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>

Migrando de la v2.2.0 a la v3.3.0

Incluir el nuevo script

Reemplazar el script antiguo por el que se muestra a continuación:

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

Métodos

Ya no es necesario comprobar instabox.isReady antes de ejecutar un método.

Ahora los métodos están disponibles directamente en la variable creada en el momento de la instanciación

// Antes
if (instabox.isReady) {
 instabox.configurator.open();
}
// Ahora
instabox.open();

Carga asíncrona y el tratamiento de errores

Ahora la carga asíncrona y el tratamiento de errores es mucho más sencillo al haber solo un proceso asíncrono en lugar de dos (también es más rápido).

Lo único que hay que hacer es no pasar el parámetro productRef en el momento de la instanciación y utilizar el método open, ya sea directamente después de la instanciación para abrir el configurador al cargar la página o al pulsar algún botón.

Para más información ver el apartado "open(params, onReady, onError)"

Contacto

Si tiene algún problema durante el proceso de integración o migración no dude en ponerse en contacto con nosotros a través de [email protected]