Skip to main content

Interface: Utils

Set of utility functions for common operations within the Mimeeq configurator.

The Utils interface provides methods for taking screenshots, generating shortcodes, setting prices, and controlling configurator visibility. These utilities simplify common tasks and provide access to functionality that would otherwise require more complex implementation.

Example​

// Take a high-resolution screenshot of the current configuration
window.mimeeqApp.utils.takeScreenshot('png', 2048)
  .then(imageBase64 => {
    // Use the image (e.g., display it, save it, or send it to a server)
    document.getElementById('product-image').src = imageBase64;
  });

Pricing​

setPrice​

setPrice: SetPrice

Sets custom pricing data for the current product configuration.

This method allows you to override the default pricing from Mimeeq with your own custom pricing logic. It accepts a price object that can include total price, currency, and delivery time information.

This is particularly useful for integrating with external pricing systems or implementing special pricing rules not available in Mimeeq's standard pricing engine.

Note: To use this method, you must enable "Use Custom Pricing" in the embed settings. Currently, modular product configurators only accept total price, not component prices.

Example​

// Set a custom price with delivery time
window.mimeeqApp.utils.setPrice({
  price: 1299.99,             // Total price
  currency: 'USD',            // Currency code
  deliveryTime: '14-21 days', // Estimated delivery time
  levels: [                   // Quantity break pricing
    { quantityMin: 1, quantityMax: 9, price: 1299.99 },
    { quantityMin: 10, quantityMax: 49, price: 1199.99 },
    { quantityMin: 50, quantityMax: 999999, price: 1099.99 }
  ]
});

// Listen for price change events to know when to update prices
document.addEventListener('mimeeq-price-change', () => {
  fetchPriceFromExternalSystem().then(priceData => {
    window.mimeeqApp.utils.setPrice(priceData);
  });
});

Param​

Price data object containing price, currency, and optional delivery time

setPricingSettings​

setPricingSettings: SetPricingSettings

Configures the decimal place settings for price display.

This method allows you to control how prices are formatted in the Mimeeq configurator by specifying the minimum and maximum number of decimal places to show. This helps maintain consistent price formatting across your application.

Example​

// Show prices with exactly 2 decimal places
window.mimeeqApp.utils.setPricingSettings(2, 2);

// Show prices with at least 2 decimal places and at most 4
window.mimeeqApp.utils.setPricingSettings(2, 4);

Param​

Minimum number of decimal places to display (default: 2)

Param​

Maximum number of decimal places to display (default: 2)

Product​

getShortcode​

getShortcode: GetShortcode

Generates a unique shortcode for a specific product configuration.

This method creates a persistent, shareable identifier for a specific product configuration. The same product-configuration pair will always generate the same shortcode, allowing for consistent referencing.

Shortcodes are used for sharing configurations, creating AR experiences, and referencing specific states in marketing materials or e-commerce.

Note: This method works only for standard products. Shortcodes are returned as part of the mimeeq-add-to-cart event. There is also configurationShortCode observer - please use them rather than through this method.

Example​

// Generate a shortcode for the current product configuration
window.mimeeqApp.utils.getShortcode('prod_123', 'A1-B2-C3')
  .then(shortcode => {
    console.log(`Shareable configuration link: https://example.com/config/${shortcode}`);
  });

Param​

Unique identifier for the product

Param​

Configuration code string representing the selected options

Returns​

A promise resolving to the generated shortcode string

Scene​

takeScreenshot​

takeScreenshot: TakeScreenshot

Captures a screenshot of the current product configuration.

This method generates a high-quality image of the current configuration state, which can be used for thumbnails, sharing, printing, or exporting. The method offers flexible options for image format, size, and appearance.

Under the hood, it clones the existing scene and calls captureImage() to ensure the screenshot doesn't disrupt the user's current view.

Example​

// Take a 1200px wide PNG screenshot with a white background
window.mimeeqApp.utils.takeScreenshot('png', 1200, '#ffffff')
  .then(imageBase64 => {
    // Use the base64-encoded image
    const img = document.createElement('img');
    img.src = imageBase64;
    document.body.appendChild(img);
  });

// Take a JPEG screenshot with custom dimensions and camera position
window.mimeeqApp.utils.takeScreenshot(
  'jpg',                      // JPEG format
  1800,                       // Width in pixels
  '#f0f0f0',                  // Light gray background
  { width: 1800, height: 1200 }, // Custom dimensions
  true,                       // Auto-zoom to fit product
  true,                       // Reset camera to initial position
  JSON.stringify({            // Custom camera position
    position: {x: -1.5, y: 1.7, z: -5.2},
    alpha: 4.4,
    beta: 1.3,
    target: {x: 0, y: 0.6, z: 0}
  })
);

Param​

File extension for the output image (default: 'png'). Supported values: 'png', 'jpg', 'jpeg'.

Param​

Image width in pixels (default: 3072). Height is calculated based on canvas aspect ratio. Note: On iOS devices, sizes larger than 2048 may cause performance issues.

Param​

Background color for JPEG images (default: '#fff'). Accepts hex color values. For PNG, this controls transparency.

Param​

Optional custom dimensions that override the default sizing.

Param​

When true, automatically zooms out to ensure the entire product is visible.

Param​

When true, resets the camera to its initial position before capturing.

Param​

JSON string with custom camera positioning data.

Returns​

A promise resolving to a base64-encoded image string, or null if unsuccessful.

Utils​

addToCart​

addToCart: AddToCart

Triggers the "add to cart" or "finish" action for the current configuration.

This method programmatically executes the same action that occurs when a user clicks the "Add to Cart" or "Finish" button in the configurator. It prepares all the necessary configuration details and dispatches the appropriate events.

Example​

// Add the current configuration to the cart when a custom button is clicked
document.getElementById('custom-add-to-cart').addEventListener('click', () => {
  window.mimeeqApp.utils.addToCart();
});

// Listen for the add to cart event to handle the data
document.addEventListener('mimeeq-add-to-cart', (e) => {
  console.log('Product added to cart:', e.detail);
  // Add the product to your e-commerce system
});

Fires​

@mimeeqmimeeq-add-to-cart

closeConfigurator​

closeConfigurator: CloseConfigurator

Closes and unmounts the active configurator from the DOM.

This method removes a currently visible configurator from the page and cleans up its resources. It works for both standard and modular configurators and is useful for single-page applications or dynamic UI changes.

Example​

// Close the configurator when a close button is clicked
document.getElementById('close-config-btn').addEventListener('click', () => {
  window.mimeeqApp.utils.closeConfigurator();
});

Deprecated​

Method works only for legacy embed version. If you are using web component please use its hide() method instead

Fires​

@mimeeq#mimeeq-unmount

getShortcode​

getShortcode: GetShortcode

Generates a unique shortcode for a specific product configuration.

This method creates a persistent, shareable identifier for a specific product configuration. The same product-configuration pair will always generate the same shortcode, allowing for consistent referencing.

Shortcodes are used for sharing configurations, creating AR experiences, and referencing specific states in marketing materials or e-commerce.

Note: This method works only for standard products. Shortcodes are returned as part of the mimeeq-add-to-cart event. There is also configurationShortCode observer - please use them rather than through this method.

Example​

// Generate a shortcode for the current product configuration
window.mimeeqApp.utils.getShortcode('prod_123', 'A1-B2-C3')
  .then(shortcode => {
    console.log(`Shareable configuration link: https://example.com/config/${shortcode}`);
  });

Param​

Unique identifier for the product

Param​

Configuration code string representing the selected options

Returns​

A promise resolving to the generated shortcode string

setPrice​

setPrice: SetPrice

Sets custom pricing data for the current product configuration.

This method allows you to override the default pricing from Mimeeq with your own custom pricing logic. It accepts a price object that can include total price, currency, and delivery time information.

This is particularly useful for integrating with external pricing systems or implementing special pricing rules not available in Mimeeq's standard pricing engine.

Note: To use this method, you must enable "Use Custom Pricing" in the embed settings. Currently, modular product configurators only accept total price, not component prices.

Example​

// Set a custom price with delivery time
window.mimeeqApp.utils.setPrice({
  price: 1299.99,             // Total price
  currency: 'USD',            // Currency code
  deliveryTime: '14-21 days', // Estimated delivery time
  levels: [                   // Quantity break pricing
    { quantityMin: 1, quantityMax: 9, price: 1299.99 },
    { quantityMin: 10, quantityMax: 49, price: 1199.99 },
    { quantityMin: 50, quantityMax: 999999, price: 1099.99 }
  ]
});

// Listen for price change events to know when to update prices
document.addEventListener('mimeeq-price-change', () => {
  fetchPriceFromExternalSystem().then(priceData => {
    window.mimeeqApp.utils.setPrice(priceData);
  });
});

Param​

Price data object containing price, currency, and optional delivery time

setPricingSettings​

setPricingSettings: SetPricingSettings

Configures the decimal place settings for price display.

This method allows you to control how prices are formatted in the Mimeeq configurator by specifying the minimum and maximum number of decimal places to show. This helps maintain consistent price formatting across your application.

Example​

// Show prices with exactly 2 decimal places
window.mimeeqApp.utils.setPricingSettings(2, 2);

// Show prices with at least 2 decimal places and at most 4
window.mimeeqApp.utils.setPricingSettings(2, 4);

Param​

Minimum number of decimal places to display (default: 2)

Param​

Maximum number of decimal places to display (default: 2)

showConfigurator​

showConfigurator: ShowConfigurator

Displays and renders a standard product configurator.

This method makes a previously hidden standard (non-modular) configurator visible and initializes its rendering. It's useful when you've set up a configurator with "Render at page load" disabled and want to show it on demand.

Example​

// Show the configurator when a button is clicked
document.getElementById('show-config-btn').addEventListener('click', () => {
  window.mimeeqApp.utils.showConfigurator();
});

Deprecated​

Method works only for legacy embed version. If you are using web component please use its show() method instead

showModular​

showModular: ShowModular

Displays and renders a modular product configurator.

This method makes a previously hidden modular configurator visible and initializes its rendering. It's useful when you've set up a modular configurator with "Render at page load" disabled and want to show it on demand.

Example​

// Show the modular configurator when a button is clicked
document.getElementById('show-modular-btn').addEventListener('click', () => {
  window.mimeeqApp.utils.showModular();
});

Deprecated​

Method works only for legacy embed version. If you are using web component please use its show() method instead

takeScreenshot​

takeScreenshot: TakeScreenshot

Captures a screenshot of the current product configuration.

This method generates a high-quality image of the current configuration state, which can be used for thumbnails, sharing, printing, or exporting. The method offers flexible options for image format, size, and appearance.

Under the hood, it clones the existing scene and calls captureImage() to ensure the screenshot doesn't disrupt the user's current view.

Example​

// Take a 1200px wide PNG screenshot with a white background
window.mimeeqApp.utils.takeScreenshot('png', 1200, '#ffffff')
  .then(imageBase64 => {
    // Use the base64-encoded image
    const img = document.createElement('img');
    img.src = imageBase64;
    document.body.appendChild(img);
  });

// Take a JPEG screenshot with custom dimensions and camera position
window.mimeeqApp.utils.takeScreenshot(
  'jpg',                      // JPEG format
  1800,                       // Width in pixels
  '#f0f0f0',                  // Light gray background
  { width: 1800, height: 1200 }, // Custom dimensions
  true,                       // Auto-zoom to fit product
  true,                       // Reset camera to initial position
  JSON.stringify({            // Custom camera position
    position: {x: -1.5, y: 1.7, z: -5.2},
    alpha: 4.4,
    beta: 1.3,
    target: {x: 0, y: 0.6, z: 0}
  })
);

Param​

File extension for the output image (default: 'png'). Supported values: 'png', 'jpg', 'jpeg'.

Param​

Image width in pixels (default: 3072). Height is calculated based on canvas aspect ratio. Note: On iOS devices, sizes larger than 2048 may cause performance issues.

Param​

Background color for JPEG images (default: '#fff'). Accepts hex color values. For PNG, this controls transparency.

Param​

Optional custom dimensions that override the default sizing.

Param​

When true, automatically zooms out to ensure the entire product is visible.

Param​

When true, resets the camera to its initial position before capturing.

Param​

JSON string with custom camera positioning data.

Returns​

A promise resolving to a base64-encoded image string, or null if unsuccessful.