Install Visual Add to Cart

Visual Add to Cart lets storefront users upload a product image on the Quick Order page to automatically recognize products and populate the order form. This document describes how to install the Visual Add to Cart feature.

Install the feature core

Follow the steps in the following sections to install the Visual Add to Cart feature core.

Prerequisites

Install the required features:

1) Add translations

Append the glossary according to your configuration: data/import/common/common/glossary.csv

>ai-commerce.quick-order-image-to-cart.image-order.errors.ai-request-failed,AI request failed. Please try again.,en_US
ai-commerce.quick-order-image-to-cart.image-order.errors.ai-request-failed,KI-Anfrage fehlgeschlagen. Bitte versuchen Sie es erneut.,de_DE
ai-commerce.quick-order-image-to-cart.image-order.errors.ai-response-invalid,The AI returned an invalid response. Please try again.,en_US
ai-commerce.quick-order-image-to-cart.image-order.errors.ai-response-invalid,Die KI hat eine ungültige Antwort zurückgegeben. Bitte versuchen Sie es erneut.,de_DE
ai-commerce.quick-order-image-to-cart.image-order.errors.no-products-recognized,No products could be recognized in the image.,en_US
ai-commerce.quick-order-image-to-cart.image-order.errors.no-products-recognized,Es konnten keine Produkte im Bild erkannt werden.,de_DE
ai-commerce.quick-order-image-to-cart.image-order.errors.product-limit-exceeded,The image contains too many products. Please upload an image with fewer products.,en_US
ai-commerce.quick-order-image-to-cart.image-order.errors.product-limit-exceeded,Das Bild enthält zu viele Produkte. Bitte laden Sie ein Bild mit weniger Produkten hoch.,de_DE
ai-commerce.quick-order-image-to-cart.image-order.errors.invalid-format,The uploaded file format is not supported.,en_US
ai-commerce.quick-order-image-to-cart.image-order.errors.invalid-format,Das hochgeladene Dateiformat wird nicht unterstützt.,de_DE
ai-commerce.quick-order-image-to-cart.image-order.errors.invalid-mime-type,The uploaded file type is not allowed.,en_US
ai-commerce.quick-order-image-to-cart.image-order.errors.invalid-mime-type,Der hochgeladene Dateityp ist nicht zulässig.,de_DE
ai-commerce.quick-order-image-to-cart.image-order.errors.file-too-large,The uploaded file exceeds the maximum allowed size.,en_US
ai-commerce.quick-order-image-to-cart.image-order.errors.file-too-large,Die hochgeladene Datei überschreitet die maximal zulässige Größe.,de_DE
ai-commerce.quick-order-image-to-cart.image-order.errors.product-not-found,Product "%name%" could not be found in the catalog.,en_US
ai-commerce.quick-order-image-to-cart.image-order.errors.product-not-found,Produkt "%name%" konnte im Katalog nicht gefunden werden.,de_DE

2) Set up behavior

Register the following plugin to integrate the feature into the Quick Order page:

src/Pyz/Yves/QuickOrderPage/QuickOrderPageDependencyProvider.php

<?php

namespace Pyz\Yves\QuickOrderPage;

use SprykerFeature\Yves\AiCommerce\Plugin\QuickOrderPage\AiCommerceQuickOrderImageToCartFormPlugin;
use SprykerShop\Yves\QuickOrderPage\QuickOrderPageDependencyProvider as SprykerQuickOrderPageDependencyProvider;

class QuickOrderPageDependencyProvider extends SprykerQuickOrderPageDependencyProvider
{
    /**
     * @return array<\SprykerShop\Yves\QuickOrderPageExtension\Dependency\Plugin\QuickOrderFormPluginInterface>
     */
    protected function getQuickOrderFormPlugins(): array
    {
        return [
            new AiCommerceQuickOrderImageToCartFormPlugin(),
        ];
    }
}

3) Configure AiFoundation for Visual Add to Cart

For a base AiFoundation setup, see Configure AiFoundation.

Using a dedicated AI configuration for Visual Add to Cart is recommended because each named configuration is tracked separately in the AiFoundation audit log. This lets you isolate and review all AI calls made by the image recognition flow independently from other AI features in your project.

To use a dedicated AI model configuration for Visual Add to Cart instead of the default one, follow these steps:

1. In config/Shared/config_ai.php, add a named configuration entry using AiCommerceConstants::VISUAL_ADD_TO_CART_CONFIGURATION_NAME as the key:

$config[\Spryker\Shared\AiFoundation\AiFoundationConstants::AI_CONFIGURATIONS][\SprykerFeature\Shared\AiCommerce\AiCommerceConstants::VISUAL_ADD_TO_CART_CONFIGURATION_NAME] = $openAiConfiguration;

2. Return the configuration name from AiCommerceConfig:

src/Pyz/Yves/AiCommerce/AiCommerceConfig.php

<?php

namespace Pyz\Yves\AiCommerce;

use SprykerFeature\Shared\AiCommerce\AiCommerceConstants;
use SprykerFeature\Yves\AiCommerce\AiCommerceConfig as SprykerAiCommerceConfig;

class AiCommerceConfig extends SprykerAiCommerceConfig
{
    public function getQuickOrderImageToCartAiConfigurationName(): ?string
    {
        return AiCommerceConstants::VISUAL_ADD_TO_CART_CONFIGURATION_NAME;
    }
}

4) Enable the feature

Enable the feature in the Back Office:

1. In the Back Office, go to AI Commerce > Quick Order > Visual Add to Cart.
2. Enable it.
3. Click Save.

Integrate the feature frontend

1) Update the Quick Order form template

In src/Pyz/Yves/QuickOrderPage/Theme/default/components/molecules/quick-order-form/quick-order-form.twig, make sure the plugin forms loop is placed after the quick-order-file-upload molecule include inside {% block fields %}:

{% include molecule('quick-order-file-upload', 'QuickOrderPage') with {
    data: {
        uploadOrderForm: data.uploadOrderForm,
        fileTemplateExtensions: data.fileTemplateExtensions,
    },
} only %}

{% for pluginForm in embed.pluginForms %}
    <hr>

    {% if pluginForm.vars.template_path is defined %}
        {% include pluginForm.vars.template_path with {
            data: {
                form: pluginForm,
            },
        } only %}
    {% else %}
        {{ form_widget(pluginForm) }}
    {% endif %}
{% endfor %}

2) Apply the frontend changes

Apply the frontend changes:

docker/sdk cli npm install
docker/sdk cli console frontend:project:install-dependencies
docker/sdk cli console frontend:yves:build