Customizer Integration Documentation

This document describes how to integrate the Customizer library into a custom ecommerce store.


For Shopify integration please check Shopify page.

Initialization

Add the script to your HTML file:

<script src="https://cdn.idealfactory.com/editors/customiser_xxx.min.js"></script>

Make sure to have a container element in your HTML:

<div id="customizer-container"></div>

To initialize the Customizer, create a new instance of the Customizer class with your configuration:

const customizer = new Customizer({
    containerId: 'customizer-container',
    iframeSrc: 'provided individually for each client',
    direct_product_id: 'xxxxxxxx',
    language: 'en',
    editor_id: 'xxxxxxxx',
    products_category_id: 'xxxxxxx',
    products_prices: 'json of prices',
    template_config: 'encoded json file',
    cart_item_uid: 'cart-item-uid',
    onAddToCart: handleAddToCart,
    onProductDetails: onProductDetails,
    platform: 'shopify' // Specify your platform here
});

Configuration

The Customizer library requires a configuration object with the following properties:

  • containerId (string): The ID of the HTML element where the iframe will be inserted.
  • iframeSrc (string): The source URL for the customizer iframe.
  • width (string): The width of the iframe (default: '100%').
  • height (string): The height of the iframe (default: '100%').
  • direct_product_id (string): The ID of the product to be customized.
  • language (string): The language code for the customizer (default: 'en').
  • editor_id (string): The ID of the editor to be used.
  • enable_hints (boolean): Whether to enable hints in the customizer.
  • allow_disabling_hints (boolean): Whether to allow disabling hints.
  • products_category_id (string): The category ID containing multiple products.
  • products_prices (string): JSON string of product prices.
  • template_config (string): The initial template configuration.
  • cart_item_uid (string): The unique identifier for the cart item.
  • onAddToCart (function): Callback function to handle add to cart events.
  • onProductDetails (function): Callback function when additional product details button is clicked.
  • platform (string): The e-commerce platform or environment type. Valid values are:
    • 'custom': For custom e-commerce implementations
    • 'shopify': For Shopify themes
    • 'shopify-headless': For headless Shopify implementations
    • 'magento': For Magento e-commerce platform
    • 'salesforce': For Salesforce Commerce Cloud
    • 'standalone': For non-e-commerce implementations (e.g., kiosk-based)

Handling Add to Cart

The onAddToCart callback will be called when the user adds a customized product to the cart. Implement this function to handle the cart addition in your ecommerce system:

function handleAddToCart(cartData) {
  console.log('Adding to cart:', cartData);
    // {
    //     _template_config: string
    //     _thumbnails: array
    //     _cart_item_uid: string
    // }
  // Implement your cart addition logic here
  // For example, you might want to:
  // 1. Update the cart UI
  // 2. Send the data to your backend
  // 3. Show a confirmation message to the user
}

API Reference

Customizer Methods

  • initialize(): Sets up the iframe and message listeners.
  • sendMessage(message): Sends a message to the iframe.
  • onEditorReady(): Called when the editor is ready.
  • onEditorClosed(): Called when the editor is closed.
  • onDesignSaved(data): Called when a design is saved.
  • onAddToCart(data): Handles the add to cart event.
  • handleBack(): Handles the back navigation event.

Events

The Customizer listens for the following events from the iframe:

  • iframe_ready: Indicates that the iframe is ready.
  • editor_exit: Indicates that the editor has been closed.
  • design_ready: Indicates that a design has been saved.
  • add_to_cart: Triggers the add to cart process.
  • back: Triggers back navigation.


For any additional customization or integration needs please contact us.