ZAKEKE - Customizer page

Customizer page

The customizer page is the fundamental part of Zakeke integration into your e-commerce website.
It will allow your customers to create or modify their customizations based on your models imported through the CSV catalogue, and then to add them to the shopping cart.

It will be shown in these case:

1. to create a new custom product by clicking the "customize" button from the model product page
2. to change the design of a custom product in the cart

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 contain the IFrame of the ZAKEKE customizer
2.Entering configuration Javascript
3. Defining the following endpoints in your website, which will be recalled by Zakeke for:
- 3.1 "ProductInfo" endpoint: obtaining information on the product selected by the customizer
- 3.2 "AddToCart" endpoint: adding a product to the shopping cart
- 3.3 "EditProductIntoCart" endpoint: modifying a custom product of the shopping cart

1. Create the customizer page

In your e-commerce website you have to create a new page (in the example a 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... -->

2. Configuration Javascript

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

<script src="https://www.zakeke.com/scripts/config.js"></script>
<script src="https://www.zakeke.com/scripts/integration/api/customizer.js"></script>

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

<script>
    var config = {config};
    var productJson = {"id":"[productid]", "name":"[productname]"};
    var customizer = new zakekeDesigner(config, productJson);
</script>

productJson

productJson is a JSON object formed by:

productid (string)	Unique product ID
productname (string)	Name of the customizable product

config

config is a javascript object structured as follows:

{
  "tokenoauth": "Token Oauth",
  "mobileversion": false,
  "cartbuttontext": "Add to cart",
  "shoppingcarturl": "[url-endpoint-add-to-cart]",
  "shoppingcarturlcallback": {javascript function object},
  "editshoppingcarturl": "[url-endpoint-edit-product-into-cart]",
  "editshoppingcartcallback": {javascript function object},
  "savedesigncallback": {javascript function object},
  "productinfourl": "[url-endpoint-info-product]",
  "additionaldata":  {},
  "canSaveDesign": false,
  "culture": "en-US",
  "currency": "USD",
  "designid": "",
  "pricetaxincluded": true,
  "labeltax": "hidden",
  "quantity": 1,
  "sides": ['codeSide1',...,'codeSiden'],
  "selectedattributes": {
      "attributekey1": "selectedattributevalue1",
      //...//
      "attributekeyn": "selectedattributevaluen"
  }
}

whose properties are defined in the table below:

Property	Description	Default value
tokenoauth mandatory type: `string`	Authentication Token Oauth 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")
mobileversion optional type: `boolean`	`true`: customizer IFRAME will be adapted for the mobile version `false`: customizer IFRAME will be adapted for the desktop version	`false`
cartbuttontext optional type: `string`	Label of the "Add to cart" button inside the IFRAME	Add to cart
shoppingcarturl Optional (mandatory if `shoppingcartcallback` has not been defined) type: `string`	Endpoint URL to add the custom product to the shopping cart For more details go to how to configure the "AddToCart" endpoint
shoppingcartcallback Optional (mandatory if `shoppingcarturl` has not been defined) type: `object`	Javascript function on Merchant web site to handle adding of customized product to shopping cart. For more details go to how to configure the "EditProductIntoCart" endpoint.
editshoppingcarturl optional (mandatory if `editshoppingcartcallback` has not been defined) type: `string`	Endpoint URL to manage custom product editing from shopping cart. For more details go to how to configure the "EditProductIntoCart" endpoint.
editshoppingcartcallback optional (mandatory if `editshoppingcarturl` has not been defined) type: `object`	Javascript function on Merchant web site to handle editing of customized product into shopping cart. For more details go to how to configure the "EditProductIntoCart" endpoint.
canSaveDesign optional type: `boolean`	`true`: enable feature to save or change existing design for a customized product previously added into cart `false`: disable feature explained above	`false`
savedesigncallback optional (mandatory if `canSaveDesign` is set to true) type: `object`	Javascript function on Merchant web site to handle change design event of customized product into shopping cart. For more details go to how to configure the "SaveDesign" endpoint.
productinfourl mandatory type: `string`	Endpoint URL to obtain product information based on the selection of attributes. For more details go to how to configure the "ProductInfo" endpoint.
additionaldata optional type: `json object`	Additional data to send to merchant endpoints
culture mandatory type: `string` Example: en-US	IFRAME interface language based on Microsoft encoding table. For details on encoding go to this link.
currency mandatory type: `string` Example: USD	Currency selected by your the customer on your store, with ISO 4217 encoding.
designid mandatory for editing a customized product type: `string`	Zakeke generated ID design of the customized product to be modified.
labeltax Optional type: `string`	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`
quantity mandatory type: `integer`	Customizable product quantity to be added/edited
imagepreviewheight optional type: `integer`	Height in pixel of the preview generated by Zakeke	`200`
imagepreviewwidth optional type: `integer`	Width in pixel of the preview generated by Zakeke	`200`
sides optional type: `array of string` Example: ['side1','side2']	Codes of product sides (defined in the sides CSV) on which customization is allowed
selectedattributes mandatory if the product has variants type: `JSON object` Example: {'color':0,'size':1}	Selected product attributes sent to the customizer page. They are formed by a key-value pair consisting respectively of the attribute name (used in forms) and the coded value. N.B.The key value pairs must match the attributes imported in the CSV feed. (For more details go to how importing products through CSV)

3. Server Side Endpoints

3.1. Endpoint ProductInfo

Zakeke IFRAME will need to call an endpoint(or callback) implemented in your e-commerce in order to get information such as the updated price inclusive of design.

The endpoint will be requested in POST, where the following JSON object will be sent into body request:

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

Where:

`productid` (string)	Unique product ID
`quantity` (integer)	selected quantity of product to be customized
`selectedattributes`	key-value pair of selected product attributes N.B. the attribute keys match those imported from CSV
`zakekeprice` (money)	unit price (in the currency of your e-commerce) of the created design to be added to the one of the product
`zakekepercentageprice` (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 (json object)` (optional)	Additional data to send to endpoint

Endpoint Response in JSON format, must be structured as follows:

{   
    "finalprice": money,
    "isoutofstock": boolean
}

Where:

`finalprice`	Final price calculated depending on the added design and unit price of the model product
`isoutofstock`	`false`: if product is in stock `true`: if product is not available (out of stock, ect.)

Below is an example in ASP. NET MVC C# of the ProductInfo Endpoint:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
public class EndpointZakekeController : Controller
{
    [HttpPost]
    [Route("zakeke/getproductinfo")]
    public JsonResult GetInfoProduct(string jsonInput)
    {
        // Deserialize JSON and get relative properties
        JObject jsonObj = JObject.Parse(jsonInput);
        decimal finalPrice = 0m;
        string productid = (string)jsonObj["productid"];
        int quantity = (int)jsonObj["quantity"];
        Dictionary<string,string> selectedattributes = ((IDictionary<string, string>)jsonObj["selectedAttributes"]).ToDictionary(p => p.Key, p => p.Value);
        decimal zakekePrice = (decimal)jsonObj["zakekePrice"];
        decimal zakekePercentagePrice = (decimal)jsonObj["zakekePercentagePrice"];
        ProductEntity product = null;
        // ProductEntity has these properties:
        // 1. unitPrice : unitary product price
        // 2. stockquantity: quantity stock
           
        // Code to get product object from id and selected attributes (depending by ORM used)
        // ....
        finalPrice = (product.unitPrice * quantity) + zakekePrice;
        if (zakekePercentagePrice > 0m)
        {
            finalPrice += (product.unitPrice * zakekePercentagePrice * quantity) / 100;
        }
        return Json(new
        {
            finalprice = finalPrice,
            isoutofstock = product.stockquantity < quantity
        });
    }
}

3.2 Endpoint AddToCart

Clicking "Add to cart" button inside IFRAME interface, will perform a POST request to the endpoint "AddToCart" with aim of adding customized product to shopping cart.

Endpoint Response in JSON format, must be structured as follows:

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

Where:

`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`	key-value pair of selected attributes N.B. attribute keys match those imported by CSV products
`additionaldata (json object)` (optional)	Additional data to send to endpoint

Note that designid is present in the request, which is needed to obtain design information to send to shopping cart, created using the REST API. (Go to DESIGN API for more information.) In response, the endpoint must provide a JSON object that will contain the URL of the shopping cart page

{   
    "returnurl": string (shopping cart URL)
}

Below is an example in ASP. NET MVC C# of the AddToCart endpoint:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using RestSharp;
public class EndpointZakekeController : Controller
{
    [HttpPost]
    [Route("zakeke/addtocart")]
    public JsonResult AddProductToCart(string jsonInput)
    {
        // Deserialize JSON and get relative properties
        JObject jsonObj = JObject.Parse(jsonInput);
        string productid = (string)jsonObj["productid"];
        string designid = (int)jsonObj["designid"];
        int quantity = (int)jsonObj["quantity"];
        Dictionary<string,string> selectedattributes = ((IDictionary<string, string>)jsonObj["selectedAttributes"]).ToDictionary(p => p.Key, p => p.Value);
        
        // Get User shopping cart
        ShoppingCartEntity cart = null;
        // Code to get user shopping cart ....
        // Get Design information via Zakeke API Rest using RestSharp (see API reference for details)
        Design designinfo = null;
        var client = new RestClient("https://api.zakeke.com/v1/designs/" + designid);
        var request = new RestRequest() { Method = Method.GET };
        request.AddHeader("Authorization", "Bearer " + "Your OAuth Token S2S");
        try
        {
            var response = client.Execute(request);
            if (response != null && response.StatusCode == System.Net.HttpStatusCode.OK)
            {
                design = new ZakekeDesign();
                JObject responseJson = JsonConvert.DeserializeObject<JObject>(response.Content);
                string urlPreviewImage = responseJson["tempPreviewImageUrl"].ToString();
                decimal designUnitPrice = decimal.Parse(responseJson["designUnitPrice"].ToString());
                decimal designUnitPercentagePrice = decimal.Parse(responseJson["designUnitPercentagePrice"].ToString());
                decimal priceToAdd = ((design.designUnitPercentagePrice / 100) * prodotto.PrezzoUnitarioScontato) + design.designUnitPrice;
                cart.Add(productid, designid, pricetoadd, quantity, urlPreviewImage);
    
                return Json(new { returnurl = "http://your.store.com/shopping-cart" });
            }
        }
        catch (Exception ex)
        {
            // Handle exception ...
        }
    }
}

3.2.1 Callback javascript

Alternatively, if the shoppingcartcallback property is defined in the configuration javascript, you can use a javascript functions to manage the adding of the customized product to the cart. The callback will receive the json object defined above as input.

<script>
// Callback edit product into shopping cart
function callback(jsonInput)
{
    // callback code to handle adding customized product to shopping cart event
}
    
// Customizer config
var config = 
{
    ...
shoppingcartcallback : callback,
    ...
}
// Product config
var productJson  = 
{
    ...
}
var customizer = new zakekeDesigner(config, productJson);
</script>

3.3 Endpoint EditProductIntoCart

When a customized product into cart is modified, the button add to the shopping cart will be replaced with the "edit" button, whose callback will be managed by the "EditProductIntoCart" endpoint.

The endpoint must update the custom product previously added into the shopping cart, with the one with the new design.

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

The following JSON object will be sent in the body of the request:

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

Where:

`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`	key-value pair of selected attributes N.B. attribute keys match those imported by CSV products
`additionaldata (json object)` (optional)	Additional data to send to endpoint

Note that the designid is present in the request, which is needed to obtain design information created using the REST API. (Go to DESIGN API for more information.) In response, the endpoint must provide a JSON object that will contain the URL of the shopping cart page

{   
    "returnurl": string (shopping cart url)
}

Below is an example in ASP. NET MVC C# of the EditProductIntoCart endpoint:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Mvc;
using Newtonsoft.Json;
using Newtonsoft.Json.Linq;
using RestSharp;
public class EndpointZakekeController : Controller
{
    [HttpPost]
    [Route("zakeke/editproduct")]
    public JsonResult EditProductIntoCart(string jsonInput)
    {
        // Deserialize JSON and get relative properties
        JObject jsonObj = JObject.Parse(jsonInput);
        string productid = (string)jsonObj["productid"];
        string designid = (int)jsonObj["designid"];
        int quantity = (int)jsonObj["quantity"];
        Dictionary<string,string> selectedattributes = ((IDictionary<string, string>)jsonObj["selectedAttributes"]).ToDictionary(p => p.Key, p => p.Value);
        
        // Get User shopping cart
        ShoppingCartEntity cart = null;
        // Code to get user shopping cart ....
        // Get Design information via Zakeke API Rest using RestSharp (see API reference for details)
        Design designinfo = null;
        var client = new RestClient("https://api.zakeke.com/v1/designs/" + designid);
        var request = new RestRequest() { Method = Method.GET };
        request.AddHeader("Authorization", "Bearer " + "Your OAuth Token S2S");
        try
        {
            var response = client.Execute(request);
            if (response != null && response.StatusCode == System.Net.HttpStatusCode.OK)
            {
                design = new ZakekeDesign();
                JObject responseJson = JsonConvert.DeserializeObject<JObject>(response.Content);
                string urlPreviewImage = responseJson["tempPreviewImageUrl"].ToString();
                decimal designUnitPrice = decimal.Parse(responseJson["designUnitPrice"].ToString());
                decimal designUnitPercentagePrice = decimal.Parse(responseJson["designUnitPercentagePrice"].ToString());
                decimal priceToAdd = ((design.designUnitPercentagePrice / 100) * prodotto.PrezzoUnitarioScontato) + design.designUnitPrice;
                // Remove from cart, customized product with the old design
                cart.Remove(productid, quantity, designid);
                // Add to cart, customized product with the new design
                cart.Add(productid, designid, pricetoadd, quantity, urlPreviewImage);
    
                return Json(new { returnurl = "http://your.store.com/shopping-cart" });
            }
        }
        catch (Exception ex)
        {
            // Handle exception ...
        }
    }
}

3.3.1 Callback javascript

Alternatively, if the editshoppingcartcallback property is defined in the configuration javascript, you can use a javascript functions to manage the editing of the customizer product into the cart. The callback will receive the json object defined above as input.

<script>
// Callback edit product into shopping cart
function callback(jsonInput)
{
    // callback code to handle edit customized product event
}
    
// Customizer config
var config = 
{
    ...
editshoppingcartcallback : callback,
    ...
}
// Product config
var productJson  = 
{
    ...
}
var customizer = new zakekeDesigner(config, productJson);
</script>

3.4 Save design javascript callback

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

{
    "designid": string
}

Where:

designid Unique design ID