3D Product Configurator UI

The user interface of the configurator is composed of an iframe that communicates via javascript with the page hosting the iframe.
The data exchanged concern:

• Data to initialize the configuration of a product.
• Data regarding prices and availability of the product that you have chosen to initialize.
• Adding the configured product to cart

Iframe code

Add the following code to include the configurator iframe to your system:

<iframe id="zakeke-frame" src="https://portal.zakeke.com/Configurator/index.html" allow="clipboard-read; clipboard-write; fullscreen; web-share"></iframe>

The Zakeke UI is fully responsive, and it's up to you to set the iframe css styling.

Other than adding the iframe code, your system will have to handle the following javascript communication between the Zakeke iframe and hosting page.

The authentication token must include must be of type C2S and you must fill Customer code or Visitor code.

Javascript integration flow with the hosting page

The diagram below will demonstrate the flow of actions from the site visitor going to the site through the process of configuring and adding to cart the product:

Send Zakeke iframe configuration

An object with the property type with "load" as value and the property parameters with the Zakeke iframe configuration object as value has to be sent using postMessage in order to initialize the configurator UI. In order to handle cases where you send the message before the Zakeke code inside the iframe loaded, you must  continue to post this message until the iframe post to you a message with type loaded.

It is possible to modify a previously created product configuration ("composition") by passing the property compositionId to the Zakeke iframe configuration object.

Zakeke iframe configuration properties

integrationVersion	"integrationVersion": 2 The version of the protocol to use for the integration. It must be 2
name	"name": "Woman handbag" The name of the product.
token	"token": "tXyHtJgiZK11yUQm7amGwTn7" A C2S authorization token with a valid customer code or a visitor code.
ecommerce	"ecommerce": "api" Always set to "api".
currency	"currency": "USD" The three-letter code for the currency used to format the prices.
culture	"culture": "en" The two letter language code (ISO 639-1).
modelCode	"modelCode": "242422342" The unique numeric identifier for the product to load.
compositionId	"compositionId": "315-e4848045-91c2-44b2" Optional. Enter in edit for a previously created product configuration.
qty	"qty": 1 Product quantity to be added to the cart.
attributes	"attributes": [ [ { "id": "34523" }, { "id": "537564567" } ] ] The list of attributes and respective values to start the configuration with. Each value is an array of two objects, containing respectively the id of the attribute and the id of the option.
customAddToCartButtonText	Optional. Enter it to change the text of the add to cart button.

Code example:

const iframe = document.querySelector("#zakeke-frame");

function zakekeLoad() {

    iframe.contentWindow.postMessage({

        type: "load",

        parameters: {

            "name": "Woman handbag",

            "token": "tXyHtJgiZK11yUQm7amGwTn7",

            "ecommerce": "api",

            "currency": "USD",

            "culture": "us",

            "modelCode": "242422342",

            "qty": 1,

            "attributes": [

                [

                    {

                        "id": "34523"

                    },

                    {

                        "id": "537564567"

                    }

                ]

            ]

        }

    }, '*');

}

const zakekeLoadInterval = setInterval(zakekeLoad, 500);

window.addEventListener('message', event => {

    if (event.origin !== new URL(iframe.src).origin) {

        return;

    }

    if (event.data.zakekeType === 'loaded') {

        clearInterval(zakekeLoadInterval);

    }

}, false);

 

Responding to the price requests

Each time that a product configuration is changed by a customer, Zakeke will ask to the hosting page about the price of that specific product configuration, passing the list of attributes with the respective values chosen and the sum of the unit price for the attributes where the price is managed on the Zakeke side.

The monetary values passed in the request by Zakeke are always in the base currency set in the API settings of your Zakeke account. The response value must be converted in the currency indicated by the "currency" property of the iframe configuration.

Depending on the settings of your system, product, and logged customer, the tax settings must be calculated for the response value.

Depending on the settings of your system, product, and logged customer, the applicable discounts must be calculated for the response value.

Price request properties

zakekeMessageType	"zakekeMessageType": "Price" "Price" is used for price requests.
messageId	"messageId": 2 The message identifier that must be present in the response.
message.compositionPrice	message.compositionPrice: 13.45 The sum of all the unit price of the chosen attribute options. The value is always in the base currency.
message.quantity	message.quantity: 1 Product quantity to be added to the cart.
message.attributes	message.attributes: [ { "attributeCode": "{\"id\":\"242422342\",\"label\":\"Color\",\"zakekePlatform\":true}", "attributeName": "Color" "attributeIsEnabled": true, "selectedOptionCode": "{\"id\":\"537564567\",\"label\":\"White\",\"zakekePlatform\":true}", "selectedOptionName": "White", "optionIsEnabled": true } ] The list of chosen attributes and respective values. For attributes that are linked to attributes on the store, the attributeCode and selectedOptionName properties each contain a json serialized with the sentinel zakekePlatform property and the id of your system. The properties attributeIsEnabled and optionIsEnabled are false if an they didn't pass ythe link check.

Price response properties

zakekeMessageType	"zakekeMessageType": "Price" "Price" is used for price response.
messageId	"messageId": 2 Must be the same messageId of the request.
message	"message": { price: 149.99, isOutOfStock: false } An object containing the  final price to be shown in the configurator UI and if the selected configuration is out of stock. The price property must be in the same currency as the "currency" property of the Zakeke iframe configuration object. If the product can't be sold for the requested attributes and quantity, the message the property isOutOfStock must be false.

Code example:

function handlePriceRequest(request) {
   var iframe = document.querySelector("#zakeke-frame");
   iframe.contentWindow.postMessage({
     messageId: request.messageId,
     zakekeMessageType: "Price",
     message: {
       price: calculateFinalPrice(request.message.attributes,
                request.message.quantity,
                request.message.compositionPrice),
       isOutOfStock: checkStock(request.message.attributes)
   }, "*");
     }
}

window.addEventListener("message", function (event) {
   if (event.data.zakekeMessageType === "Price") {
     handlePriceRequest(event.data);
   }
}, false);

 

Add to cart

When the consumer confirms that he wants to purchase the configured product, the Zakeke iframe sends a message to the hosting page containing the composition identifier, a preview image of the product and the requested quantity.
For security reasons, information on the attribute values chosen and the price managed on the Zakeke side must be made via an API S2S request as indicated in the documentation.

Add to cart request properties

zakekeMessageType	"zakekeMessageType": "AddToCart" "AddToCart" is used for the add to cart request.
message.composition	message.composition: "315-e4848045-91c2-44b2" The identifier to the product configuration.
message.preview	message.preview: "https://...." Url to image preview of the configured product.
message.quantity	message.quantity: 1 Product quantity to be added to the cart.

 Code example:

window.addEventListener("message", function (event) {
  if (event.data.zakekeMessageType === "AddToCart") {
    handleAddToCartRequest(event.data.message.composition,
      event.data.message.preview,
event.data.message.quantity);
  }
}, false);