> 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/cms-elements-and-recommendations.md).

# Shopping Experiences and recommendations

What the plugin adds to the Shopping Experiences manager, which pages you can design for the search, and how the search works together with Cross-Selling Pro.

This page answers two questions: What does the search plugin add to the Shopping Experiences manager of Shopware, and how does the search work together with the plugin "Cross-Selling Pro - KI Cross Selling". It helps if you want to design pages for the search or use recommendations in the search window.

## What the plugin adds to the Shopping Experiences manager

The search plugin adds exactly **one block with one element**, and both are deprecated.

| What                              | Name in the admin                       |
| --------------------------------- | --------------------------------------- |
| Block (block category "Commerce") | "AI Basis Empfehlungsslider (veraltet)" |
| Element                           | "KI-Produktempfehlungen (veraltet)"     |

The element shows a notice: the slider is no longer developed further. For new pages, please use the recommendation elements of "Cross-Selling Pro - KI Cross Selling". **Existing pages with the old block keep working**, you do not have to rebuild anything.

{% hint style="info" %}
For new pages we recommend Cross-Selling Pro. It brings the blocks of the block category "AI Cross-Selling", for example cards, list, grid, mosaic and spotlight. Its setup is described in the documentation of Cross-Selling Pro.
{% endhint %}

### Fields of the deprecated slider

The slider shows complementary products for the current article (recommendation type "Goes well together", not selectable). It loads its products after the page has been built and shows a loading message, or a note if there is no result. It needs the search index of the sales channel and language, but not the plugin Cross-Selling Pro.

The labels below are the German admin labels, because the element is only labelled in German in the admin.

| Field                                      | Effect                                                                                                          | Default              |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------- | -------------------- |
| "Titel" (title)                            | Heading above the slider.                                                                                       | "Passt gut zusammen" |
| "Untertitel" (subtitle)                    | Optional additional text.                                                                                       | empty                |
| "Limit"                                    | Number of products, 1 to 50.                                                                                    | 6                    |
| "Modus" (mode)                             | "Gemischt" (mixed), "Nur gleiche Marke" (same brand only) or "Nur gleiche Kategorie" (same category only).      | mixed                |
| "Nur verfügbare Produkte" (available only) | Hides products that cannot be delivered.                                                                        | off                  |
| "Produktquelle" (product source)           | "Automatisch (Produktdetailseite)" uses the product of the current page, "Festes Produkt" a product you choose. | automatic            |
| "Referenzprodukt" (reference product)      | The fixed product. Empty means: product of the current detail page.                                             | empty                |

Under "Experten-Einstellungen anzeigen" (show expert settings) you find more switches and numeric values:

* Switches: exclude same brand, prefer category, exclude article group (hides articles of the same variant group) and forbid identical title (default: on).
* Numeric values: brand penalty (0.25), category bonus (0.1), internal category penalty (0), brand boost, category boost and category path boost (1 each), minimum hit rate (0 to 3), brand, category, price, attribute and tag weighting (0.25 each) and maximum price deviation (1 means up to 100 %).

Every value has a help text in the admin. For daily use the defaults are usually enough.

## What is not a Shopping Experiences element

Some parts of the search look like building blocks but are not elements you drag into a Shopping Experience:

* **Search field and search window:** part of the storefront search. You switch them on in the plugin configuration ("Activate search", "Search activation mode").
* **Search results page and listing filters:** The search supplies the Shopware search results page ("Supply the Shopware search results page via InsightSearch"). There is no separate element for it.
* **Rule banner:** A Shopping Experience that you assign to a search term rule appears as a banner above the results. You choose the Shopping Experience in the rule itself, not in a block. More on the page [Search term rules](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/search-term-rules.md).
* **Purchase attribution:** This is not a visible place but an invisible marker that credits a purchase to the search (see below).

## CMS pages for the search

For two situations in the search window you can show your own Shopping Experience. You choose it in the Shopware admin under Extensions → My extensions → plugin configuration, in the card "Search settings". Both fields can be set per sales channel.

### CMS page for the empty search state

"CMS page for the empty search state" appears when the search window is opened without a search term. Without a choice, the default placeholder text appears. Below it appear the search suggestions and popular searches, if there are any. If a page is chosen, the search window also opens on a click into the empty field when there are no suggestions. This function is available to everyone.

Good choices are image and text banners, entry points into categories, promotions or a bestseller slider. Keep the page compact: on a phone the search window fills the screen.

### CMS page for searches without results

"CMS page for searches without results" appears in the search window when a search finds nothing. Without a choice, the default message appears.

{% hint style="warning" %}
This selection field exists only with the purchased add-on **"CMS bei keinen Treffern"** (CMS for no results; purchase in Shopware). Without the add-on, the plugin configuration shows a note at this place with a "Details" button. When the add-on is active, it says that the function is active for your shop.
{% endhint %}

The page appears only in the search window, not on the search results page. Good choices are a help text, links to categories, a slider with bestsellers or recommendations and contact details.

With the setting "Substitute products in addition to the CMS page for searches without results" (default: off) you decide whether substitute products follow below the page. Leave it off if your page shows products itself, otherwise duplicate product blocks appear. The "Get advice" note of the [shopping assistant](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/shopping-assistant.md) also appears next to the CMS page.

{% hint style="info" %}
There is no "current product" on these pages. A recommendation slider with product source "Automatic (product detail page)" finds no product there. Choose a fixed product or a recommendation type without product reference. We have not tested this case for all elements.
{% endhint %}

On a phone, in the designs "Results first" and "Like an app", banners and pages appear below the products.

## Working together with Cross-Selling Pro

If "Cross-Selling Pro - KI Cross Selling" is installed in the same shop, the search can use two things from it: complementary products below the results and better substitute products for searches without results.

### Requirements

The functions are active ("coupled") when

1. Cross-Selling Pro is installed and active in the same shop,
2. it is connected to your InsightSearch account, and
3. a recommendation index is assigned to the sales channel and language.

If a requirement is missing, the two switches are greyed out. The notice then says that the plugin needs Cross-Selling Pro and has to be installed and connected in the same shop. A saved value is kept. Both switches count as **on** when no value has been saved.

### "Goes with" in the search window

With the switch "Goes with" in the search overlay (card "Search settings"), the search window shows up to four matching products for the first result below the results. The heading is "Goes with {name of the first result}". Results that are already visible are not shown again. If there is no result, or it takes too long (more than about 1.5 seconds), nothing appears.

### Substitute products for searches without results

With the switch "Substitute products from Cross-Selling Pro - KI Cross Selling" (card "No results & related results"), the substitute products for a search without results come from the recommendation AI and match the search term instead of just being popular.

* They apply in the search window **and** on the search results page. The heading is "You might be interested in".
* You set the number with "Number of substitute products" (4 to 12, default 8).
* In the search window, the search asks the recommendation AI only if it could not rescue the search itself. A loosened or corrected search takes precedence.
* This requires a Cross-Selling Pro package of **Starter** or higher. In the free package, the normal substitute products of the search remain.
* On the search results page the products are not personalised. They are not delivered to search engine crawlers.

### Cart button

In the search window, the cards follow the setting "Add to cart button in the search overlay" (default: off). This applies equally to results, "Goes with" and the substitute products from Cross-Selling Pro. Simple articles go straight into the cart, articles with variants show "Select", sold-out articles have no button. In the "Native" layout the setting has no effect. On the search results page, the substitute products show the normal Shopware product boxes.

### Quota

Every call to the recommendation AI counts toward the recommendation quota of Cross-Selling Pro, namely "Goes with" (per search with results) and the substitute products for searches without results. Automated visits such as search engine crawlers do not call it. When the quota is reached, simply nothing appears in these areas, and the search window stays unchanged otherwise.

### Personalisation

Both plugins use the same visitor recognition. The cookie banner has an entry "Recognition for search and recommendations" for it, and one consent covers both plugins. With "Personalise search results" (default: off), brands and categories a visitor viewed recently move up slightly. This applies only with consent or for logged-in customers. The recommendations in the search window ("Goes with", substitute products) are not tailored to the single customer, because the pages are cached.

### Placeholder image

The "Placeholder image for products without image" from the search settings appears in the search window, for substitute products and in the shopping assistant. Cross-Selling Pro uses it too if it has no image of its own. An image maintained there takes precedence, otherwise the image of the search applies, otherwise a grey placeholder. Search results page and category pages keep showing the Shopware presentation.

### Revenue attribution

A purchase counts as "Revenue via search" per purchased product (or its variant) if that product was clicked in the search or put into the cart from there. Up to 72 hours may pass between click and order, in the same browser. If a cart line carries the marker of the search **and** that of a recommendation, it counts as recommendation revenue and not as search revenue.

### If Cross-Selling Pro is missing

Without Cross-Selling Pro nothing changes in the shop. There is no "Goes with". For searches without results the search shows its own substitute products (popular products) as long as "Show substitute products when nothing is found" is on (default: on, 4 to 12 products, default 8). The old slider keeps working.

## Further reading

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

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

{% content-ref url="/pages/M8CXII0ghuvtdpPzO3e7" %}
[More configuration cards](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/more-configuration.md)
{% endcontent-ref %}

{% content-ref url="/pages/EKzI7kx2ZAjSIJVZz2DI" %}
[Shopping assistant (beta)](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/shopping-assistant.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/cms-elements-and-recommendations.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.
