Installation Guide

This comprehensive guide walks you through the installation and initial setup of the FEL AI Product Advisor plugin for your Shopware 6 store.

Prerequisites

System Requirements

Before installing the FEL AI Product Advisor, ensure your system meets these requirements:

• Shopware Version: 6.6.3 or higher (6.7.x recommended)
• PHP: 8.2 or higher
• MySQL: 5.7 or higher
• Required Plugin: FEL OAI Assistants Manager (must be installed first)

OpenAI Account Setup

You'll need an active OpenAI account with:

• API Access: Active OpenAI API key
• API Key: Obtain from OpenAI Platform
• Supported Models: GPT-4o-mini, GPT-4o, GPT-5-mini, and all current reasoning models
• Configured Assistant: At least one OpenAI Assistant created

Model Selection

The plugin supports all current OpenAI models including GPT-4o-mini, GPT-5-mini, and reasoning models. Mini models offer excellent performance at very affordable costs. Premium models provide advanced capabilities but require monitoring token usage.

Dependency: FEL OAI Assistants Manager

The FEL AI Product Advisor requires the FEL OAI Assistants Manager base plugin to be installed and configured first. This base plugin handles all OpenAI API communication.

Verify Base Plugin Installation

1. Navigate to Settings → System → Plugins
2. Search for "FEL OAI Assistants Manager"
3. Ensure it's installed and activated
4. Click on the three dots (...) → Configuration
5. Verify that a valid OpenAI API key is entered
6. Test the connection using the "API Test" button

Installation Steps

Step 1: Install the Plugin

Via Command Line (Recommended)

# Navigate to your Shopware root directory
cd /path/to/your/shopware

# Extract plugin to plugins directory
cd custom/plugins/

# Refresh plugin list
bin/console plugin:refresh

# Install and activate the plugin
bin/console plugin:install FelAIProductAdvisor --activate

# Clear cache
bin/console cache:clear

Via Shopware Administration

1. Log in to your Shopware Administration
2. Navigate to Extensions → My Extensions
3. Click Upload extension
4. Upload the plugin ZIP file
5. Click Install after upload completes
6. Activate the plugin by clicking the toggle switch

Step 2: Compile Assets

After installation, you must compile the Shopware assets to include the plugin's frontend components.

# Compile Administration (if you'll configure the plugin)
bin/build-administration.sh

# Compile Storefront (required for chatbot display)
bin/build-storefront.sh

Important

Skipping asset compilation will result in the chatbot not displaying correctly or not appearing at all.

Verification

Verify Plugin Installation

1. Navigate to Settings → System → Plugins
2. Verify "FEL AI Product Advisor" is listed and activated
3. Check the plugin version (should be 2.0.0 or higher)

Verify CMS Element Availability

To confirm the installation was successful:

1. Navigate to Content → Shopping Experiences
2. Edit an existing page or create a new one
3. In the CMS layout editor, look for the "KI Produktberater" (AI Product Advisor) element
4. The element should be available in the "Commerce" category

Success!

If you can see the "KI Produktberater" element in the CMS editor, your installation was successful!

Post-Installation Configuration

After successful installation, no additional API configuration is needed at the plugin level. The FEL AI Product Advisor uses the API settings from the base plugin (FEL OAI Assistants Manager).

Optional: Plugin Settings

You can access optional plugin settings:

1. Navigate to Settings → System → Plugins
2. Find "FEL AI Product Advisor"
3. Click the three dots (...) → Configuration

Available global settings include:

Setting	Description	Default
Plugin aktivieren	Enable/disable the chatbot globally	✅ Enabled
Nur für authentifizierte Nutzer	Restrict chatbot to logged-in customers	❌ Disabled
Kundengruppen	Limit access to specific customer groups	All
Maximale Eingabelänge	Maximum characters per customer message	400
Suchergebnis-Limit	Maximum products in internal searches	8
Max. Beschreibungslänge	Product description character limit	500
Max. Produkte im Chat	Number of products displayed directly	4

Configuration Strategy

Most configuration happens at the CMS element level when you add the chatbot to a page. This allows you to create different chatbots for different pages with unique settings.

Troubleshooting Installation Issues

Plugin Not Appearing in Administration

Possible Solutions:

1. ✅ Clear cache: bin/console cache:clear
2. ✅ Refresh plugin list: bin/console plugin:refresh
3. ✅ Clear browser cache (Ctrl + F5)
4. ✅ Check Shopware logs: var/log/prod-*.log

CMS Element Not Available

Possible Solutions:

1. ✅ Verify plugin is activated (Settings → Plugins)
2. ✅ Rebuild storefront assets: bin/build-storefront.sh
3. ✅ Clear cache: bin/console cache:clear
4. ✅ Check browser console for JavaScript errors (F12)
5. ✅ Verify Shopware version compatibility (6.6.3+)

Checkboxes Not Visible in Configuration (Shopware 6.7)

Solution:

The plugin uses modern Shopware 6.7 type="bool" fields. If checkboxes don't appear:

# Rebuild administration
bin/build-administration.sh

# Clear cache
bin/console cache:clear

Asset Compilation Errors

If you encounter errors during asset compilation:

# Clear all caches first
rm -rf var/cache/*

# Try compiling again
bin/build-storefront.sh

Connection Issues with Base Plugin

Verify:

1. ✅ FEL OAI Assistants Manager is installed and activated
2. ✅ OpenAI API key is configured in base plugin
3. ✅ API connection test passes (click "API Test" button)
4. ✅ OpenAI account has sufficient credits
5. ✅ Server can reach https://api.openai.com

Important

The FEL AI Product Advisor cannot function without the FEL OAI Assistants Manager base plugin properly configured.

Next Steps

Now that you've successfully installed the FEL AI Product Advisor, proceed with:

1. Configuration - Set up your plugin settings and API configuration
2. Creating Your First Advisor - Add the chatbot to a CMS page
3. Design Customization - Choose from 6 professional themes
4. Best Practices - Learn how to optimize your chatbot for best results

Ready to Go!

You're now ready to create your first AI-powered product advisor. Head to the Creating a Product Advisor guide to get started!

Need Help?

If you continue to experience issues:

• Email:info@5-elements-design.de
• Include: Shopware version, PHP version, error messages, and steps to reproduce
• Logs: Check var/log/prod-*.log for detailed error information