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:
The integration of the customizer into your e-commerce website requires the following steps:
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... -->
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
is a JSON object formed by:
productid (string) | Unique product ID |
productname (string) | Name of the customizable product |
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
|
|
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
|
|
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 |
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) |
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 |
|
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 }); } }
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 ... } } }
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>
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 ... } } }
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>
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 |