> 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/cross-selling-pro-or-ki-+-warenkorb-cross-selling-+-bundles-and-sets/technik-und-betrieb.md).

# Technik und Betrieb

Systemvoraussetzungen, Hintergrundverarbeitung, geplante Aufgaben, Installation bis Deinstallation, Stage und Live, Befehl, Zwischenspeicher, Protokolle und Rechte von Cross Selling Pro.

Diese Seite richtet sich an Shop-Betreiber mit Serverzugang und an Agenturen. Sie beschreibt, was Cross Selling Pro von Ihrem Shopware-System braucht, was im Hintergrund läuft und worauf Sie bei Updates, Stage-Systemen und der Deinstallation achten sollten.

{% hint style="warning" %}
Der wichtigste Punkt vorab: Die Hintergrundverarbeitung von Shopware muss dauerhaft laufen und auch die Warteschlange `low_priority` abarbeiten. Sonst kommen Warenkorb, Bestellungen und Klicks nicht bei InsightSearch an.
{% endhint %}

## Systemvoraussetzungen

| Plugin-Version      | Shopware       | Hinweis                          |
| ------------------- | -------------- | -------------------------------- |
| 2.x (aktuell 2.2.1) | 6.7            | gleicher Funktionsumfang wie 1.x |
| 1.x (aktuell 1.4.1) | 6.6 ab 6.6.9.0 | gleicher Funktionsumfang wie 2.x |

* Die PHP-Version richtet sich nach Ihrer Shopware-Version. Das Plugin verlangt keine eigene.
* Die **Storefront** von Shopware ist Pflicht. Empfehlungen, Tracking und Cookie-Einträge hängen an ihr.
* Das Such-Plugin InsightSearch ist **nicht** nötig.

## Hintergrundverarbeitung (Message Queue)

Shopware erledigt viele Aufgaben nicht sofort, sondern legt sie als Nachricht in eine Warteschlange, die **Message Queue**. Ein **Worker** ist der Prozess, der diese Nachrichten nacheinander abarbeitet. Cross Selling Pro nutzt zwei Warteschlangen:

| Warteschlange  | Was darüber läuft                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------- |
| `async`        | Push-Pakete, Neu-Einlesen der Produktdaten, Nachtragen von Bestellungen, Neuberechnung des Zahlstatus      |
| `low_priority` | Warenkorb, Bestellungen, Anmeldungen und Ereignisse aus dem Browser für InsightSearch, dazu der Zahlstatus |

Der Worker muss beide abarbeiten:

```bash
bin/console messenger:consume async low_priority
```

* Wer nur `async` abarbeitet, bekommt keine Tracking-Ereignisse mehr bei InsightSearch an, und die Warteschlange im Shop wächst.
* Liegen Tracking-Ereignisse länger als 24 Stunden unverarbeitet, zeigt das Plugin-Dashboard einen Hinweis mit genau diesem Befehl. Der Hinweis funktioniert, wenn Shopware die Warteschlange in der Datenbank führt (Standard). Bei anderen Transporten wie Redis oder RabbitMQ erscheint er nicht.
* Der Admin-Worker von Shopware ist für Tests in Ordnung. Für Live-Shops empfehlen wir einen dauerhaft laufenden Dienst, etwa über Supervisor oder systemd.
* Kann das Plugin eine Tracking-Nachricht gar nicht einreihen, sendet es sie direkt mit kurzem Zeitlimit.

<details>

<summary>Speicherschutz für Worker beim Push</summary>

Ein Worker, der Push-Pakete verarbeitet, beendet sich nach der aktuellen Nachricht von selbst, wenn sein PHP-Speicher knapp wird. Ihr Dienst (Supervisor, systemd oder der Admin-Worker) muss ihn danach neu starten. Andere Arbeiten des Workers sind davon nicht betroffen. Mit `memory_limit -1` ist dieser Schutz aus.

</details>

## Geplante Aufgaben

Die geplanten Aufgaben von Shopware müssen laufen, als Dienst oder Cronjob mit `bin/console scheduled-task:run` oder über den Admin-Worker. Cross Selling Pro bringt fünf Aufgaben mit:

| Aufgabe            | Takt            | Was sie tut                                                                                                                                        |
| ------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| Verbindungsprüfung | stündlich       | Prüft den Stau in `low_priority`, meldet Plugin- und Shopware-Version, Paket und Zeitzone an InsightSearch, räumt verwaiste Push-Einstellungen auf |
| Paketabgleich      | stündlich       | Gleicht Ihr Paket mit den In-App-Käufen von Shopware ab                                                                                            |
| Täglicher Push     | täglich         | Startet für jede Push-Quelle einen vollständigen Push                                                                                              |
| Push-Wächter       | alle 10 Minuten | Reiht hängende Push-Pakete neu ein und schließt fertige Läufe ab                                                                                   |
| Bestellabgleich    | täglich         | Überträgt Bestellungen der letzten 90 Tage, die InsightSearch noch fehlen                                                                          |

Für den Feed-Weg muss außerdem die Shopware-eigene Aufgabe zur **Erzeugung von Produktexporten** laufen. Sonst wird die Feed-Datei nie aktualisiert.

{% hint style="info" %}
Ein bezahltes Paket fällt erst zurück, wenn der Paketabgleich dreimal hintereinander keinen Kauf findet. Paketwechsel übernehmen laufende Worker ohne Neustart.
{% endhint %}

Laufen die geplanten Aufgaben länger nicht, fehlt das regelmäßige Lebenszeichen Ihres Shops. Werden die Empfehlungsdaten deshalb entfernt, zeigt das Plugin den Hinweis „Deine Empfehlungsindizes wurden aufgrund von Inaktivität gelöscht. Bitte starte eine neue Indexierung, um die Empfehlungen wieder zu aktivieren.“ Starten Sie dann unter **Produkte & Daten → Quellen** „Produktdaten neu einlesen“.

## Netzwerk und Zugriff

* **Vom Shop-Server nach außen:** Der Shop spricht mit InsightSearch für Registrierung, Verbindungsprüfung, Push, Tracking, Bestellabgleich und Statistik. Die Verbindung muss ausgehend erlaubt sein.
* **Vom Browser des Besuchers:** Die Empfehlungen lädt der Browser direkt bei InsightSearch. Eine strenge Content-Security-Policy, Werbeblocker oder Firmen-Proxys können das verhindern. Dann bleiben die Empfehlungen leer. Prüfen Sie in den Entwicklertools des Browsers, ob Anfragen an InsightSearch blockiert werden.
* **Im Shop:** Die Empfehlungs-Elemente rufen im Hintergrund Adressen Ihres Shops auf, die mit `/cogi/` beginnen, dazu die Zwischenseite `/checkout/recommendations`. Eine Firewall oder ein Bot-Schutz darf diese Aufrufe nicht blockieren.
* **Feed (Pull):** InsightSearch ruft Ihre Feed-Adresse selbst ab. Sie muss öffentlich und ohne Anmeldung erreichbar sein. Der Abruf kommt mit der Browser-Kennung `CogiInsightSearch-Feed/1.0`. Feste Absender-Adressen für eine Freigabe erfragen Sie bitte beim Support.

## Produktdaten: Feed oder Push

**Feed (Pull) ist der Standard im Livebetrieb.** Der Einrichtungsassistent legt dafür einen Verkaufskanal vom Typ Produktvergleich, eine dynamische Produktgruppe und einen Produktexport mit Varianten an. Der Export wird per geplanter Aufgabe erzeugt.

* „Automatische Indexierung (Uhrzeit)“ unter **Quellen** legt fest, wann InsightSearch den Feed täglich abholt. Laut Hilfetext startet der Abruf innerhalb von 15 Minuten nach der eingestellten Uhrzeit.
* „Produktdaten neu einlesen“ verwirft zuerst den alten Export und wartet, bis Shopware ihn neu erzeugt hat. Das Plugin prüft das alle 30 Sekunden, höchstens 10 Minuten lang. Danach wird mit dem vorhandenen Stand eingelesen.
* Optional lassen sich Cross-Sellings aus Shopware in den Export aufnehmen (Karte „Produkt-Export“).

**Push ist für DEV- und Stage-Systeme gedacht**, die von außen nicht erreichbar sind. Das Plugin sendet die Produkte dann selbst in Paketen zu 50 Stück über die Hintergrundverarbeitung, einmal täglich und auf Knopfdruck. Ohne laufenden Worker bleibt der Push stehen.

## Lebenszyklus des Plugins

### Installieren und aktivieren

Beim Installieren meldet sich das Plugin bei InsightSearch an. Klappt das nicht, bleibt die Installation trotzdem erhalten. Im Einrichtungsassistenten erscheint dann der Knopf „Installation erneut versuchen“. Beim Aktivieren meldet das Plugin sich wieder als aktiv.

### Deaktivieren

Im Shop erscheinen keine Empfehlungen mehr. Tracking und die geplanten Aufgaben des Plugins laufen nicht.

### Deinstallieren

Shopware fragt, ob Sie die Daten behalten möchten.

| Auswahl               | Was im Shop passiert                                                                                                                                                                                                       |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| „Daten behalten“      | Nichts wird gelöscht. Vorlagen, Einstellungen und Zugangsdaten bleiben. Eine spätere Neuinstallation verbindet sich ohne neue Registrierung                                                                                |
| ohne „Daten behalten“ | Gelöscht werden alle Empfehlungs-, Bundle/Set- und Conversion-Booster-Elemente in **allen** Erlebniswelten, alle Empfehlungs- und Bundle/Set-Vorlagen, die Tagessummen für den cogi Commander und die Plugin-Konfiguration |

{% hint style="danger" %}
Ohne „Daten behalten“ verlieren Ihre Erlebniswelten ihre Empfehlungsblöcke dauerhaft. Nach einer Neuinstallation müssen Sie Vorlagen und Blöcke neu anlegen.
{% endhint %}

Stehen bleiben der vom Assistenten angelegte Produktvergleichs-Verkaufskanal, die dynamische Produktgruppe und der Produktexport. Löschen Sie diese bei Bedarf von Hand. Die Auswahl „Daten behalten“ wirkt auf die Daten in Ihrem Shop.

### Update

Nach einem Update empfehlen sich die üblichen Shopware-Schritte:

```bash
bin/console plugin:update CogiInsightSearchRecommendations
bin/console theme:compile
bin/console cache:clear
bin/console messenger:stop-workers
```

Der letzte Befehl beendet laufende Worker, damit Ihr Dienst sie mit dem neuen Code neu startet.

<details>

<summary>Besonderheiten beim Update auf 2.2.1 bzw. 1.4.1</summary>

* Das erste Speichern der Plugin-Konfiguration nach dem Update startet einmalig eine Neuberechnung des Zahlstatus.
* Sitzungen werden ab dem Update unter einer neuen Kennung gezählt. In der Statistik gibt es an diesem Tag einen Bruch.
* Lieferbarkeit und Hauptkategorie wirken ab der nächsten Übertragung der Produktdaten.

</details>

## Stage und Live

* Kopieren Sie die Live-Datenbank auf eine Stage, stehen dort auch die Live-Zugangsdaten in der Plugin-Konfiguration. Damit Bestellungen und Klicks der Stage nicht in Ihr Live-Konto laufen, nutzen Sie auf der Stage im Einrichtungsassistenten „Verbindung zurücksetzen“ und richten die Stage neu ein, oder Sie schalten dort das Bestell-Tracking ab.
* Lehnt InsightSearch eine Neuregistrierung ab, weil der Shop schon verbunden ist, zeigt der Admin das an. Sie geben die Neuregistrierung im InsightSearch-Dashboard unter Installationen mit „Neuregistrierung freigeben“ frei.
* Ist die Stage durch Passwort oder IP-Sperre geschützt, kann InsightSearch den Feed nicht abholen. Geben Sie den Feed frei oder wählen Sie Push.

## Befehl für den cogi Commander

Cross Selling Pro bringt genau einen eigenen Befehl mit. Er trägt Bestellungen und Umsatz durch Empfehlungen aus der Vergangenheit einmalig als Tagessummen für den cogi Commander nach.

```bash
bin/console cogi-insightsearch-recommendations:suite-backfill [--from=JJJJ-MM-TT] [--force]
```

| Option              | Wirkung                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `--from=JJJJ-MM-TT` | Erster Tag des Nachtrags. Ohne Angabe werden alle Bestellungen gelesen                                   |
| `--force`           | Lässt den Nachtrag ein zweites Mal laufen. Nur richtig, solange der Commander noch nichts übernommen hat |

1. cogi Commander installieren und aktivieren. Ohne aktiven Commander bricht der Befehl ab.
2. Befehl ausführen.
3. Der Commander übernimmt die Summen bei seinem nächsten stündlichen Lauf.

Nachgetragen werden nur Bestellungen und Umsatz, bis zu dem Tag, ab dem live gezählt wird. Einblendungen, Klicks und Warenkorb-Aktionen von früher lassen sich nicht nachtragen. Der Befehl sendet nichts an InsightSearch.

## Zwischenspeicher

* Speichern oder löschen Sie eine **Empfehlungs-Vorlage**, verwirft das Plugin die zwischengespeicherten Seiten mit dieser Vorlage sofort.
* Persönliche Teile werden nie zwischengespeichert: Kundenbezug, Produktdaten der Elemente, Live-Preise, Sichtbarkeitsprüfung und die Checkout-Zwischenseite.
* Die Empfehlungen selbst lädt der Browser zur Laufzeit. Neue Produktdaten wirken deshalb nach der nächsten Übertragung, ohne dass Sie den Zwischenspeicher leeren.
* Ist eine Änderung an Ausspielorten oder Bundle/Set-Vorlagen nicht zu sehen, leeren Sie den Shop-Zwischenspeicher.
* Ein vorgeschalteter Proxy wie Varnish darf die Hintergrund-Aufrufe unter `/cogi/` nicht zwischenspeichern.

## Protokolle

Das Plugin schreibt in eine eigene, täglich neue Datei:

```
var/log/CogiInsightSearchRecommendations-<Datum>.log
```

Einige Meldungen landen zusätzlich im allgemeinen Shopware-Protokoll. Im Admin helfen außerdem die Vorschau in der Vorlage, die Empfehlungs-Sandbox, „Export testen“ im Datenfeld-Editor und die Seite **Überblick → Nutzer-Tracking**.

## Rechte im Admin

Das Plugin bringt keine eigenen Rollen mit, sondern nutzt vorhandene Shopware-Rechte.

| Bereich                                                                                                                       | Benötigtes Recht                       |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Statistik, CMS-Blöcke, Nutzer-Tracking, Statistik am Produkt, Kachel im Admin-Dashboard                                       | Bestellungen ansehen                   |
| Ausspielorte                                                                                                                  | Plugins verwalten                      |
| Alle ändernden Aktionen (Feed anlegen, neu einlesen, Sprachzuordnung, Datenfelder, Push, Bestellungen nachtragen, Zahlstatus) | Systemkonfiguration bearbeiten         |
| Schnellzuweisung Cross-Selling: ansehen / speichern                                                                           | Produkte ansehen / Produkte bearbeiten |

Die Seitenleiste zeigt alle Bereiche, auch ohne Recht. Beim Öffnen sperrt Shopware dann den Zugriff.

## Themes

Das Plugin bringt eigene Darstellungen für Slider, Offcanvas, Bundle/Set und Conversion Booster mit. Für Zenit-Themes enthält es eigene Anpassungen, etwa für den Kauf-Button auf Produktkarten. Kompilieren Sie nach Installation oder Update das Theme neu (`bin/console theme:compile`), damit die Styles des Plugins greifen.

## Weiterlesen

{% content-ref url="/pages/Fzp9B2xGCXQcdIY2HPhj" %}
[Cross-Selling Tracking und Datenverarbeitung](https://docs.codegiganten.de/plugin-documentation/apps/cross-selling-pro-or-ki-+-warenkorb-cross-selling-+-bundles-and-sets/cross-selling-tracking-und-datenverarbeitung.md)
{% endcontent-ref %}

{% content-ref url="/pages/GGXPYNq3gHeZ8533R9E7" %}
[Fehlersuche und häufige Fragen](https://docs.codegiganten.de/plugin-documentation/apps/cross-selling-pro-or-ki-+-warenkorb-cross-selling-+-bundles-and-sets/fehlersuche-und-faq.md)
{% endcontent-ref %}

{% content-ref url="/pages/6k1qZUWCUdvgoVMAXycx" %}
[Wann wirkt eine Änderung?](https://docs.codegiganten.de/plugin-documentation/apps/cross-selling-pro-or-ki-+-warenkorb-cross-selling-+-bundles-and-sets/wann-wirkt-eine-aenderung.md)
{% endcontent-ref %}

{% content-ref url="/pages/7ba808a78bb216ea4f30f967af24cfb8a69b3176" %}
[Installation](https://docs.codegiganten.de/plugin-documentation/apps/cross-selling-pro-or-ki-+-warenkorb-cross-selling-+-bundles-and-sets/installation.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/cross-selling-pro-or-ki-+-warenkorb-cross-selling-+-bundles-and-sets/technik-und-betrieb.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.
