> For the complete documentation index, see [llms.txt](https://docs.fact-finder.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fact-finder.com/magento/sdk-v5.x/web-component-integration.md).

# Web Component integration

Activate or deactivate web components from the Magento 2 configuration page.

Web Component templates live in:

```
src/view/frontend/templates/ff
```

Module styles live in:

```
src/view/frontend/web/css/source/ff
```

The source stylesheet is:

```
src/view/frontend/web/css/source/_module.less
```

Integrate templates anywhere in your shop. Magento 2 layouts are the recommended approach. For example, this SDK integrates `ff-suggest` into the `ff-searchbox` template:

```xml
<referenceBlock name="top.search">
    <action method="setTemplate" ifconfig="factfinder/general/is_enabled">
        <argument name="template" xsi:type="string">Omikron_Factfinder::ff/searchbox.phtml</argument>
    </action>
    <block class="Magento\Framework\View\Element\Template" name="factfinder.suggest" as="suggest" ifconfig="factfinder/general/is_enabled" template="Omikron_Factfinder::ff/suggest.phtml" />
</referenceBlock>
```

You can also instantiate a block with the Magento Layout API. This is not the recommended approach:

```php
<?php echo $this->getLayout()
->createBlock(\Magento\Framework\View\Element\Template::class)
->setTemplate('Omikron_Factfinder::ff/suggest.phtml')
->toHtml(); ?>
```

FACT-Finder Web Components uses Handlebars for HTML templates. See the [Handlebars documentation](https://handlebarsjs.com/).

## Configuration element

The main Web Components configuration is in `src/view/frontend/templates/ff/communication.phtml`. Its view model is `src/ViewModel/Communication.php`. The template belongs to the `default` layout and is added to `after.body.start`.

This template is essential. Ensure your project includes it. Avoid overriding both the template and view model.

## Searchbox integration and functions

Once you activate FACT-Finder Integration, the searchbox component automatically replaces the default Magento 2 search.

Its template is:

```
src/view/frontend/templates/ff/searchbox.phtml
```

Searches redirect to the FACT-Finder search-results page. The module adds relevant data to its URL, including the FACT-Finder channel and query string. Its layout definition is:

```
src/view/frontend/layout/factfinder_result_index.xml
```

That layout already integrates templates including `ff-record-list`.

## Data transfer between the shop and FACT-Finder

[![Communication Overview](https://github.com/FACT-Finder-Web-Components/magento2-module/raw/release/5.x/docs/assets/communication-overview.png)](https://github.com/FACT-Finder-Web-Components/magento2-module/blob/release/5.x/docs/assets/communication-overview.png)

By default, search and suggest requests go directly to FACT-Finder. Enable **Proxy** only when you must modify request parameters or responses.

### Using Proxy

Proxy passes each search request through this controller before returning it to the frontend:

```
src/Controller/Proxy/Call.php
```

Add an `afterExecute` plugin through Magento Interceptors to enrich FACT-Finder data. Proxy adds HTTP and Magento processing overhead. Avoid it without a clear requirement.

## Using FACT-Finder on category pages

The module preserves category URLs and SEO by using Magento routing with custom search parameters. Category-page searches start immediately through `searchImmediately`. Enable the corresponding **Main Settings** option.

### Set the CategoryPath field name

The SDK uses `CategoryPath` by default. Set the field name in the SDK configuration if your FACT-Finder category field differs.

[![Main Settings](https://github.com/FACT-Finder-Web-Components/magento2-module/raw/release/5.x/docs/assets/category-field-name.png)](https://github.com/FACT-Finder-Web-Components/magento2-module/blob/release/5.x/docs/assets/category-field-name.png)

## Tracking

Web Components tracks these events:

* Product clicks
* Add-to-cart actions
* Order purchases
* User logins

For click tracking, use the `data-redirect` directive described in the [tracking guide](https://web-components.fact-finder.de/documentation/4.x/tracking-guide). Add-to-cart tracking uses `src/view/frontend/web/js/catalog-add-to-cart-mixin.js`. It requires the base `catalog-add-to-cart.js`.

Checkout tracking uses `ff-checkout-tracking` in `src/view/frontend/templates/ff/checkout-tracking.phtml`. This extends `checkout_onepage_success`. If your checkout uses another layout, append this template there. Use `src/ViewModel/Order.php` to provide the necessary backend data.

Login tracking calls `factfinder.tracking.login` from `src/view/frontend/templates/ff/communication.phtml`.


---

# 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.fact-finder.com/magento/sdk-v5.x/web-component-integration.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.