> 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/installation-and-setup.md).

# Installation and setup

Install the plugin and walk through the setup wizard step by step until the first products are in the search.

You install the plugin like any Shopware plugin. A setup wizard then guides you through the connection to our search system, creating the product feed and reading in the products for the first time. Plan about half an hour for this. With large catalogs, reading in continues in the background afterwards.

{% hint style="info" %}
If you prefer not to do the initial setup yourself, we are happy to take care of it as a one-time setup service. Please contact us through the Shopware ticket system. This note is also shown at the top of the wizard.
{% endhint %}

## Before you start

Check on the page [Requirements](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/requirements.md) whether your shop is ready. Especially important: with Pull the feed address must be reachable from outside without a login.

## Install the plugin

1. In Shopware, open the extension manager (Extensions → My extensions).
2. Install and activate the plugin.
3. If needed, clear the Shopware cache.

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-a75376ff033b9129caa1961ec5497964b956bd81%2Fimage%20(82).png?alt=media" alt="Plugin in the Shopware extension manager"><figcaption></figcaption></figure>

During installation the plugin registers your shop with our search system automatically. This creates the **Installation Secret**, an access key that identifies your installation uniquely. The plugin stores it in the plugin configuration itself. Do not change it.

The **Account Secret** is missing at first. It is created in the wizard when your installation is connected to an account. An account groups several installations, for example live, stage and development. You can see both keys later in the plugin configuration in the card "Global configuration" (fields "Account secret" and "Installation secret"). The button "Test connection" there checks whether the connection works.

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-5c8ffd90ed06f2220318f7b64745defed5e2d7bc%2Fimage%20(81).png?alt=media" alt="Plugin configuration with Installation Secret, Account Secret and button to the wizard"><figcaption></figcaption></figure>

You can also reach the plugin via Content → InsightSearch. In the plugin configuration, the button "Open setup wizard" leads to the wizard.

### If the wizard is locked

If storing the Installation Secret automatically did not work during installation, the wizard says: "The setup wizard is currently locked because the installation key is missing for this shop installation." Click "Request installation key again". As soon as the key is stored, the wizard reloads and unlocks.

If an error message appears instead, this usually helps:

* If shop URL or instance ID are missing, check the `APP_URL` setting of your shop.
* If the key could not be requested right now, try again in a few minutes.
* For the third message, check the shop configuration and try again.

## The wizard step by step

In the header the wizard is called "Initial setup" and shows a progress bar with five steps: "Connection type", "Connect", "Validation", "Connect products" and "Indexing".

It appears as soon as you open the plugin dashboard for the first time, and the sidebar is hidden meanwhile. Your progress is saved in the browser. If you leave the page or reload it, you continue at the same place. Reading in the products continues in the background, so you can close the page at any time.

### Step 1: Connection type

Here you decide how this shop installation is connected to InsightSearch. There are two ways:

* **"Create new installation":** search and data stay separate for this shop. This is the normal case for a first setup.
* **"Connect to existing installation":** you keep using an existing account, for example when you set up a stage environment next to your live shop.

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-0025bf2b759cb79152b1fc83cecc4aadd068f8e2%2Fimage%20(83).png?alt=media" alt="Wizard, step create or connect account"><figcaption></figcaption></figure>

### Step 2a: Create new installation

Fill in three fields. The button "Continue" becomes active only when all are filled.

| Field                      | Meaning                                                                                                                  | Default       |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------- |
| "Shop name"                | A name by which you recognize the installation, for example "Main shop production", "Staging shop" or "DEV environment". | empty         |
| "Purpose (dev/stage/live)" | What the installation is used for. Choices: "Development", "Staging", "Production".                                      | "Development" |
| "E-mail"                   | Address for messages about critical problems with the search.                                                            | empty         |

{% hint style="warning" %}
The default for the purpose is "Development". For your live shop, choose "Production" explicitly.
{% endhint %}

We use the e-mail address only to inform you about critical problems related to the search. In the InsightSearch settings you later decide whether and to which address such messages are sent.

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-5ee57403078d7bbb985e8d7c619c3d8bf0dab75a%2Fimage%20(84).png?alt=media" alt="Wizard, step account data"><figcaption></figcaption></figure>

With "Continue" the plugin creates the installation. The button "Back" is only visible as long as nothing has been connected yet.

### Step 2b: Connect to existing installation

You see a field "Account secret" and the button "Link". It becomes active once the field is filled. Enter the Account Secret of your existing account. You find it in the plugin configuration of an already connected installation, card "Global configuration", field "Account secret".

The plugin stores the secret and then checks it. How to split several installations sensibly 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).

### Step 3: Validation

The plugin briefly checks the connection ("We are checking the connection. This only takes a moment."). On success it continues automatically. If the check fails, the wizard jumps back to step 2 and shows an error message. Check your entries then.

### Step 4: Connect products (create feed)

This is the most important step. Our search system needs your products. Here you decide how they reach us. The default is a **product feed**, similar to a Google feed: it is created in Shopware as a sales channel of type "Product comparison" and produces an export file that our search system fetches regularly. Without this feed the search has no products and delivers no results.

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-2054e6397e397a5880e6c3c10d14b7072609f80e%2Fimage%20(85).png?alt=media" alt="Wizard, step create product feed"><figcaption></figcaption></figure>

You find the same form later in the "Sources" area in the dialog "Add another feed".

**Indexing mode (required):**

* **"Pull (default): InsightSearch fetches the product feed".** Preselected. Our search system calls the feed address regularly, so the address must be reachable from outside (no password protection, no htaccess block).
* **"Push: the plugin sends the products (for DEV/stage)".** Intended only for DEV and stage environments that are not reachable from outside. The plugin sends the products itself. For this, Shopware's background processing must be running.

**Fields of the form:**

| Field                                                                 | Effect                                                                                                                                   | Default                                                   |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| "Name" (required)                                                     | Name for the product feed and the related sales channel, for example "InsightSearch product feed main shop".                             | "InsightSearch Feed"                                      |
| "Storefront sales channel" (required)                                 | Only products from this channel go to the search. Only storefront channels are allowed.                                                  | none, choose from your sales channels                     |
| "Storefront domain" (required)                                        | Domain through which the export is reachable for us, usually the main domain. Selectable only once a sales channel is chosen.            | If the channel has exactly one domain, it is preselected. |
| "Language" (required)                                                 | Language of the texts in the feed. Only languages of the channel are offered. The search can later also be used in other shop languages. | default language of the channel                           |
| "Currency" (required)                                                 | Currency of all prices in the feed. Only currencies of the channel.                                                                      | currency of the channel                                   |
| "Customer group" (required)                                           | Price and visibility rules (Rule Builder) are applied on this basis, so the feed uses the same conditions as the shop.                   | customer group of the channel                             |
| "Use existing dynamic product group (optional)"                       | Choose only if you want to use your own product group.                                                                                   | "Create new product group automatically"                  |
| "Use existing product comparison sales channel (optional)", Pull only | Uses feed template and access key of an existing channel. The other fields are dropped.                                                  | empty                                                     |

If you change the sales channel, domain, language, currency and customer group are reset and preselected again.

There is no choice of feed template, it is created automatically. You adjust which data fields it contains later with "Edit data fields" (see [Edit data fields](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/feed-template-editor.md)).

With "Create feed" you start creating. The button becomes active as soon as all required fields are filled.

**What is created in the shop (Pull):**

* A new, active sales channel of type "Product comparison" with your name. It takes payment method, shipping method, country and navigation from the storefront channel.
* A dynamic product group "InsightSearch Feed" with date and time in its name. The filter is "Active = yes". If you chose your own group, no new one is created.
* A product export in XML format (UTF-8) that includes variants and is generated by a scheduled task.
* The feed address, built from your domain and the access key of the export. You see it later in the "Sources" area and in the product comparison channel under "Export URL".
* An automatic language assignment for the chosen sales channel and language.

Shopware checks the template before registering. If it is faulty, you see: "The product comparison sales channel was created, but the feed template contains errors, so the feed was not registered. Check the template in the sales channel." If the template merely could not be checked, the feed is created anyway and you see a note.

{% hint style="info" %}
If creating fails after the channel was created, the channel is kept. It is then preselected under "Use existing product comparison sales channel", and a new attempt reuses it instead of creating a second one.
{% endhint %}

**With Push** no sales channel and no export are created. The plugin creates a push index instead ("Push index created, the products are being transferred now.") and starts the transfer immediately. If the start does not work, you see: "The automatic indexing could not be started. You can trigger it manually from the dashboard later." Without a dynamic product group, all products of the sales channel are transferred.

### Step 5: Indexing and completion

The feed is now being processed. First our search system checks reachability and completeness, then the products are evaluated, data quality is checked and the feed is prepared for the search. Only then is it available to the search. This takes a while depending on the number of products.

<figure><img src="https://923488348-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FebcjSiStaIxyVJ83vjsL%2Fuploads%2Fgit-blob-e6da4ec33283c2de42110c2e72d9dcc4b92a5163%2Fimage%20(86).png?alt=media" alt="Wizard, last step with first indexing"><figcaption></figcaption></figure>

You see three checkpoints with the status "Pending" or "Done": "Validation", "Quality check" and "Indexed". The wizard also shows how long the run has been going ("Running since") and when it was last updated. The display updates itself every few seconds.

With Push, a bar additionally shows "Products transferred" with count, percentage and estimated remaining time. If Shopware's background processing is not running, this bar stands still.

The wizard warns in these cases but does not abort:

* Push with no progress for over 10 minutes.
* A feed indexing that runs longer than 30 minutes. With very large catalogs this can be normal.
* The status could not be retrieved several times. Indexing may still be running.

For warnings and errors there is a "Technical details" area that you can show to our support.

**Completion:** When indexing is finished, the wizard switches the search on itself (switch "Enable search" in the plugin configuration) and closes. You then see the normal plugin dashboard with the overview.

## If reading in fails

If indexing fails, the wizard shows a red card "Indexing failed". With Pull and a recognized cause, a help block appears below with:

* the title of the error type and, if known, the "HTTP status",
* the feed URL with the link "Open feed in browser",
* the lists "Possible causes" and "What you can do",
* the note for stage and test systems: they are often protected by a password, an IP block or an internal domain. Our search system fetches the feed over the internet, so the address must be public and reachable without a login.

In the "Sources" area the same block is collapsed behind "Show help".

### Causes and what you can do

| Message                                         | Common causes                                                                                                                | What you can do                                                                                                                                                                           | Retried automatically |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| "The feed is protected by a login"              | password protection or Basic Auth, IP block or firewall, bot protection (for example Cloudflare)                             | Open the feed address in a private browser window; it must load without a login. Exclude the address from the protection or allow our requests (user agent "CogiInsightSearch-Feed/1.0"). | no                    |
| "Access to the feed is denied"                  | as above                                                                                                                     | Make the address public, allow requests with the user agent "CogiInsightSearch-Feed/1.0" in your firewall or bot protection.                                                              | no                    |
| "The feed was not found at this URL"            | product export deleted or deactivated, access key changed, wrong domain (for example after a move or a stage copy)           | In Shopware, check under Marketing → Product comparison that the export is active. Open the address in the browser. If needed, create the feed again in the wizard.                       | no                    |
| "The shop is in maintenance mode"               | maintenance mode for shop or sales channel                                                                                   | End maintenance mode or exclude the feed address from it.                                                                                                                                 | yes                   |
| "The shop had an error while creating the feed" | error in the shop, very large catalog                                                                                        | Check the Shopware log (var/log), open the address in the browser. For large catalogs, enable "Generate in background" in the product export.                                             | yes                   |
| "Too many requests in a short time"             | shop or search system throttles briefly                                                                                      | Wait a moment.                                                                                                                                                                            | yes                   |
| "The feed took too long"                        | generation takes too long, shop under load                                                                                   | Enable "Generate in background" with a suitable interval in the product export, try again later.                                                                                          | yes                   |
| "The feed domain cannot be reached"             | domain not publicly resolvable (local or internal stage domain), misspelled, not set up                                      | Use a publicly reachable domain for the channel, check the domain of the sales channel.                                                                                                   | no                    |
| "The server refuses the connection"             | web server not reachable or not running, firewall                                                                            | Check reachability from outside, allow it in the firewall.                                                                                                                                | yes                   |
| "The SSL certificate is not valid"              | expired, invalid, does not match the domain, self-signed                                                                     | Set up a valid certificate (for example Let's Encrypt), then try again.                                                                                                                   | no                    |
| "The feed is not valid XML"                     | response is HTML or truncated, template modified                                                                             | Check the address in the browser. Create the feed again in the wizard so the right template is used.                                                                                      | no                    |
| "The feed contains no products"                 | channel without products, products not visible or not active, a filter in the export (for example stock) excludes everything | Check sales channel, visibility and dynamic product group.                                                                                                                                | no                    |
| "The feed could not be loaded"                  | catch-all if no exact cause was recognized                                                                                   | Open the address in the browser, try again. If the error persists, support helps.                                                                                                         | yes                   |

More help is on the pages [Reading the product feed fails](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/reading-the-product-feed-fails.md) and [Troubleshooting](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/troubleshooting.md).

### Automatic retry

For causes that can disappear by waiting, the wizard tries up to three times itself, after 30, 60 and 120 seconds. You see a countdown ("We will try again automatically in {seconds} seconds (attempt {n} of 3).") and the buttons "Try again now" and "Stop automatic retries".

* After "Stop": "Automatic retries are stopped. You can try again yourself at any time."
* After three attempts, the wizard no longer retries by itself and asks you to check the hints.
* For causes that waiting does not fix: "Waiting will not fix this error. Check the hints and then try again."

The button "Try again" is always there when no countdown is running. A Push is never retried automatically, only by hand.

## What the wizard creates in the shop

In summary:

| With Pull                                                             | With Push                                                |
| --------------------------------------------------------------------- | -------------------------------------------------------- |
| Sales channel "Product comparison" with access key                    | no sales channel                                         |
| Dynamic product group with filter "Active = yes" (or your chosen one) | your chosen group, otherwise all products of the channel |
| Product export (XML) with the feed address                            | no export, the plugin sends the products                 |
| Automatic language assignment                                         | Automatic language assignment                            |

At the end the wizard also switches the search on. During installation the plugin also creates two custom fields and the sort option "Recommended". The sort option appears for visitors in the sorting dropdown; you can adjust or deactivate it in Shopware.

## What to do afterwards

In most cases the search already delivers first results now. For good quality a few more steps are worthwhile, for example assigning languages, setting up filters and testing the search. You find the order on the page [Getting started](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/getting-started.md).

## Continue reading

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

{% content-ref url="/pages/UKhMX3Zla832boJXFREa" %}
[Sources](https://docs.codegiganten.de/plugin-documentation/en/apps/search-intelligent-and-ai-optimized/indices.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/installation-and-setup.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.
