Developer documentation

Integrate Paclab 3D in minutes

Paclab 3D ships as two integration libraries, chosen by what you are configuring: Instabox 3D for corrugated boxes and folding cartons, Instapack 3D for pouches, bottles, tubes, tubs, sleeves, bags, tape and apparel. Both embed an iframe into your own page. Pick your library for the Quick Start and the full parameter, event and method reference.

Instabox 3D · v4.1.0 Instapack 3D · v3.0.0

Quick Start

Corrugated boxes and folding cartons run on the Instabox 3D integration library. Include the script near the end of your page, create an instance of the Instabox3D class, and the configurator appears in an iframe — either as a pop-up or inside an element of your own page.

1. Include the script

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

2. Create the instance

‹‹script››
  const instabox = new Instabox3D({
    client: "trial",
    productRef: "fefco-0201",
    debug: true,
    onFinish: data =›› console.log("Configurator data", data),
  });
‹‹/script››

That is a working integration. client is the subdomain of your Instabox 3D, productRef is the product reference agreed in the briefing. Need a sandbox before your own configurator is live? Ask us for trial access at info@paclab.nl.

Introduction

The integration is done by creating a new instance of the Instabox3D class, passing an object with configuration parameters. Depending on those parameters the configurator appears as a pop-up window or within an existing HTML element on the page.

There are three types of parameters:

Required parameters — necessary to open the configurator.
Optional parameters — define how the configurator is displayed.
Event parameters — run your code when something happens inside the configurator.

Parameters can be passed at instantiation time and also in the open method:

instabox.open({
  // parameters
});

Static parameters such as client, plus optional and event parameters, are usually defined at instantiation. productRef and boxParams are usually defined in the open method, which can also modify or overwrite a previously defined parameter.

Current version: v4.1.0.

Required Parameters

client: String — the subdomain name of your Instabox 3D. If your URL is https://my-company.instabox3d.com, the value is "my-company". Usually the company name in lowercase, spaces replaced with hyphens.

productRef: String — the product reference specified in the briefing during the setup phase. Pass it at instantiation (the configurator opens showing that product) or in the open method (it opens only when that runs). productRef and projectRef are exclusive — one or the other, never both.

projectRef: String — to reopen a saved project instead of a product. The reference of each project is the one returned in the onFinish callback.

projectToken: String — required only if projectRef is defined. Also returned in the onFinish callback.

Optional Parameters

modal: Boolean = true — pop-up window (true) or embedded in an element of your page (false).

modalWidth: String = "100vw" and modalHeight: String = "100vh" — any CSS length. Only has effect when modal is true.

containerId: String — the id of the HTML element that will contain the configurator. Only has effect when modal is false.

iframeWidth: String = "100%" and iframeHeight: String = "600px" — size relative to the container element. To match the container height, set iframeHeight: "auto" and add display: flex to the container's style. Only has effect when modal is false.

boxParams: Object — default values for the box variables, keyed by variable ref (never name), with a number or an option ref as value. If the box has variables length, breadth, height, color and flute:

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

This is also how fixed boxes are built from parametric models: one parametric box with the variables hidden from the user, and the fixed measurements passed in the integration.

language: String — two-character language code, e.g. "en" or "es", if your Instabox has multiple languages.

disableForm: Boolean — deactivates the built-in contact form, e.g. when embedding in an e-commerce flow that has its own checkout.

hiddenSidebar: Boolean — hides the configurator sidebar so you can build the inputs and buttons into your own layout.

Event Parameters

onSave: Function — runs when the configuration is saved. Returns the same data as onFinish, except the file-related values, which are not generated until the project is finished.

onFinish: Function — runs when the user completes the configuration, receiving an object with: title, image, instaviewer, pdf, artwork, sourceFiles, dieline, projectRef, projectToken and config (variables, options, dielines and form data). Artwork values are omitted if the user applied no graphics.

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

In config, numeric variables land under config.variables[ref].value and selection variables under config.options[ref].selected.ref — keyed by the same refs reported by onChange.

onChange: Function — runs whenever the box configuration changes, receiving an array of the box variables with current and available values. It also fires once right after the configurator finishes loading, which makes it the enumeration API: the array is exactly the set of customizable variables you may write through boxParams / changeBoxParams.

// selection variable
{
  name: "mat",
  options: [
    {name: "Material 1", value: 0, ref: "optionReference1"},
    {name: "Material 2", value: 1, ref: "optionReference2"}
  ],
  publicName: "Material",
  ref: "variableReference",
  type: "SelectVariable",
  value: 0
}

// numeric variable
{
  name: "l",
  publicName: "Length",
  ref: "variableReference",
  type: "NumericVariable",
  value: 350
}

ref — the key to use when writing the variable. name is internal and display-only; never send it back.
type — NumericVariable, or SelectVariable / MaterialVariable / FluteVariable for selections (identical shape).
value on a selection variable is the index in options, not a ref. Write options[value].ref when round-tripping.

A variable only appears — and only accepts writes — if it is marked customizable in the briefing. A missing variable is a briefing change on our side, not an integration change: info@paclab.nl.

onArtworkOpened / onArtworkClosed: Function — run when the 2D editor is opened or closed.

onError: Function — runs with the error message when entered values are not valid.

Other Parameters

debug: Boolean = false — prints integration errors to the console. Useful during development, recommended off in production.

debug: true,

Methods

All methods are available on the variable created at instantiation time.

open(params, onReady, onError) — opens the configurator manually; the first argument must contain productRef, and may overwrite any previously defined parameter. Supports callbacks or promises:

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

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

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

close() — closes the configurator. Takes no arguments.

changeBoxParams(config) — works like the boxParams parameter, applied dynamically:

instabox.changeBoxParams({
  length: 320,
  color: "white-raw",
  flute: "B"
});

It has no return value and sends no acknowledgment. An unknown ref, or a ref that is not customizable, is a silent no-op. A customizable ref with an invalid value triggers onError. To confirm a change applied, read it back from the next onChange. Numeric variables accept a number or numeric string; selection variables require an exact option ref — not an index, not a name.

openArtwork(dielineReference) — opens the 2D editor; with no argument it opens the selected dieline.

closeArtwork() — closes the 2D editor.

saveConfiguration(externalData) — saves the configuration at any time. Production files are not generated on save; finish the project to generate them.

finishConfiguration(externalData) — finishes the configuration: production files are generated and the project is finalised, so it can no longer be edited. externalData entries need a name (string, or an object per language) and a value (string, number or boolean); _keys sets the order, and the special key title sets the project title.

{
  key1: { name: "Order ID", value: "SO-10482" },
  key2: { name: { en: "Quantity", es: "Cantidad" }, value: 2500 },
  _keys: ["key1", "key2"]
}

getIframe() — returns the iframe, e.g. to apply your own styling.

Code Examples

In these examples client is "trial" and productRef is "fefco-0201" — replace both with the values of your own configurator.

Embedded in an HTML element

‹‹div id="configurator-container" style="width: 75vw; height: 75vh; display: flex;"››‹‹/div››

‹‹script src="https://www.instabox3d.com/integration-v4.1.0.js"››‹‹/script››
‹‹script››
  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››

Open and close from your own buttons — instantiate without productRef so the configurator does not open automatically.

‹‹button onclick="openConfigurator()"››Open configurator‹‹/button››
‹‹button onclick="closeConfigurator()" id="close-btn" style="display: none"››Close configurator‹‹/button››

‹‹script src="https://www.instabox3d.com/integration-v4.1.0.js"››‹‹/script››
‹‹script››
  function openConfigurator() {
    instabox.open({ productRef: "fefco-0201" }, onOpen, onError);
  }
  function closeConfigurator() {
    instabox.close();
    document.getElementById("close-btn").style.display = "none";
  }
  function onOpen() {
    document.getElementById("close-btn").style.display = "block";
  }
  function onError(error) {
    console.log("Instabox Error", error);
  }

  const instabox = new Instabox3D({
    client: "trial",
    modalWidth: "80vw",
    modalHeight: "80vh",
    onFinish: output =›› console.log("Instabox Output", output),
  });
‹‹/script››

Two-way integration — drive the box from your own inputs and read values back.

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

function onBoxChange(data) {
  // match by ref, not name
  const variable = data.find(v =›› v.ref === "length");
  if (variable) document.getElementById("length").value = variable.value;
}

const instabox = new Instabox3D({
  client: "trial",
  productRef: "fefco-0201",
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
  hiddenSidebar: true,
  debug: true,
  onChange: onBoxChange,
  onError: error =›› console.log("Invalid box", error),
  onFinish: output =›› console.log("Instabox Output", output),
});

Quick Start

Pouches, doypacks, bottles, tubes, tubs, sleeves, bags, tape and apparel run on the Instapack 3D integration library. Include the script near the end of your page and create an instance of the Instapack3D class; the configurator appears in an iframe, as a pop-up or inside an element of your own page.

1. Include the script

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

2. Create the instance

‹‹script››
  const instapack = new Instapack3D({
    client: "demo",
    productRef: "aerosol",
    debug: true,
    onFinish: data =›› console.log("Configurator data", data),
  });
‹‹/script››

client is the subdomain of your Instapack 3D, productRef is the product reference agreed in the briefing. For sandbox access before your configurator is live, contact info@paclab.nl.

Introduction

The integration is done by creating a new instance of the Instapack3D class, passing an object with configuration parameters. Depending on those parameters the configurator appears as a pop-up window or within an existing HTML element on the page.

There are three types of parameters:

Required parameters — necessary to open the configurator.
Optional parameters — define how the configurator is displayed.
Event parameters — run your code when something happens inside the configurator.

Parameters can be passed at instantiation time and also in the open method:

instapack.open({
  // parameters
});

Static parameters such as client, plus optional and event parameters, are usually defined at instantiation; productRef is usually defined in the open method, which can also overwrite a previously defined parameter.

Current version: v3.0.0.

Required Parameters

client: String — the subdomain name of your Instapack 3D. If your URL is https://my-company.instapack3d.com, the value is "my-company".

Optional Parameters

modal: Boolean = true — pop-up window (true) or embedded in an element of your page (false).

modalWidth: String = "100vw" and modalHeight: String = "100vh" — any CSS length. Only has effect when modal is true.

containerId: String — the id of the container element. Only has effect when modal is false.

iframeWidth: String = "100%" and iframeHeight: String = "600px" — size relative to the container. To match the container height, set iframeHeight: "auto" and add display: flex to the container's style.

language: String — two-character language code, e.g. "en" or "es", if your Instapack has multiple languages.

disableForm: Boolean — deactivates the built-in contact form, e.g. when embedding in an e-commerce flow that has its own checkout.

hiddenSidebar: Boolean — hides the configurator sidebar so you can build the inputs and buttons into your own layout.

Event Parameters

onFinish: Function — runs when the user completes the configuration. The data is saved on the Instapack leads page, and the callback receives an object with: title, image, instaviewer, pdf, artwork, sourceFiles and config (options — Instapack 3D Pro only — plus parts with their names and chosen values, and form fields).

{
  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: {...}, selected: { ref: "optionRef", name: {...} } }, _keys: ["selectRef"] },
    parts: { partRef: { name: {...}, appearance: { ref: "AppearanceRef", name: {...} },
      artwork: true, color: "#ffffff",
      artworkPdf: "...part-artwork.pdf", combinedPdf: "...part-combined.pdf" }, _keys: ["partRef"] },
    form: { fieldRef: { name: {...}, value: "Field value" }, _keys: ["fieldRef"] }
  }
}

onChange: Function — runs on every change, receiving an object with optionGroups and partGroups, each carrying its current and 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 }
      ] }
  ],
  partGroups: [
    { id: "Part1", name: "Part 1", selected: true,
      materials: [
        { id: "Material1", name: "Material 1", selected: true },
        { id: "Material2", name: "Material 2", selected: false }
      ],
      color: "#ffffff", artwork: true }
  ]
}

onOptionGroupSelected: Function — runs with the option group ID when an option group is selected.

onPartGroupSelected: Function — runs with the part group ID when a part group is selected.

onArtworkOpened / onArtworkClosed: Function — run when the 2D editor is opened or closed.

Other Parameters

debug: Boolean = false — prints integration errors to the console. Useful during development, recommended off in production.

debug: true,

Methods

All methods are available on the variable created at instantiation time. Since v3.0.0 you no longer need to check instapack.isReady first.

open(params, onReady, onError) — opens the configurator manually; the first argument must contain productRef. Supports callbacks or promises:

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

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

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

close() — closes the configurator. Takes no arguments.

selectOptionGroup(optionGroupId) — changes the selected option group.

selectOption(optionGroupId, optionId) — changes the selected option.

selectPartGroup(partGroupId) — changes the selected part group.

selectMaterial(partGroupId, materialId) — changes the appearance of a specific part.

changeColor(partGroupId, color) — changes a part colour, passing the colour in hexadecimal format.

openArtwork(partGroupId) — opens the 2D editor; with no argument it opens the selected part group.

closeArtwork() — closes the 2D editor.

finishConfiguration() — ends the configuration at any time.

getIframe() — returns the iframe, e.g. to apply your own styling.

Code Examples

In these examples client is "demo" and productRef is "aerosol" — replace both with the values of your own configurator.

Embedded in an HTML element

‹‹div id="configurator-container" style="width: 75vw; height: 75vh; display: flex;"››‹‹/div››

‹‹script src="https://www.instapack3d.com/integration-v3.0.0.js"››‹‹/script››
‹‹script››
  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››

Open and close from your own buttons — instantiate without productRef so the configurator does not open automatically.

‹‹button onclick="openConfigurator()"››Open configurator‹‹/button››
‹‹button onclick="closeConfigurator()" id="close-btn" style="display: none"››Close configurator‹‹/button››

‹‹script src="https://www.instapack3d.com/integration-v3.0.0.js"››‹‹/script››
‹‹script››
  function openConfigurator() {
    instapack.open({ productRef: "aerosol" }, onOpen, onError);
  }
  function closeConfigurator() {
    instapack.close();
    document.getElementById("close-btn").style.display = "none";
  }
  function onOpen() {
    document.getElementById("close-btn").style.display = "block";
  }
  function onError(error) {
    console.log("Instapack Error", error);
  }

  const instapack = new Instapack3D({
    client: "demo",
    modalWidth: "80vw",
    modalHeight: "80vh",
    onFinish: output =›› console.log("Instapack Output", output),
  });
‹‹/script››

Two-way integration — hide the sidebar, build your own layout, and drive the configurator with the select methods.

const instapack = new Instapack3D({
  client: "demo",
  debug: true,
  modal: false,
  containerId: "configurator-container",
  iframeHeight: "auto",
  hiddenSidebar: true,
  onChange: configuration =›› console.log("Configuration changed", configuration),
  onOptionGroupSelected: id =›› console.log("Option group selected", id),
  onPartGroupSelected: id =›› console.log("Part group selected", id),
  onArtworkOpened: () =›› console.log("2D Editor opened"),
  onArtworkClosed: () =›› console.log("2D Editor closed"),
  onFinish: output =›› console.log("Instapack Output", output),
});

instapack.open({ productRef: "aerosol" }, onOpen, onError);

// then drive it from your own UI
instapack.selectOption(optionGroupId, optionId);
instapack.selectMaterial(partGroupId, materialId);
instapack.changeColor(partGroupId, "#ffffff");
instapack.openArtwork(partGroupId);
instapack.finishConfiguration();