Skip to main content

Configurator UI API

Summary

  1. Overview

  2. Iframe code

  3. Javascript Integration Flow With The Hosting Page

    3.1 Send Zakeke iframe configuration

    3.2 Zakeke iframe Configuration Properties

    3.2.1 integrationVersion

    3.2.2 name

    3.2.3 token

    3.2.4 ecommerce

    3.2.5 currency

    3.2.6 culture

    3.2.7 modelCode

    3.2.8 composition Optional

    3.2.9 qty

    3.2.10 attributes

  4. customAddToCartButtonText Optional

  5. Responding to The Price Requests

  6. Price Request Properties

    6.1 zakekeMessageType

    6.2 messageId

    6.3 message.compositionPrice

    6.4 message.quantity

    6.5 message.attributes

  7. Price Response Properties

    7.1 zakekeMessageType

    7.2 messageId

    7.3 message

  8. Add to Cart

    8.1 Add to Cart Request Properties

    8.1.1 zakekeMessageType

    8.1.2 message.composition

    8.1.3 message.preview

    8.1.4 message.quantity

1. Overview

The Configurator UI is the visual gateway that empowers users to personalize and modify products interactively. This dynamic interface is composed of an iframe, establishing seamless communication with the hosting page through JavaScript.

Key Components of Configurator UI Integration:

  • Initialization Data
  • Product Information: data related to prices and product availability during initialization.
  • "Add to Cart" to enable the addition of the configured product to the shopping cart.

By integrating these APIs, your platform gains the capability to incorporate the Configurator UI, offering users a visually engaging and interactive space for personalizing products.

2. 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" allowfullscreen></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.

3. 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:

Zakeke UI

3.1 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.

3.2 Zakeke iframe configuration properties

3.2.1 integrationVersion

"integrationVersion": 2 The version of the protocol to use for the integration. It must be 2

3.2.2 name

The name of the product.

"name": "Woman handbag"

3.2.3 token

A C2S authorization token with a valid customer code or a visitor code. Always set to "api".

"token": "tXyHtJgiZK11yUQm7amGwTn7"

3.2.4 ecommerce

Always set to "api".

"ecommerce": "api"

3.2.5 currency

The three-letter code for the currency used to format the prices.

"currency": "USD"

3.2.6 culture

The two letter language code (ISO 639-1).

"culture": "en"

3.2.7 modelCode

The unique numeric identifier for the product to load.

"modelCode": "242422342"

3.2.8 compositionId Optional

Enter in edit for a previously created product configuration.

"compositionId": "315-e4848045-91c2-44b2"

3.2.9 qty

Product quantity to be added to the cart.

"qty": 1

3.2.10 attributes

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.

"attributes": [
[
{
"id": "34523"
},
{
"id": "537564567"
}
]
]

4. 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",
"integrationVersion": 2,
"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);

5. 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.

6. Price Request Properties

6.1 zakekeMessageType

"Price" is used for price requests.

"zakekeMessageType": "Price"

6.2 messageId

The message identifier that must be present in the response.

"messageId": 2

6.3 message.compositionPrice

The sum of all the unit price of the chosen attribute options. The value is always in the base currency.

message.compositionPrice: 13.45

6.4 message.quantity

Product quantity to be added to the cart.

message.quantity: 1

6.5 message.attributes

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.

message.attributes: [
{
"attributeCode": "{\"id\":\"242422342\",\"label\":\"Color\",\"zakekePlatform\":true}",
"attributeName": "Color",
"attributeIsEnabled": true,
"selectedOptionCode": "{\"id\":\"537564567\",\"label\":\"White\",\"zakekePlatform\":true}",
"selectedOptionName": "White",
"optionIsEnabled": true
}
]

7. Price Response Properties

7.1 zakekeMessageType

"Price" is used for price response.

"zakekeMessageType": "Price"

7.2 messageId

Must be the same messageId of the request.

"messageId": 2

7.3 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);

8. 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.

8.1 Add to Cart Request Properties

8.1.1 zakekeMessageType

"zakekeMessageType": "AddToCart"

"AddToCart" is used for the add to cart request.

8.1.2 message.composition

message.composition: "315-e4848045-91c2-44b2"

The identifier to the product configuration.

8.1.3 message.preview

message.preview: "https://...."

Url to image preview of the configured product.

8.1.4 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);