Skip to main content

Customizer UI API

Summary

  1. Overview

  2. Create the Customizer Page

  3. Configuration JavaScript
    3.1 config

  4. Callback
    4.1 getProductInfo
    4.2 addToCart
    4.3 editAddToCart
    4.4 getSaveDesign
    4.5 getProductPrice
    4.6 getProductAttribute
    4.7 addToCartNameAndNumber
    4.8 editAddToCartNameAndNumber
    4.9 onBackClicked
    4.10 getSharedDesign
    4.11 addToCartBulk
    4.12 editAddToCartBulk

  5. CUSTOMIZE button
    5.1 Adding Customizer Button
    5.2 HTML FORM
    5.3 JavaScript to Send the Product Selection to the Customizer
    5.4 Full HTML code Example

1. Overview

The Customizer UI page plays a pivotal role in seamlessly integrating the Visual Product Customizer into your e-commerce website, offering a dynamic and engaging experience for your customers.

This interactive and sleek UI, incorporated within an iframe, empowers users to effortlessly create and modify designs on your products before adding them to the shopping cart.

Customizer-UI-pic

The integration of the customizer into your e-commerce website requires the following steps:

1) Creating a new page in your website (format: HTML, PHP, CSHTML, etc. depending on the technology used) that will host the IFrame of the ZAKEKE customizer

2) Entering configuration JavaScript code

3) Defining the following JavaScript callback in your website, which will be call by Zakeke for:

  • "getProductInfo": obtaining information on the product selected by the customizer

  • "addToCart": adding a product to the shopping cart

  • "editAddToCart": modifying the design of a customized product previously added to the shopping cart

For the various endpoints required by the integration, Zakeke allows a JavaScript function to be implemented and passed to Zakeke as a callback.

2. Create the Customizer Page

In your e-commerce website, you have to create a new page (in the example an HTML page) whose layout will be that of your website and the content will have a div so defined (highlighted):

<!-- header html layout... -->

<div class="container">

<div id="zakeke-container">

</div>

</div> <!-- footer html layout... -->

3. Configuration JavaScript

Before closing the <body> tag of the previously created page, add the following JavaScript references:

<script
src="https://portal.zakeke.com/scripts/integration/apiV2/customizer.js">
</script>

Then add the following JavaScript block that will start the customizer on the page:

<script>

var customizer = new ZakekeDesigner();

//Create config object
var config = {
tokenOauth: "Token Oauth",
//...
}

//Create Iframe
customizer.createIframe(config);

</script>

In addition to creating the iframe, you also have the option to remove it using the removeIframe function.

<script>

var customizer = new ZakekeDesigner();

//Create Iframe
customizer.createIframe(config);

//Remove Iframe
customizer.removeIframe();

</script>

3.2 Config

config is a JavaScript object which allows you to parameterize some aspects of the integration and, above all, to specify the various callback necessary for the dialogue between the ecommerce and Zakeke. The config object is structured as follows:

var config = {
tokenOauth: "Token Oauth",
// Product configuration
productId: "Id product",
productName: "Name product",
getProductInfo: { javascript function object },
getProductPrice: { javascript function object },
getProductAttribute: { javascript function object },
// Add to cart
cartButtonText: "Add To Cart",
addToCart: { javascript function object },
editAddToCart: { javascript function object },
// Name and numbers (add to cart and edit product)
isNamesAndNumbers: false,
addToCartNameAndNumber: { javascript function object },
editAddToCartNameAndNumber: { javascript function object },
// Bulk variations purchase (add to cart end edit product)
isMultipleVariations: true,
addToCartBulk: { javascript function object },
editAddToCartBulk: { javascript function object },
isBulkIndividualFile: true,
// Share design
isSharedDesignUrl: true,
getSharedDesign: { javascript function object },
ShareUrlPrefix: "http://your.store.com/",
// Save design
isSaveDesign: true,
getSaveDesign: { javascript function object },
//--
onBackClicked: { javascript function object },
//--
designId: "",
hideVariants: true,
inventoryManagement: false,
priceTaxIncluded: false,
isClientPreviewsEnabled: true,
mobileVersion: false,
culture: "it-IT",
currency: "EUR",
loadTemplateId: "",
labelTax: "hidden",
quantity: 1,
selectedAttributes:
{
"attributekey1": "selectedattributevalue1",
//...//
"attributekeyn": "selectedattributevaluen"
},
sides: ["codeSide1",...,"codeSiden"],
additionalData: {}
};
Please Note

For products created in Zakeke using CSV files, the productid specified in productJson object must match the MasterProductID specified in the products.txt file. Go to CSV product data specification.

Another property of the config object to pay attention to in case the product has variants is selectedAttributes. This property specifies the complete selection of all attribute values that define the variant chosen by the user on the product page. The property specifies a list in which for each attribute its name or identification key is reported (as per the form on the product page) and the encoded value. If the product was uploaded via the products CSV file, the key-value pairs specified in the Attributes field must be present among the key-value pairs specified for the property (For more details go to how to connect products through CSV.).

For example, in the case of a product with color and size variations, the property could have the following values:

{
// ... //
selectedAttributes:
{
"Color": "Y",
"Size": "M"
}
}

indicating the selection Yellow (Y) for the color attribute (Color) and Medium (M) for the size attribute (Size).

The following table explains the meaning and format of the various properties of the config object.

PropertyDescriptionAdditional info
tokenOauthAuthentication OAuth token with additional information about visitor and/or authenticated user (for more details go to how to obtain an authentication token with customer and/or visitor code)Type: string
Default: empty
Required: true
productIdUnique product IDType: string
Required: true
productNameName productType: string
Required: true
designIdZakeke generated unique design ID of the customized product to be modified.Type: string
Default: empty
Required:: false (mandatory for editing a custom product design)
loadTemplateIdOpens the iframe directly with the declared templateIDType: string
Default: empty
Required:: false
currencyExample: USD. Currency selected by the customer on your store, with ISO 4217 encoding.Type: string
Default: empty
Required:: true
cultureExample: en-US. IFRAME interface language based on Microsoft encoding table. For details on encoding go to this link.Type: string
Default: empty
Required:: true
mobileVersiontrue: customizer IFRAME will be adapted for the mobile version
false: customizer IFRAME will be adapted for the desktop version
Type: boolean
Default: false
Required: false
labelTaxIndicates how tax label will be presented in the IFRAME interface.
Possible values:
- hidden: the label is hidden
- including: label "taxes included" is displayed
- excluding: label "taxes excluded" is displayed hidden
Type: string
Default: empty
Required:: false
quantityCustomizable product quantity to be added/editedType: integer
Default: undefined
Required:: true
imagePreviewHeightHeight in pixel of the preview generated by ZakekeType: integer
Default: 200
Required:: false
imagePreviewWidthWidth in pixel of the preview generated by ZakekeType: integer
Default: 200
Required:: false
isClientPreviewsFlag to enable the generation of the preview image for each side of the customized product.Type: boolean
Default: false
Required:: false
cartButtonTextLabel of the "Add to cart" button inside the IFRAME Add to cartType: string
Default: empty
Required: false
hideVariantsIf it is false, you will have the opportunity to change the variant. For more details go to hideVariantsType: boolean
Default: false
Required: false
getProductInfoJavaScript feature to obtain product information based on the selection of attributes. For more details go to how to configure the "getProductInfo".Type: string
Default: none
Required:: true
getProductPriceJavaScript feature on Merchant website to send the final price of the product. how to configure the "getProductPrice"Type: function
Default: none
Required: true
getProductAttributeJavaScript function on Merchant web site. For more details go to how to configure the "getProductAttribute".Type: function
Default: undefined
Required: true
addToCartJavaScript function on Merchant web site to handle adding of customized product to shopping cart. For more details go to how to configure the "AddToCart"Type: function
Default: undefined
Required: true
editAddToCartJavaScript function on Merchant web site to handle editing of customized product into shopping cart. For more details go to how to configure the "editAddToCart".Type: function
Default: undefined
Required: true
isNamesAndNumbersEnable the Name And Number featureType: boolean
Default: false
Required: false
addToCartNameAndNumberJavaScript function on Merchant web site to handle adding customized products with Names and Numbers to shopping cart. For more details go to how to configure the "addToCartNameAndNumber".Type: function
Default: undefined
Required: false (mandatory if isNamesAndNumbers has been defined)
editAddToCartNameAndNumberJavaScript function on Merchant web site to handle editing of customized products with Names and Numbers into shopping cart. For more details go to how to configure the "editAddToCartNameAndNumber".Type: function
Default: undefined
Required: false (mandatory if isNamesAndNumbers is set to true)
isMultipleVariationsEnable Bulk Variation Forms featureType: boolean
Default: false
Required:: false
addToCartBulkJavaScript function on Merchant website to handle adding customized products to shopping cart with bulk variation purchase. For more details go to how to configure the "addToCartBulk".Type: function
Default: undefined
Required: false (mandatory mandatory if isMultipleVariations is set to true)
editAddToCartBulkJavaScript function on Merchant website to handle editing of customized products into shopping cart. Bulk Variation version. For more details go to how to configure the "editAddToCartBulk".Type: function
Default: undefined
Required: false (mandatory mandatory if isMultipleVariations)
isBulkIndividualFileEnables the possibility of using a different design (and therefore obtaining a different print file) for each different variant chosen in the Bulk Variations Form.Type: boolean
Default: false
Required:: false
isSharedDesignAllows the merchant to manage the share functionalityType: boolean
Default: false
Required: false
getSharedDesignJavaScript feature on the Merchant’s website to manage the share functionality. For more details go to how to configure the "getSharedDesign".
shareUrlPrefixOption to enter the domain of the merchant in the preview URLType: string
Default: empty
Required:: false
isSaveDesigntrue: enable feature to save or change existing design for a customized product previously added into cart
false: disable feature explained above
Type: boolean
Default: false
Required: false
getSaveDesignJavaScript function on Merchant web site to handle change design event of customized products into shopping cart. For more details go to how to configure the "getSaveDesign".Type: function
Default: undefined
Required: false (mandatory if canSaveDesign is set to true)
sidesExample:['side1','side2']
Codes of product sides (defined in the sides CSV) on which customization is allowed
Type: array of string
Default: undefined
Required:: false
additionalDataAdditional data to send to merchantType: object
Default: undefined
Required: false
selectedAttributesSelected product attributes sent to the customizer page. They are formed by a set of key-value pairs consisting respectively of the attribute name (used in product page forms) and the selected coded value.
N.B. The sequence of key-value pairs represents the entire selection of attributes for the product variant chosen by the user on the product page of the ecommerce. To identify the customizable variant in Zakeke, this sequence must contain the sub-sequence of key-value pairs corresponding to the customizable variant passed to Zakeke via CSV feed. (For more details go to how to connect products through CSV.).
If product has not variants, the value must be an empty object ('selectedattributes': )
Type: object
Default: undefined
Required:: true

4. JavaScript callback

4.1 GetProductInfo

Zakeke IFRAME needs to use a callback to get information such as the updated price inclusive of the design. You can set the callback function in the config JavaScript object:


function callback(zakekeData){
//...
return data = {
price: 40,
isOutOfStock: false
};
}
// Customizer config
var config = {
//...
getProductInfo : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

The callback function will be called with the following javascript object:

{
productId: "productId",
quantity: 1,
selectedattributes:
[
/* (e.g.[{"color":"0","size":"1"}]) */
{"attrKey1":"attrValue1"},...,
{"attrKeyn":"attrValuen"}
],
price: 10.5,
percentPrice: 10,
additionaldata: {}
}

Where:

PropertyTypeDescriptionDefault valueRequired
productIdstringUnique product ID
quantityintegerSelected quantity of product to be customized
selectedattributesarrayarray of key-vaue pair of selected product attributes
N.B. the attribute keys match those imported from CSV
pricemoneyUnit price (in the currency of your e-commerce) of the created design to be added to the one of the product
percentPricemoneyPercentage of the created design to be added to the one of the product, to be applied to the unit price of the product
additionaldataobjectAdditional data to send to JavaScript functionoptional
warning

The price property specifies the unit price, encompassing any initial setup costs. It is important to carefully note the number of decimal places in this price, as it may exceed the standard two digits.

If we indicate the unit price of the product on the e-commerce with unitPrice, the global unit price could be calculated as follows:

finalUnitPrice = unitPrice + price + (unitPrice*percentPrice/100);
finalPrice = finalUnitPrice * quantity;

The callback response must be structured as follows:

{
price: 30.5,
isOutOfStock: false
}

Where:

PropertyTypeDescription
finalpricemoneyFinal price calculated depending on the added design and unit price of the model product
isoutofstockbooleanfalse: if product is in stock
true: if product is not available (out of stock, ect.)

4.2 AddToCart

Zakeke will call this function to communicate with the ecommerce that the end user has decided (by clicking on the "Add to cart" button) to add the customized product to the shopping cart.

The AddToCart function can be implemented on the client-side by defining a JavaScript callback. This can be specified via the addToCart property of the config object:

4.2.1 JavaScript callback

The callback will be called with the following Javascript object:

{
productId: "productId",
designId: "designId",
quantity: 1,
selectedattributes:
[
/* (e.g. [{"color":"0","size":"1"}]) */
{"attrKey1":"attrValue1"},...,
{"attrKeyn":"attrValuen"}
],
additionaldata: {}
}

Where:

PropertyTypeDescription
productIdstringUnique product ID
designIdstringUnique design ID applied to the customized product
quantityintegerQuantity of customized product to add to shopping cart
selectedattributesarrayarray of key-value pair of selected attributes

N.B. Attribute keys must match those imported by CSV products. Additional data is optional and should be sent to the callback.

Please Note

The designId provided as input to the callback can be used in the API call to Zakeke to retrieve details about the user's created design. (Go to DESIGN API for more information.)

In response, the callback must provide a Javascript object with the URL of the shopping cart page.

{
window.location.href = "string (shopping cart URL)";
}

4.3 EditAddToCart

After adding a custom product to the shopping cart, a user may wish to change its design by reopening the Zakeke customization interface, where the initial “Add to Cart” button will be replaced by the “Save Changes” button. When this button is pressed, Zakeke calls the specified callback to notify e-commerce that the customized product has undergone changes.

// Callback edit product into shopping cart 
function callback(zakekeData){
//...
}
// Customizer config
var config = {
//...
editAddToCart : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

N.B.The design ID will remain unchanged even after the editing.

4.3.1 JavaScript callback

The callback will be called with the following Javascript object:

{
productId: "productId",
designId: "designId",
quantity: 1,
selectedattributes: {
[
/* (e.g. [{"color":"0"},{"size":"1"}]) */
{"attrKey1":"attrValue1"},
//...,
{"attrKeyn":"attrValuen"}
],
}
additionaldata: {object}
}

Where:

PropertyTypeDescription
productIdstringUnique product ID
designIdstringUnique design ID applied to the customized product
quantityintegerQuantity of customized product to add to shopping cart
selectedattributesarrayarray of key-value pair of selected attributes

N.B. Attribute keys must match those imported by CSV products. Additional data is optional and should be sent to the callback.

Please Note

The designId provided as input to the callback can be used in the API call to Zakeke to retrieve details about the user's modified design. Go to Design API for more information.

In response, the callback must provide a JSON object with the URL of the shopping cart page.

{
window.location.href = "string (shopping cart URL)";
}

4.4 GetSaveDesign

JavaScript functions to handle the change design event for a customized product previously added to the cart. The callback will receive the JSON object defined below as input.

{
designId: "designId"
}

Where:

AttributeDescription
designIdUnique design ID

4.5 GetProductPrice

The getProductPrice function can be implemented on the client-side by defining a JavaScript callback. This can be specified via the getProductPrice property of the config object:

// Callback edit product price 
function callback(zakekeData){
//...
return data = {
price: 40,
isOutOfStock: false
};
}
// Customizer config
var config = {
//...
getProductPrice : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)
Please Note

Zakeke expects a final unit price from the e-commerce site, to be multiplied by the quantity to have a total price of the customized product.

4.5.1 JavaScript callback

The callback will be called with the following Javascript object:

{
productId: "productId",
selectedattributes:
[
/* (e.g. [{"color":"0"},{"size":"1"}]) */
{"attrKey1":"attrValue1"},
//...,
{"attrKeyn":"attrValuen"}
],
percentPrice: 0,
price: 0,
quantity: 1
}

Where:

PropertyTypeDescription
productIdstringUnique product ID
selectedattributesarrayarray of key-value pair of selected attributes
quantityintegerQuantity of customized product to add to shopping cart
percentagePricenumberPercentage increase in product price due for customization, if any
pricemoneyUnit price (in the currency of your e-commerce) of the created design to be added to the one of the product

N.B. attribute keys must match those imported by CSV products

warning

The price property specifies the unit price, encompassing any initial setup costs. It is important to carefully note the number of decimal places in this price, as it may exceed the standard two digits.

If we indicate the unit price of the product on the e-commerce with unitPrice, the global unit price could be calculated as follows:

finalUnitPrice = unitPrice + price + (unitPrice*percentPrice/100);
finalPrice = finalUnitPrice * quantity;

In response, provide a JavaScript object that will contain the final price and any out of stock.

{
price = 100,
isOutOfStock = false
}

Where:

AttributeDescription
priceFinal product unit price, including both the product price and the design price.
isoutofstockfalse: if product is in stock
true: if product is not available (out of stock, ect.)

4.6 GetProductAttribute

This Javascript function allows Zakeke to retrieve information about all the attributes and variants of an ecommerce product. Attributes constitute the single variable characteristics of a product that a customer can choose at the time of purchase (e.g. Size, Color, etc.). A variant is a particular combination of attribute values made available for online purchase. If, for example, a product has two attributes, Size and Color, with the possible values (S and M) and (Yellow and Red) respectively, then a possible variant for the product could be the combination Size=S and Color =Red or Size=M and Color=Red.

The Javascript function must be implemented client-side by defining a JavaScript callback. It must be specified via the getProductAttribute property of the config object:

{
//...//
getProductAttribute : {javascript function object},
//...//
}

4.6.1 Callback request data

The javascript callback sends this data:

{
productId: "productId"
}

Where:

PropertyTypeDescription
productIdstringUnique product ID

In response, the Javascript function must provide a object that will contain the attributes and variants of the products:

{
"attributes": [
{
// Size attribute
code: "1",
label: "Size",
values: [
{
code: "m",
label: "M"
},
{
code: "s",
label: "S"
}
]
},
{
// Color attribute
code: "2",
label: "Color",
values: [
{
code: "blue",
label: "Blue"
},
{
code: "green",
label: "Green"
}
]
}
],
variants: [
[
// Variant 1 (Size: M, Color: Yellow)
{
code: "1",
value: {
code: "m"
}
},
{
code: "2",
value: {
code: "blue"
}
},

],
[
// Variant 2 (Size: M, Color: Red)
{
code: "1",
value: {
code: "s"
}
},
{
code: "2",
value: {
code: "green"
}
}
],
// ...
// ...
]
}

Where:

PropertyTypeDescription
AttributesarrayThe list of the product attributes
VariantsarrayThe list of the product variants

Each attribute is an object having the following structure:

{
code: "1",
label: "Size",
values: [
{
code: "m",
label: "M"
},
{
code: "s",
label: "S"
}
]
}

Where:

PropertyTypeDescription
codestringThe attribute identifier (code or key) in the ecommerce
labelstringThe attribute name that can also be used in a selection user interface
valuesarraythe list of possible values for the attribute, with code and label for each of the values

Each variant of the variants array represents the list of code-value pairs for the attributes that characterize it. Each code-value pair for a single attribute of the variant will be represented by an object of the type:

{
code: "1",
value: {
code: "s"
}
}

where:

PropertyTypeDescription
codestringThe attribute identifier (code or key) in the ecommerce
valueobjectThe object containing the code of the attribute value

4.6.2 JavaScript callback

Alternatively, if the getProductAttribute property is defined in the JavaScript configuration, you can use a JavaScript function to submit product attributes and variants.

function callback(){
// callback code to send the equipment of the products
return productData = {
attributes: [
// Attribute I
{
code: "1",
label: "Size",
values: [
{ code: "m", label: "M" },
{ code: "s", label: "S" }
]
},
// Attribute II
{
code: "2",
label: "Color",
values: [
{ code: "blue", label: "Blue" },
{ code: "green", label: "Green" }
]
}
],
variants: [
// Variant I
[
{ code: "1", value: { code: "m" } },
{ code: "2", value: { code: "blue" } }
],
// Variant II
[
{ code: "1", value: { code: "s" } },
{ code: "2", value: { code: "green" } }
]
]
};
}
// Customizer config
var config = {
//...
getProductAttribute : callback,
//...
}
var customizer = new ZakekeDesigner();

customizer.createIframe(config)

4.7 AddToCartNameAndNumber

Zakeke's “Names and Numbers” tool is a feature that allows shoppers to add multiple product variants to their shopping cart by customizing specific fields with the same design. This tool is used creatively in various contexts, such as identifying players on sports jerseys or customizing items for events.

This javascript callback will be called by Zakeke to tell e-commerce that the end user has decided (by clicking the “Add to Cart” button) to add the customized product (with names and numbers) to the cart.

4.7.1 Callback request data

The javascript callback sends this data:

{
productId: "productId",
designId: "designId",
namesandnumbers: [
{
modificationid: "modificationid",
elementdescs: {
id: "elementdescid",
elements: [
{
tag: "name",
text: {
content: "my name 1"
}
},
{
tag: "number",
text: {
content: "01"
}
}
]
},
selectedattributes: [
{
Id: "1",
Value: {
Id: "m"
}
},
{
Id: "2",
Value: {
Id: "y"
}
}
],
quantity: 5,
previewimageurl: "url-to-preview-image"
}
],
previews: [
{
url: "url-to-preview-image",
sideName: "side name",
modificationID: "modificationid"
}
]
}

Where:

PropertyTypeDescription
productIdstringUnique product ID
designIdstringUnique design ID applied to the customized product
namesandnumbersarrayThe list of specific values to apply to the design fields and for which product variations
previewsarrayThe list of the preview images generated for each different design fields value combination
Please Note

The designId provided as input to the javascript callback can be used in the API call to Zakeke to retrieve details about the user's created design. (Go to DESIGN API for more information.)

The namesandnumbers property is an array of objects, each of which specifies the combination of values for the design fields, for which product variant to use that combination, and in what quantity. The object of the array has the following structure:

{
modificationid: "modificationid",
elementdescs: {
id: "elementdescid",
elements: [
{
tag: "name",
text: {
"content": "my name 1"
}
},
{
tag: "number",
text: {
"content": "01"
}
}
]
},
selectedattributes: [
{
Id: "1",
Value: {
Id: "m"
}
},
{
Id: "2",
Value: {
Id: "y"
}
}
],
quantity: 5,
previewimageurl: "url-to-preview-image"
}

where:

PropertyTypeDescription
modificationidstringUnique identifier generated by Zakeke for the field value combination
elementdescsobject The list of values for the design fields
selectedattributesarrayArray of key-value pair of selected attributes
quantityintegerThe quantity of customized product for the combination of design field values to add to cart
previewimageurlstringThe image preview of the customized product with the combination of design field values applied

4.7.2 JavaScript callback

Alternatively, if the addToCartNameAndNumber property is defined in the configuration JavaScript, you can use a JavaScript function to manage the adding of the customized product to the cart when the names and numbers tool is enabled. The callback will receive in input the same JSON object defined above for the HTTP call.

The following code shows how to define the callback in the JavaScript configuration code:

// Callback product into shopping cart name and number
function callback(jsonInput){

window.location.href = "https://your-store/cart";
}
// Customizer config
var config = {
//...
addToCartNameAndNumber : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

In response, the Javascript function must provide a object with the URL of the shopping cart page.

{
window.location.href = "http://your.store.com/page";
}

4.8 EditAddToCartNameAndNumber

After adding a customized product to the cart, a user may want to change its design by reopening the Zakeke customization interface where the initial "Add to cart" button will be replaced with the "Save changes" one. When this button is pressed, Zakeke calls the specified Javascript function to notify the ecommerce that the customized product has undergone changes. The Javascript function manages the case of modifying a product in the cart when it has been customized with the "Names and numbers" tool.

The Javascript function must be implemented client-side by defining a JavaScript callback. It must be specified via theeditAdditToCartNameAndNumber property of the config object:

{
//...//
editAddToCartNameAndNumber: {javascript function object},
//...//
}

The Javascript function must update the custom product previously added into the shopping cart, with the one with the changed design.

N.B.The design ID will remain unchanged even after the editing.

4.8.1 Callback request data

The Javascript function will be called in post with a JSON in the body with the same structure as the one used for the Shopping Cart how to configure the "AddToCart" in the Names and Numbers case

In response, the Javascript function must provide a Javascript object that will contain the URL of the shopping cart page.

{
window.location.href = "string (shopping cart URL)";
}

4.8.2 JavaScript callback

Alternatively, if the editAddToCartNameAndNumber property is defined in the configuration JavaScript object, you can use a JavaScript function manage the editing of the customizer product into the cart. [ copiare il data mandato ]

// Callback edit product into shopping cart name and number
function callback(jsonInput){
//...
}
// Customizer config
var config = {
//...
editAddToCartNameAndNumber : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

4.9 OnBackClicked

The property allows you to specify the JavaScript function to be called when the "Back" button inside the Zakeke IFrame is pressed.

function callback(jsonInput){
window.location.href = "https://www.zakeke.com/";
}
// Customizer config
var config = {
//...
onBackClicked : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

4.10 SharedDesignUrl

In Zakeke, the end user has the ability to share the customization they have created on a product. To allow a design to be shared among multiple users, a link must be generated that allows the receiving user to directly open the Zakeke customizer within the ecommerce with the shared design automatically uploaded.

On the client side by defining a JavaScript callback, it allows Zakeke to request the ecommerce to generate the link from the current design identifier. The ecommerce will have the ability to implement all the logic to generate the correct link that has all the necessary parameters for the product and design to load.

{
//...//
isSharedDesign: true,
getSharedDesign: {javascript function object},
shareUrlPrefix: "http://your.store.com/",
//...//
}

4.10.1 Callback request data

The javascript callback sends this data:

{
designId: "designId",
}

Where:

PropertyTypeDescription
productIdstringUnique product ID
designIdstringUnique design ID applied to the customized product

In response, the Javascript function must provide a object with the URL to share:

{
url: "http://your.store.com/QjIuKgt7F0SH52YVLGArgg"
}

4.10.2 JavaScript callback

The getSharedDesign property is defined in the configuration JavaScript object, use a JavaScript function to handle URL generation.


function callback(zakekeData){
return url = "https://your-store/" + zakekeData;
}
// Customizer config
var config = {
//...
getSharedDesign : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

4.11 AddToCartBulk

In Zakeke it is possible to activate the ability to purchase multiple variants of the same product with the same design in bulk. The function is available in two versions. In the first case, Zakeke generates a single version of the print files to be used for all the variants the user has chosen to purchase. In the second case, Zakeke generates a different file for each of the variants chosen by the user.

In this and subsequent sections we will describe the Javascript function (for adding to cart and for editing) related to the first possibility, single print file, while later we will also introduce the Javascript function for the second.

As usual, the Javascript function can be implemented client-side by defining a JavaScript callback. it must be specified via the addToCartBulk property of the config object:

{
//...//
addToCartBulk: {javascript function object},
//...//
}

4.11.1 Callback request data

The javascript callback sends this data:

{
productId: "productId",
designId: "designId",
bulkvariations: [
{
attributes: [
{
Id: "1",
Value: {
Id: "m"
}
},
{
Id: "2",
Value: {
Id: "y"
}
}
],
quantity: 2
},
{
attribute : [
{
Id: "1",
Value: {
Id: "m"
}
},
{
Id: "2",
Value: {
Id: "r"
}
}
],
quantity: 3
}
],
previews: [],
}

Where:

PropertyTypeDescription
productIdstringUnique product ID.
designIdstringUnique design ID applied to the customized product.
bulkvariationsarrayArray of variants with the desired quantity for each of them.
previewsarrayArray of preview images

Variants in bulkvariations are specified via an array of code-value pairs, where each code-value pair represents the selection for a specific attribute.

In response, the Javascript function must provide a Javascript object with the URL of the shopping cart page.

{
window.location.href = "string (shopping cart URL)";
}

4.11.2 JavaScript callback

Alternatively, if the addToCartBulk property is defined in the configuration JavaScript object, you can use a JavaScript function to manage the adding of the customized product to the cart. The callback will receive in input the same Javascript object.

// Callback edit product into shopping cart bulk
function callback(zakekeData){
//...
window.location.href = "https://your-store/cart";
}
// Customizer config
var config = {
//...
addToCartBulk : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

4.12 EditAddToCartBulk

After adding a custom product to the shopping cart with the mass changes module, a user may want to change its design by reopening the Zakeke customization interface, where the initial “Add to Cart” button will be replaced by the “Save Changes” button. When this button is pressed, Zakeke calls the specified Javascript function to notify ecommerce that the customized product has undergone changes.

The Javascript function can be implemented client-side by defining a JavaScript callback. It must be specified via the editAdditToCartBulk properties of the config object:

{
//...//
editAddToCartBulk: {javascript function object},
//...//
}

4.12.1 Callback request data

The javascript callback sends this data:

{
productId: "productId",
designId: "designId",
bulkvariations: [
{
attributes: [
{
Id: "1",
Value: {
Id: "m"
}
},
{
Id: "2",
Value: {
"Id": "y"
}
}
],
quantity: 2
},
{
attributes: [
{
Id: "1",
Value: {
Id: "m"
}
},
{
Id: "2",
Value: {
Id: "r"
}
}
],
quantity: 3
}
],
previews: [],
}

Where:

PropertyTypeDescription
productIdstringUnique product ID.
designIdstringUnique design ID applied to the customized product.
bulkvariationsarrayArray of variants with the desired quantity for each of them.
previewsarrayArray of preview images

Variants in bulkvariations are specified via an array of code-value pairs, where each code-value pair represents the selection for a specific attribute.

In response, the Javascript function must provide a Javascript object with the URL of the shopping cart page.

{
window.location.href = "string (shopping cart URL)";
}

4.12.2 JavaScript callback

// Callback edit product into shopping cart bulk
function callback(jsonInput){
//...
}
// Customizer config
var config = {
//...
editAddToCartBulk : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

4.13 AddToCartBulk

The Javascript function will be invoked by Zakeke in case of bulk addition to the shopping cart of a customized product in multiple variants and when the generation of a different print file for each variant has been enabled. The isBulkIndividualFile property of the JavaScript configuration file can be used to enable this second version of the bulk purchase.

The Javascript function must be implemented client-side by defining a JavaScript callback. It must be specified via the addToCartBulk property of the config object:

{
//...//
isBulkIndividualFile: true,
addToCartBulk: {javascript function object},
//...//
}

4.13.1 Callback request data

The javascript callback sends this data:

{
productId: "productId",
designId: "designId",
bulkvariations: [
{
modificationID: "modificationid",
selectedattributes: [
{
Id: "1",
Value: {
Id: "m"
}
},
{
Id: "2",
Value: {
"Id: "y"
}
}
],
quantity: 5,
tempPreviewImageUrl: "urlPreview"
}
],
previews: [],
}

Where:

PropertyTypeDescription
productIdstringUnique product ID
designIdstringUnique design ID applied to the customized product
bulkvariationsarrayArray of variants with the desired quantity for each of them.
previewsarrayArray of preview images
Please Note

The designId provided as input to the endpoint can be used in the API call to Zakeke to retrieve details about the user's created design. (Go to DESIGN API for more information.)

The bulkvariations property is an array of objects, each of which specifies the combination the product variant added to the cart and in what quantity. The object of the array has the following structure:

{
modificationid: "modificationid",
selectedattributes: [
{
Id: "1",
Value: {
Id: "m"
}
},
{
Id: "2",
Value: {
Id: "y"
}
}
],
quantity: 5,
previewimageurl: "url-to-preview-image"
}

where:

PropertyTypeDescription
modificationidstringUnique identifier generated by Zakeke for the variant
selectedattributesarrayArray of key-value pair of selected attributes
quantityintegerThe quantity of customized product for the combination of design field values to add to cart
previewimageurlstringThe image preview of the customized product in the selected variant

In response, the Javascript function must provide a JSON object with the URL of the shopping cart page.

{
window.location.href = "string (shopping cart URL)";
}

4.13.2 JavaScript callback

The following code shows how to define the callback in the JavaScript configuration code:

// Callback edit product into shopping cart bulk
function callback(jsonInput){
//...
window.location.href = "https://your-store/cart";
}
// Customizer config
var config = {
//...
editAddToCartBulk : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

4.14 EditAddToCartBulk

After adding a custom product to the shopping cart with the massive variations module, a user may wish to change its design by reopening the Zakeke customization interface, where the initial “Add to Cart” button will be replaced by the “Save Changes” button. When this button is pressed, Zakeke calls the specified Javascript function to notify e-commerce that the customized product has undergone changes.

The Javascript function must be implemented client-side by defining a JavaScript callback. It must be specified via the editAddToCartBulk property of the config object:

{
//...//
isBulkIndividualFile: true,
//...//
editAddToCartBulk: {javascript function object},
//...//
}

The Javascript function must update the custom product previously added into the shopping cart, with the one with the changed design.

N.B.The design ID will remain unchanged even after the editing.

4.14.1 Callback request data

The Javascript function will be called in post with a Javascipt object in the body with the same structure as the one used for the Shopping Cart Javascript function how to configure the "AddToCart" Javascript function in the Bulk variations case

In response, the Javascript function must provide a Javascript object that will contain the URL of the shopping cart page.

{
window.location.href = "string (shopping cart URL)";
}

4.14.2 JavaScript callback

// Callback edit product into shopping cart bulk
function callback(zakekeData){
//
}
// Customizer config
var config = {
//...
editAddToCartBulk : callback,
//...
}

var customizer = new ZakekeDesigner();

customizer.createIframe(config)

4.15 HideVariants

When you set this property to false, you will have the option to select and change the product variant each time you open the iframe, allowing for greater customization and flexibility. Additionally, you can customize the interface using the "Interface Editor" tool. This Guide provides detailed instructions on how to do it.

Product Colors

5. CUSTOMIZE button

In the standard Zakeke usage flow, the Customizer UI (the IFrame) is opened from the product page through the 'Customize' call to action (typically a button). This button becomes visible when a product is configured as customizable in the Zakeke back-office. Here's a summary of the standard flow: Customize > Zakeke UI > Add to Cart > Cart.

It's essential to note that this flow is optional, as long as you implement an alternative system to open the IFrame. However, if you choose to implement the 'Customize' button, follow these steps:

Product-Page

5.1 Adding Customizer Button

This is usually an HTML button to be placed next to the "ADD TO CART" button:

<button id="btnCustomize" type="button">Customize<button>

Clearly you can use any HTML element as long as it has as btnCustomize identifier.

5.2 HTML FORM

Before closing the body tag, you will need to add the following html FORM:

<form id="frmCustomizer" action="{Customizer URL}">
<input type="hidden" name="quantity" />
<input type="hidden" name="productid" />
<input type="hidden" name="{attributeKey1}" />
..
<input type="hidden" name="{attributeKeyn}" />
</form>

Where:

AttributeAttribute valueDescription
form actionCustomizer URLURL of the created customizer page (refer to the reference section of the URL documentation).
input namequantityQuantity to add to cart.
input nameproductidUnique product ID.
input nameattributeKeyProduct attribute key (e.g. "color", "size", etc.).

N.B. Attribute keys must match those defined in the imported products CSV. Go to how to import products for more details.

5.3 JavaScript to Send the Product Selection to the Customizer

After the HTML form and before closing the Body tag, enter the following script. It allows you to send the product selection to the customizer after clicking the "Customize" button. The script retrieves information on the quantity and options chosen for the attributes of any product variant from a hypothetical FORM present on the product page. It is clear that this logic must be adapted to the particular user interface of the product page. The clear thing is that the data relating to the quantity and product variant chosen by the user must be retrieved and sent to the Zakeke IFrame via the form prepared with the previous script.

<script>

var btnCustomizer = document.getElementById('btnCustomize');
btnCustomizer.addEventListener('click',
function(evt) {

evt.preventDefault();
var formCustomizer = document.getElementById("frmCustomizer");
var formProductPage = document.getElementById("{idFormProduct}");
formCustomizer.elements["productid"].value = { productid };
formCustomizer.elements["quantity"].value = formProductPage.elements["quantity"].value;
formCustomizer.elements["attributeKey1"].value = formProductPage.["attributeKey1"].value;
...
formCustomizer.elements["attributeKeyn"].value = formProductPage.elements["attributeKeyn"].value;
formCustomizer.submit();

});

</script>

Where:

AttributeDescription
idFormProductFORM tag ID of the product page
productidUnique product I

5.4 Full HTML code Example

Below the sample code of a product page with the "customize" button integrated:

<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>Customizable T-Shirt</title>
</head>
<body>
<div class="content">
<div class="foto">
<img alt="Customizable T-Shirt" src="http://your.store.com/images/product.jpg" />
</div>
<div class="details">
<h1>Customizable T-Shirt - sku: 00001</h1>
<p>Description product.....</p>
<form id="frmAddToCart" action="https://your.store.com/shopping-cart.html">
<select name="quantity">
<option>1</option>
<option>2</option>
<option>3</option>
<option>4</option>
<option>5</option>
</select>
<select name="color">
<option value="0">Black</option>
<option value="1">Red</option>
<option value="2">White</option>
<option value="3">Green</option>
</select>
<select name="size">
<option value="0">S</option>
<option value="1">M</option>
<option value="2">L</option>
<option value="3">XL</option>
</select>
<button id="addToCart" type="submit">Add to shopping cart</button>
<button id="btnCustomize" type="button">Customize</button>
</form>
</div>
</div>
<form id="frmCustomizer" action="https://your.store.com/customizer.html">
<input type="hidden" name="sku" />
<input type="hidden" name="quantity" />
<input type="hidden" name="color" />
<input type="hidden" name="size" />
</form>
<script>

var btnCustomizer = document.getElementById('btnCustomize');
btnCustomizer.addEventListener('click',
function(evt)
{
evt.preventDefault();
var formCustomizer = document.getElementById("frmCustomizer");
var formProductPage = document.getElementById("frmAddToCart");
formCustomizer.elements["productid"].value = '00001';
formCustomizer.elements["quantity"].value = formProductPage.elements["quantity"].value;
formCustomizer.elements["color"].value = formProductPage.elements["color"].value;
formCustomizer.elements["size"].value = formProductPage.elements["size"].value;
formCustomizer.submit();
});

</script>
</body>
</html>