> For the complete documentation index, see [llms.txt](https://docs.codegiganten.de/plugin-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/requirements.md).

# Requirements

Which Shopware version, which Shopware features and which outside access are needed for the plugin.

Before you set up the plugin, your shop and server should meet a few conditions. Setup fails most often because our search system cannot fetch the feed address. Check the points on this page in advance, it saves troubleshooting later. This page is also meant for your agency or host.

## Versions

There are two version lines with the same functionality:

| Plugin version | Shopware version            |
| -------------- | --------------------------- |
| 2.x            | Shopware 6.7                |
| 1.x            | Shopware 6.6 (from 6.6.9.0) |

The plugin requires a storefront. Without a storefront sales channel there is neither search nor feed. The plugin does not prescribe a PHP version itself, what your Shopware version requires applies.

{% hint style="info" %}
If you use Shopware 6.6.9 and see an error message about "defined test" (Twig) in the search overlay, update the plugin to the current version of the 1.x line. The error is fixed there.
{% endhint %}

{% hint style="warning" %}
If Shopware's Elasticsearch or OpenSearch is active for products, InsightSearch does not take over the search results page. The switch "Supply the Shopware search results page through InsightSearch" then has no effect. The search overlay is not affected.
{% endhint %}

## Required Shopware features

| Feature                                                    | What it is needed for                                                                           |
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Sales channel type "Product comparison" and product export | With Pull: the feed is generated from it. The wizard creates both itself.                       |
| Dynamic product group                                      | Defines which products are in the feed. The wizard creates it, or you choose an existing one.   |
| Shopware background processing (message queue with worker) | For Push, for manual re-reading in Push mode and for cart and order messages of the statistics. |
| Scheduled tasks                                            | For the daily Push sync, the connection check, catching up missed orders and the live sync.     |
| Shopware in-app purchases (optional)                       | For paid add-on features such as search term rules or "CMS on no results".                      |

### Background processing (worker)

Shopware's **background processing** works off jobs that are not finished immediately during a page request. Technically it is called message queue, and the continuously running process for it is called **worker**. It must run permanently, either as admin worker (runs only while an admin has the browser open, suitable for tests only) or as its own service via `messenger:consume`, ideally supervised by Supervisor or systemd.

Without a running worker, a Push indexing stands still and messages for the statistics pile up.

After a plugin update, restart the running workers (`bin/console messenger:stop-workers`) so that they load the new code.

### Scheduled tasks

Shopware's scheduled tasks must run, either via the cron job for `scheduled-task:run` or a corresponding service. Without them there is no automatic daily Push, no connection check, no catching up of orders and no live sync.

If you use the option "Generate in background" in the product export with Pull, Shopware also creates the feed file through a scheduled task. These tasks must run too.

## Outside access for the feed

With the default **Pull**, our search system fetches the feed address over the internet. It must therefore:

* be publicly reachable, without a login and without a block,
* run over HTTPS with a valid certificate,
* be reachable under a domain that can be resolved on the internet.

The address looks like this: your domain, then `/store-api/product-export/`, then an access key and the file name. You find it in the "Sources" area as feed address.

### What can block the fetch

The following protections prevent the fetch if they cover the feed address:

* **Password protection:** htaccess or Basic Auth, as is usual on stage systems.
* **IP blocks and firewalls** that let only certain addresses through.
* **Bot protection**, for example from Cloudflare, that blocks automated requests.
* **Maintenance mode** of the shop or the sales channel.
* **Invalid, expired or self-signed certificate.**
* **Local or internal domains** that are only known on your own network.

**What you should allow:** exclude the feed address from the protection or allow our fetch. Our fetch identifies itself with the user agent `CogiInsightSearch-Feed/1.0`. We cannot name fixed sender IP addresses here. Ask our support if needed.

A simple check: open the feed address in a private browser window. If it loads there without a login, our search system can fetch it too.

### Connections of your shop server

Your shop server makes outgoing HTTPS connections to our system (registration, connection check, Push, statistics). Firewalls and proxies of the server must allow these addresses:

* `https://api.insightsearch.de`
* `https://search.insightsearch.de`
* for the shopping assistant (beta) additionally `https://assistant.insightsearch.de`

### Connections from your visitors' browser

The search overlay in the visitor's browser calls our search system directly (`search.insightsearch.de`). A very strict content security policy, ad and script blockers or firewalls on the visitor's side can interfere. Add the address to your content security policy if you set one.

The plugin also uses its own routes in your shop, which your bot protection or web application firewall should not block:

* `/cogi/insightsearch/auth/session-token`
* `/cogi/insightsearch/user-event`
* `/cogi/insightsearch/search-suggestions`
* `/cogi/insightsearch/live-prices` (live prices, beta)

All write calls are secured by Shopware's CSRF protection.

{% hint style="info" %}
If your shop sits behind a CDN or load balancer, set the trusted proxies (`TRUSTED_PROXIES`) in Shopware correctly. Otherwise all visitors appear with the same IP address, and the collection of statistics may throttle visitors by mistake.
{% endhint %}

## Stage and DEV

Stage and development systems are often not reachable from outside or are protected by a password.

* **Not reachable or protected:** choose **Push** as indexing mode in the wizard. The plugin then sends the products itself, and Shopware's background processing must be running.
* **Pull on a protected stage** fails. The wizard then explains that the feed address must be public and reachable without a login.
* **Every environment needs its own connection.** A copy of the live shop must not write into the index and statistics of the original. How to do this cleanly is described on the page [Stage and live](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/stage-and-live.md).

## What should be ready before setup

* A **storefront sales channel** with payment method, shipping method, country and navigation category, and a domain that belongs to the channel. Otherwise creating the feed aborts.
* The **languages** in which to search are assigned to the sales channel. For each language you will later need its own data source.
* **Products** that are active and visible in the sales channel. A feed without products leads to an error ("The feed contains no products").
* An **e-mail address** for messages about critical problems.
* Optional: your Account Secret, if you want to connect another installation to an existing account.
* An admin user with the rights "Read system settings" and "Edit system settings" (see [Permissions](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/permissions.md)).

## Continue reading

{% content-ref url="/pages/1Lxj7Rpj8iUl7dhClF69" %}
[Installation and setup](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/installation-and-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/kRomH0o5aBX5iDGMqpD3" %}
[Stage and live](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/stage-and-live.md)
{% endcontent-ref %}

{% content-ref url="/pages/kG1p17yKCiPZb4o3gw2S" %}
[Push and live synchronisation](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/push-and-live-sync.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/requirements.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
