> 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/apps/suche-intelligent-und-ki-optimiert/voraussetzungen.md).

# Voraussetzungen

Welche Shopware-Version, welche Shopware-Funktionen und welcher Zugriff von außen für das Plugin nötig sind.

Bevor Sie das Plugin einrichten, sollten Shop und Server einige Bedingungen erfüllen. Am häufigsten scheitert die Einrichtung daran, dass unser Suchsystem die Feed-Adresse nicht abrufen kann. Prüfen Sie die Punkte dieser Seite vorab, das spart Ihnen später Fehlersuche. Die Seite richtet sich auch an Ihre Agentur oder Ihren Hoster.

## Versionen

Es gibt zwei Versionslinien mit demselben Funktionsstand:

| Plugin-Version | Shopware-Version          |
| -------------- | ------------------------- |
| 2.x            | Shopware 6.7              |
| 1.x            | Shopware 6.6 (ab 6.6.9.0) |

Das Plugin setzt eine Storefront voraus. Ohne Storefront-Verkaufskanal gibt es weder Suche noch Feed. Eine PHP-Version schreibt das Plugin nicht selbst vor, es gilt, was Ihre Shopware-Version verlangt.

{% hint style="info" %}
Nutzen Sie Shopware 6.6.9 und sehen im Such-Overlay eine Fehlermeldung zu „defined test“ (Twig), aktualisieren Sie das Plugin auf die aktuelle Version der 1.x-Linie. Der Fehler ist dort behoben.
{% endhint %}

{% hint style="warning" %}
Ist Shopwares Elasticsearch oder OpenSearch für Produkte aktiv, übernimmt InsightSearch die Suchergebnisseite nicht. Der Schalter „Shopware-Suchergebnisseite durch InsightSearch beliefern“ wirkt dann nicht. Das Such-Overlay ist davon nicht betroffen.
{% endhint %}

## Benötigte Shopware-Funktionen

| Funktion                                                        | Wofür sie gebraucht wird                                                                                              |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Verkaufskanal-Typ „Produktvergleich“ und Produktexport          | Bei Pull: Der Feed wird daraus erzeugt. Der Wizard legt beides selbst an.                                             |
| Dynamische Produktgruppe                                        | Legt fest, welche Produkte im Feed stehen. Der Wizard legt sie an, oder Sie wählen eine vorhandene.                   |
| Hintergrundverarbeitung von Shopware (Message Queue mit Worker) | Bei Push, beim manuellen Neu-Einlesen im Push-Modus sowie für Warenkorb- und Bestellmeldungen der Statistik.          |
| Geplante Aufgaben (Scheduled Tasks)                             | Für den täglichen Push-Abgleich, die Verbindungsprüfung, das Nachholen verpasster Bestellungen und den Live-Abgleich. |
| Shopware In-App-Käufe (optional)                                | Für kostenpflichtige Zusatzfunktionen wie Suchbegriff-Regeln oder „CMS bei keinen Treffern“.                          |

### Hintergrundverarbeitung (Worker)

Die **Hintergrundverarbeitung** von Shopware arbeitet Aufträge ab, die nicht sofort im Seitenaufruf erledigt werden. Technisch heißt das Message Queue, der dauernd laufende Prozess dazu heißt **Worker**. Er muss dauerhaft laufen, entweder als Admin-Worker (läuft nur, solange ein Admin im Browser geöffnet ist, nur für Tests geeignet) oder als eigener Dienst über `messenger:consume`, am besten überwacht von Supervisor oder systemd.

Ohne laufenden Worker bleibt eine Push-Indexierung stehen, und Meldungen für die Statistik stauen sich.

Nach einem Plugin-Update starten Sie die laufenden Worker neu (`bin/console messenger:stop-workers`), damit sie den neuen Code laden.

### Geplante Aufgaben

Die geplanten Aufgaben von Shopware müssen laufen, entweder über den Cronjob für `scheduled-task:run` oder einen entsprechenden Dienst. Ohne sie gibt es keinen automatischen täglichen Push, keine Verbindungsprüfung, kein Nachholen von Bestellungen und keinen Live-Abgleich.

Nutzen Sie bei Pull die Option „Im Hintergrund generieren“ im Produktexport, erzeugt Shopware die Feed-Datei ebenfalls per geplanter Aufgabe. Diese Aufgaben müssen dann auch laufen.

## Zugriff von außen für den Feed

Beim Standardweg **Pull** ruft unser Suchsystem die Feed-Adresse über das Internet ab. Sie muss deshalb:

* öffentlich erreichbar sein, ohne Anmeldung und ohne Sperre,
* über HTTPS mit gültigem Zertifikat laufen,
* unter einer Domain erreichbar sein, die im Internet aufgelöst werden kann.

Die Adresse sieht so aus: Ihre Domain, dann `/store-api/product-export/`, dann ein Zugangsschlüssel und der Dateiname. Sie finden sie im Bereich „Quellen“ als Feed-Adresse.

### Was den Abruf blockieren kann

Folgende Schutzmaßnahmen verhindern den Abruf, wenn sie die Feed-Adresse erfassen:

* **Passwortschutz:** htaccess oder Basic Auth, wie er bei Stage-Systemen üblich ist.
* **IP-Sperren und Firewalls**, die nur bestimmte Adressen durchlassen.
* **Bot-Schutz**, zum Beispiel von Cloudflare, der automatische Abrufe blockiert.
* **Wartungsmodus** des Shops oder des Verkaufskanals.
* **Ungültiges, abgelaufenes oder selbst signiertes Zertifikat.**
* **Lokale oder interne Domains**, die nur im eigenen Netz bekannt sind.

**Was Sie freigeben sollten:** Nehmen Sie die Feed-Adresse vom Schutz aus oder erlauben Sie unseren Abruf. Unser Abruf meldet sich mit dem User-Agent `CogiInsightSearch-Feed/1.0`. Feste Absender-IP-Adressen können wir hier nicht angeben. Fragen Sie bei Bedarf unseren Support.

Eine Prüfung ist einfach: Öffnen Sie die Feed-Adresse in einem privaten Browserfenster. Lädt sie dort ohne Anmeldung, kann auch unser Suchsystem sie abrufen.

### Verbindungen Ihres Shop-Servers

Ihr Shop-Server baut ausgehend HTTPS-Verbindungen zu unserem System auf (Registrierung, Verbindungsprüfung, Push, Statistik). Firewalls und Proxys des Servers müssen diese Adressen erlauben:

* `https://api.insightsearch.de`
* `https://search.insightsearch.de`
* für den Shopping-Assistenten (Beta) zusätzlich `https://assistant.insightsearch.de`

### Verbindungen aus dem Browser Ihrer Besucher

Das Such-Overlay im Browser des Besuchers ruft unser Suchsystem direkt auf (`search.insightsearch.de`). Eine sehr strenge Content-Security-Policy, Werbe- und Skript-Blocker oder Firewalls auf Besucherseite können das stören. Tragen Sie die Adresse in Ihrer Content-Security-Policy ein, falls Sie eine setzen.

Zusätzlich nutzt das Plugin eigene Routen in Ihrem Shop, die Ihr Bot-Schutz oder eine Web-Application-Firewall nicht blockieren sollte:

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

Alle schreibenden Aufrufe sind durch den Shopware-CSRF-Schutz gesichert.

{% hint style="info" %}
Steht Ihr Shop hinter einem CDN oder Lastverteiler, setzen Sie die vertrauenswürdigen Proxys (`TRUSTED_PROXIES`) in Shopware korrekt. Sonst sehen alle Besucher dieselbe IP-Adresse, und die Erfassung der Statistik kann Besucher irrtümlich drosseln.
{% endhint %}

## Stage und DEV

Stage- und Entwicklungssysteme sind oft von außen nicht erreichbar oder durch ein Passwort geschützt.

* **Nicht erreichbar oder geschützt:** Wählen Sie im Wizard als Indexierungsart **Push**. Das Plugin sendet die Produkte dann selbst, die Hintergrundverarbeitung von Shopware muss laufen.
* **Pull auf einer geschützten Stage** schlägt fehl. Der Wizard erklärt dann, dass die Feed-Adresse öffentlich und ohne Anmeldung erreichbar sein muss.
* **Jede Umgebung braucht ihre eigene Verbindung.** Eine Kopie des Live-Shops darf nicht in den Index und die Statistik des Originals schreiben. Wie das sauber geht, steht auf der Seite [Stage und Live](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/stage-und-live.md).

## Was vor der Einrichtung bereitliegen sollte

* Ein **Storefront-Verkaufskanal** mit Zahlungsart, Versandart, Land und Navigationskategorie sowie einer Domain, die zum Kanal gehört. Sonst bricht das Anlegen des Feeds ab.
* Die **Sprachen**, in denen gesucht werden soll, sind dem Verkaufskanal zugeordnet. Je Sprache brauchen Sie später eine eigene Datenquelle.
* **Produkte**, die aktiv und im Verkaufskanal sichtbar sind. Ein Feed ohne Produkte führt zu einem Fehler („Der Feed enthält keine Produkte“).
* Eine **E-Mail-Adresse** für Mitteilungen bei kritischen Problemen.
* Optional: Ihr Account Secret, wenn Sie eine weitere Installation mit einem bestehenden Account verbinden wollen.
* Ein Admin-Benutzer mit den Rechten „Systemeinstellungen lesen“ und „Systemeinstellungen bearbeiten“ (siehe [Berechtigungen](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/berechtigungen.md)).

## Weiterlesen

{% content-ref url="/pages/G8WHK3FCmQgWEZXwYEFm" %}
[Installation und Einrichtung](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/installation-und-einrichtung.md)
{% endcontent-ref %}

{% content-ref url="/pages/SjGrQJy19tWx34BxWnlQ" %}
[Stage und Live](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/stage-und-live.md)
{% endcontent-ref %}

{% content-ref url="/pages/TB60BMQ05uLv6epja2ky" %}
[Push und Live-Abgleich](https://docs.codegiganten.de/plugin-documentation/apps/suche-intelligent-und-ki-optimiert/push-und-live-abgleich.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/apps/suche-intelligent-und-ki-optimiert/voraussetzungen.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.
