Customizer UI API

Summary

Overview
Create the Customizer Page
Configuration JavaScript
3.1 config
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
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.

Property	Description	Additional info
tokenOauth	Authentication 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
productId	Unique product ID	Type: `string` Required: true
productName	Name product	Type: `string` Required: true
designId	Zakeke generated unique design ID of the customized product to be modified.	Type: `string` Default: empty Required:: false (mandatory for editing a custom product design)
loadTemplateId	Opens the iframe directly with the declared templateID	Type: `string` Default: empty Required:: false
currency	Example: USD. Currency selected by the customer on your store, with ISO 4217 encoding.	Type: `string` Default: empty Required:: true
culture	Example: en-US. IFRAME interface language based on Microsoft encoding table. For details on encoding go to this link.	Type: `string` Default: empty Required:: true
mobileVersion	`true`: 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
labelTax	Indicates 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
quantity	Customizable product quantity to be added/edited	Type: `integer` Default: undefined Required:: true
imagePreviewHeight	Height in pixel of the preview generated by Zakeke	Type: `integer` Default: 200 Required:: false
imagePreviewWidth	Width in pixel of the preview generated by Zakeke	Type: `integer` Default: 200 Required:: false
isClientPreviews	Flag to enable the generation of the preview image for each side of the customized product.	Type: `boolean` Default: `false` Required:: false
cartButtonText	Label of the "Add to cart" button inside the IFRAME Add to cart	Type: `string` Default: empty Required: false
hideVariants	If it is false, you will have the opportunity to change the variant. For more details go to hideVariants	Type: `boolean` Default: false Required: false
getProductInfo	JavaScript 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`
getProductPrice	JavaScript feature on Merchant website to send the final price of the product. how to configure the "getProductPrice"	Type: `function` Default: `none` Required: `true`
getProductAttribute	JavaScript function on Merchant web site. For more details go to how to configure the "getProductAttribute".	Type: `function` Default: undefined Required: `true`
addToCart	JavaScript 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`
editAddToCart	JavaScript 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`
isNamesAndNumbers	Enable the Name And Number feature	Type: `boolean` Default: `false` Required: `false`
addToCartNameAndNumber	JavaScript 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)
editAddToCartNameAndNumber	JavaScript 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)
isMultipleVariations	Enable Bulk Variation Forms feature	Type: `boolean` Default: `false` Required:: false
addToCartBulk	JavaScript 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)
editAddToCartBulk	JavaScript 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)
isBulkIndividualFile	Enables 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
isSharedDesign	Allows the merchant to manage the share functionality	Type: `boolean` Default: `false` Required: `false`
getSharedDesign	JavaScript feature on the Merchant’s website to manage the share functionality. For more details go to how to configure the "getSharedDesign".
shareUrlPrefix	Option to enter the domain of the merchant in the preview URL	Type: `string` Default: empty Required:: `false`
isSaveDesign	`true`: 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`
getSaveDesign	JavaScript 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)
sides	Example:['side1','side2'] Codes of product sides (defined in the sides CSV) on which customization is allowed	Type: `array of string` Default: undefined Required:: false
additionalData	Additional data to send to merchant	Type: `object` Default: undefined Required: `false`
selectedAttributes	Selected 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:

Property	Type	Description	Required
productId	`string`	Unique product ID
quantity	`integer`	Selected quantity of product to be customized
selectedattributes	`array`	array of key-vaue pair of selected product attributes N.B. the attribute keys match those imported from CSV
price	`money`	Unit price (in the currency of your e-commerce) of the created design to be added to the one of the product
percentPrice	`money`	Percentage of the created design to be added to the one of the product, to be applied to the unit price of the product
additionaldata	`object`	Additional data to send to JavaScript function	optional

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:

Property	Type	Description
finalprice	`money`	Final price calculated depending on the added design and unit price of the model product
isoutofstock	`boolean`	`false`: 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:

getProductInfo

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:

Property	Type	Description
productId	`string`	Unique product ID
designId	`string`	Unique design ID applied to the customized product
quantity	`integer`	Quantity of customized product to add to shopping cart
selectedattributes	`array`	array 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:

Property	Type	Description
productId	`string`	Unique product ID
designId	`string`	Unique design ID applied to the customized product
quantity	`integer`	Quantity of customized product to add to shopping cart
selectedattributes	`array`	array 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:

Attribute	Description
designId	Unique 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:

Property	Type	Description
productId	`string`	Unique product ID
selectedattributes	`array`	array of key-value pair of selected attributes
quantity	`integer`	Quantity of customized product to add to shopping cart
percentagePrice	`number`	Percentage increase in product price due for customization, if any
price	`money`	Unit 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

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:

Attribute	Description
price	Final product unit price, including both the product price and the design price.
isoutofstock	`false`: 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:

Property	Type	Description
productId	`string`	Unique 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:

Property	Type	Description
Attributes	`array`	The list of the product attributes
Variants	`array`	The 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:

Property	Type	Description
code	`string`	The attribute identifier (code or key) in the ecommerce
label	`string`	The attribute name that can also be used in a selection user interface
values	`array`	the 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:

Property	Type	Description
code	`string`	The attribute identifier (code or key) in the ecommerce
value	`object`	The 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:

Property	Type	Description
productId	`string`	Unique product ID
designId	`string`	Unique design ID applied to the customized product
namesandnumbers	`array`	The list of specific values to apply to the design fields and for which product variations
previews	`array`	The 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:

Property	Type	Description
modificationid	`string`	Unique identifier generated by Zakeke for the field value combination
elementdescs	`object`	The list of values for the design fields
selectedattributes	`array`	Array of key-value pair of selected attributes
quantity	`integer`	The quantity of customized product for the combination of design field values to add to cart
previewimageurl	`string`	The 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:

Property	Type	Description
productId	`string`	Unique product ID
designId	`string`	Unique 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:

Property	Type	Description
productId	`string`	Unique product ID.
designId	`string`	Unique design ID applied to the customized product.
bulkvariations	`array`	Array of variants with the desired quantity for each of them.
previews	`array`	Array 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:

Property	Type	Description
productId	`string`	Unique product ID.
designId	`string`	Unique design ID applied to the customized product.
bulkvariations	`array`	Array of variants with the desired quantity for each of them.
previews	`array`	Array 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:

Property	Type	Description
productId	`string`	Unique product ID
designId	`string`	Unique design ID applied to the customized product
bulkvariations	`array`	Array of variants with the desired quantity for each of them.
previews	`array`	Array 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:

Property	Type	Description
modificationid	`string`	Unique identifier generated by Zakeke for the variant
selectedattributes	`array`	Array of key-value pair of selected attributes
quantity	`integer`	The quantity of customized product for the combination of design field values to add to cart
previewimageurl	`string`	The 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:

Attribute	Attribute value	Description
form action	`Customizer URL`	URL of the created customizer page (refer to the reference section of the URL documentation).
input name	`quantity`	Quantity to add to cart.
input name	`productid`	Unique product ID.
input name	`attributeKey`	Product 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:

Attribute	Description
`idFormProduct`	FORM tag ID of the product page
`productid`	Unique 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>

Customizer UI API

Summary​

1. Overview​

2. Create the Customizer Page​

3. Configuration JavaScript​

3.2 Config​

4. JavaScript callback​

4.1 GetProductInfo​

4.2 AddToCart​

4.2.1 JavaScript callback​

4.3 EditAddToCart​

4.3.1 JavaScript callback​

4.4 GetSaveDesign​

4.5 GetProductPrice​

4.5.1 JavaScript callback​

4.6 GetProductAttribute​

4.6.1 Callback request data​

4.6.2 JavaScript callback​

4.7 AddToCartNameAndNumber​

4.7.1 Callback request data​

4.7.2 JavaScript callback​

4.8 EditAddToCartNameAndNumber​

4.8.1 Callback request data​

4.8.2 JavaScript callback​

4.9 OnBackClicked​

4.10 SharedDesignUrl​

4.10.1 Callback request data​

4.10.2 JavaScript callback​

4.11 AddToCartBulk​

4.11.1 Callback request data​

4.11.2 JavaScript callback​

4.12 EditAddToCartBulk​

4.12.1 Callback request data​

4.12.2 JavaScript callback​

4.13 AddToCartBulk​

4.13.1 Callback request data​

4.13.2 JavaScript callback​

4.14 EditAddToCartBulk​

4.14.1 Callback request data​

4.14.2 JavaScript callback​

4.15 HideVariants​

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​

Summary

1. Overview

2. Create the Customizer Page

3. Configuration JavaScript

3.2 Config

4. JavaScript callback

4.1 GetProductInfo

4.2 AddToCart

4.2.1 JavaScript callback

4.3 EditAddToCart

4.3.1 JavaScript callback

4.4 GetSaveDesign

4.5 GetProductPrice

4.5.1 JavaScript callback

4.6 GetProductAttribute

4.6.1 Callback request data

4.6.2 JavaScript callback

4.7 AddToCartNameAndNumber

4.7.1 Callback request data

4.7.2 JavaScript callback

4.8 EditAddToCartNameAndNumber

4.8.1 Callback request data

4.8.2 JavaScript callback

4.9 OnBackClicked

4.10 SharedDesignUrl

4.10.1 Callback request data

4.10.2 JavaScript callback

4.11 AddToCartBulk

4.11.1 Callback request data

4.11.2 JavaScript callback

4.12 EditAddToCartBulk

4.12.1 Callback request data

4.12.2 JavaScript callback

4.13 AddToCartBulk

4.13.1 Callback request data

4.13.2 JavaScript callback

4.14 EditAddToCartBulk

4.14.1 Callback request data

4.14.2 JavaScript callback

4.15 HideVariants

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