> 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/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/technical-operation.md).

# Technical operation

System requirements, background processing, scheduled tasks, installation to uninstallation, stage and live, command, cache, logs and permissions of Cross Selling Pro.

This page is aimed at shop owners with server access and at agencies. It describes what Cross Selling Pro needs from your Shopware system, what runs in the background and what to watch out for with updates, stage systems and uninstallation.

{% hint style="warning" %}
The most important point first: the Shopware background processing must run permanently and also process the queue `low_priority`. Otherwise cart, orders and clicks do not reach InsightSearch.
{% endhint %}

## System requirements

| Plugin version        | Shopware         | Note                 |
| --------------------- | ---------------- | -------------------- |
| 2.x (currently 2.2.1) | 6.7              | same features as 1.x |
| 1.x (currently 1.4.1) | 6.6 from 6.6.9.0 | same features as 2.x |

* The PHP version follows your Shopware version. The plugin does not require its own.
* The Shopware **Storefront** is required. Recommendations, tracking and cookie entries depend on it.
* The InsightSearch search plugin is **not** required.

## Background processing (message queue)

Shopware does not handle many tasks immediately but places them as messages in a queue, the **message queue**. A **worker** is the process that works through these messages one by one. Cross Selling Pro uses two queues:

| Queue          | What runs through it                                                                    |
| -------------- | --------------------------------------------------------------------------------------- |
| `async`        | Push batches, reindexing product data, adding past orders, recalculating payment status |
| `low_priority` | Cart, orders, logins and browser events for InsightSearch, plus payment status          |

The worker must process both:

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

* If only `async` is processed, tracking events no longer reach InsightSearch and the queue in the shop keeps growing.
* If tracking events remain unprocessed for more than 24 hours, the plugin dashboard shows a notice with exactly this command. The notice works if Shopware keeps the queue in the database (default). With other transports such as Redis or RabbitMQ it does not appear.
* The Shopware admin worker is fine for testing. For live shops, we recommend a permanently running service, for example via Supervisor or systemd.
* If the plugin cannot queue a tracking message at all, it sends it directly with a short time limit.

<details>

<summary>Memory protection for workers during push</summary>

A worker that processes push batches ends itself after the current message when its PHP memory runs low. Your service (Supervisor, systemd or the admin worker) must then restart it. Other work of the worker is not affected. With `memory_limit -1`, this protection is off.

</details>

## Scheduled tasks

The Shopware scheduled tasks must run, as a service or cron job with `bin/console scheduled-task:run` or via the admin worker. Cross Selling Pro ships five tasks:

| Task             | Interval         | What it does                                                                                                                                     |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Connection check | hourly           | Checks the backlog in `low_priority`, reports plugin and Shopware version, plan and time zone to InsightSearch, cleans up orphaned push settings |
| Plan check       | hourly           | Compares your plan with the Shopware in-app purchases                                                                                            |
| Daily push       | daily            | Starts a full push for each push source                                                                                                          |
| Push watchdog    | every 10 minutes | Requeues stuck push batches and completes finished runs                                                                                          |
| Order sync       | daily            | Transfers orders from the last 90 days that InsightSearch is still missing                                                                       |

For the feed route, the Shopware task for **generating product exports** must also run. Otherwise the feed file is never updated.

{% hint style="info" %}
A paid plan only falls back if the plan check finds no purchase three times in a row. Running workers pick up plan changes without a restart.
{% endhint %}

If the scheduled tasks do not run for a longer period, the regular sign of life from your shop is missing. If the recommendation data is removed for this reason, the plugin shows the notice "Your recommendation indices were deleted due to inactivity. Please start a new indexing run to reactivate recommendations." Then start "Reindex" under **Products & data → Sources**.

## Network and access

* **From the shop server outwards:** The shop talks to InsightSearch for registration, connection check, push, tracking, order sync and statistics. Outgoing connections must be allowed.
* **From the visitor's browser:** The browser loads the recommendations directly from InsightSearch. A strict Content Security Policy, ad blockers or company proxies can prevent this. The recommendations then stay empty. Check in the browser developer tools whether requests to InsightSearch are blocked.
* **Within the shop:** The recommendation elements call addresses of your shop in the background that start with `/cogi/`, plus the interstitial page `/checkout/recommendations`. A firewall or bot protection must not block these calls.
* **Feed (pull):** InsightSearch fetches your feed address itself. It must be publicly reachable without login. The request comes with the browser identification `CogiInsightSearch-Feed/1.0`. Please ask support for fixed sender addresses for an allowlist.

## Product data: feed or push

**Feed (pull) is the standard for live shops.** The setup wizard creates a sales channel of the type product comparison, a dynamic product group and a product export including variants. The export is generated by a scheduled task.

* "Automatic indexing (time)" under **Sources** sets when InsightSearch fetches the feed each day. According to the help text, the fetch starts within 15 minutes of the configured time.
* "Reindex" first discards the old export and waits until Shopware has generated it again. The plugin checks this every 30 seconds for 10 minutes at most. After that, the existing state is read.
* Optionally, cross-sellings from Shopware can be included in the export (card "Product export").

**Push is meant for DEV and stage systems** that cannot be reached from outside. The plugin then sends the products itself in batches of 50 via background processing, once a day and at the push of a button. Without a running worker, the push stops.

## Plugin lifecycle

### Install and activate

During installation, the plugin registers with InsightSearch. If this fails, the installation is kept anyway. The setup wizard then shows the button "Retry installation". On activation, the plugin reports itself as active again.

### Deactivate

No more recommendations appear in the shop. Tracking and the plugin's scheduled tasks do not run.

### Uninstall

Shopware asks whether you want to keep the data.

| Choice           | What happens in the shop                                                                                                                                                                                                                 |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Keep data        | Nothing is deleted. Templates, settings and credentials remain. A later reinstallation connects without a new registration                                                                                                               |
| Do not keep data | All recommendation, bundle/set and Conversion Booster elements in **all** shopping experiences are deleted, as well as all recommendation and bundle/set templates, the daily totals for the cogi Commander and the plugin configuration |

{% hint style="danger" %}
Without keeping data, your shopping experiences permanently lose their recommendation blocks. After a reinstallation, you have to create templates and blocks again.
{% endhint %}

The product comparison sales channel, the dynamic product group and the product export created by the wizard remain. Delete them manually if needed. The choice to keep data applies to the data in your shop.

### Update

After an update, the usual Shopware steps are recommended:

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

The last command stops running workers so that your service restarts them with the new code.

<details>

<summary>Special points when updating to 2.2.1 or 1.4.1</summary>

* The first save of the plugin configuration after the update starts a one-time recalculation of the payment status.
* From the update on, sessions are counted under a new identifier. The statistics show a break on that day.
* Availability and main category take effect from the next transfer of product data.

</details>

## Stage and live

* If you copy the live database to a stage, the live credentials are in the plugin configuration there as well. So that orders and clicks from the stage do not end up in your live account, use "Reset connection" in the setup wizard on the stage and set up the stage again, or switch off order tracking there.
* If InsightSearch rejects a new registration because the shop is already connected, the admin shows this. You release the new registration in the InsightSearch dashboard under installations.
* If the stage is protected by a password or IP restriction, InsightSearch cannot fetch the feed. Make the feed accessible or choose push.

## Command for the cogi Commander

Cross Selling Pro ships exactly one command of its own. It adds past orders and revenue from recommendations once as daily totals for the cogi Commander.

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

| Option              | Effect                                                                                                 |
| ------------------- | ------------------------------------------------------------------------------------------------------ |
| `--from=YYYY-MM-DD` | First day to add. Without it, all orders are read                                                      |
| `--force`           | Runs the backfill a second time. Only correct as long as the Commander has not taken over anything yet |

1. Install and activate the cogi Commander. Without an active Commander, the command aborts.
2. Run the command.
3. The Commander takes over the totals on its next hourly run.

Only orders and revenue are added, up to the day from which live counting started. Past impressions, clicks and cart actions cannot be added. The command sends nothing to InsightSearch.

## Cache

* If you save or delete a **recommendation template**, the plugin immediately discards the cached pages that use this template.
* Personal parts are never cached: customer reference, product data of the elements, live prices, visibility check and the checkout interstitial page.
* The browser loads the recommendations themselves at runtime. New product data therefore takes effect after the next transfer without clearing the cache.
* If a change to placements or bundle/set templates is not visible, clear the shop cache.
* An upstream proxy such as Varnish must not cache the background calls under `/cogi/`.

## Logs

The plugin writes to its own file, a new one each day:

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

Some messages also end up in the general Shopware log. In the admin, the preview in the template, the recommendation sandbox, the export test in the data field editor and the page **Overview → User tracking** also help.

## Permissions in the admin

The plugin does not ship its own roles but uses existing Shopware permissions.

| Area                                                                                                                 | Required permission           |
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
| Statistics, CMS blocks, user tracking, statistics on the product, tile on the admin dashboard                        | view orders                   |
| Placements                                                                                                           | manage plugins                |
| All changing actions (create feed, reindex, language assignment, data fields, push, add past orders, payment status) | edit system configuration     |
| Quick cross-selling assignment: view / save                                                                          | view products / edit products |

The sidebar shows all areas, even without permission. When you open one, Shopware then blocks access.

## Themes

The plugin ships its own layouts for sliders, offcanvas, bundle/set and Conversion Booster. It contains specific adjustments for Zenit themes, for example for the buy button on product cards. Recompile the theme after installation or update (`bin/console theme:compile`) so that the plugin styles apply.

## Read more

{% content-ref url="/pages/tS4JTCj4GmgmDzAXPYMj" %}
[Tracking and data protection](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/tracking-and-data-protection.md)
{% endcontent-ref %}

{% content-ref url="/pages/R4ryPjO5ox01iI39KIJG" %}
[Troubleshooting and FAQ](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/troubleshooting-and-faq.md)
{% endcontent-ref %}

{% content-ref url="/pages/e00VEeT8TubzE8TB5J6M" %}
[When do changes take effect?](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/when-changes-take-effect.md)
{% endcontent-ref %}

{% content-ref url="/pages/cBKy95w4S0o2CevRDTsz" %}
[Installation](https://docs.codegiganten.de/plugin-documentation/en/apps/cross-selling-pro-ai-cart-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/en/apps/cross-selling-pro-ai-cart-cross-selling-bundles-and-sets/technical-operation.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.
