> 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/oxid/sdk-v6.x-sdk-v5.x/sdk-v5.x.md).

# SDK v5.x

FactFinder Web Components v4.x for Oxid v7

## Overview

[![Packagist Version](https://camo.githubusercontent.com/b4e3434c2b6fd073e9ff250f6a51b4f9110a2f7d80e8ffdf9c1c215e3c95d3b8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f6d696b726f6e2f6f7869642d6661637466696e646572)](https://packagist.org/packages/omikron/oxid-factfinder) [![GitHub contributors](https://camo.githubusercontent.com/5dfe0bf64711f1ca323f5c502f8e05a18de0912a735c78f98a94d5ac33e1dc26/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f636f6e7472696275746f72732f464143542d46696e6465722d5765622d436f6d706f6e656e74732f6f7869642d6573686f702d6d6f64756c65)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/graphs/contributors)

This document helps you integrate the FactFinder Web Components SDK into OXID eShop. It also provides a concise overview of its primary functions. The *Installation* chapter walks you through the suggested process. The *Backend Configuration* chapter explains the OXID backend options. The *Web Component Integration* chapter describes how the components interact with the shop and how to customize them.

Our OXID module provides a basic integration for the default OXID Apex theme. Most projects need modifications to fit their requirements. For advanced features, see the [Web Components documentation](https://docs.fact-finder.com/webcomponents-overview/web-components-4.x./).

### Requirements

* OXID eShop 7.0 or higher
* PHP version 8.0 or higher

**Note:** For OXID eShop 6.x and PHP 7, use SDK version 4.x.

### Installation

To install the module, open your terminal and run the command:

```
composer require omikron/oxid-factfinder
```

### Activating the Module

From the root of your OXID installation, clear the cache:

```
rm -rf source/tmp/*
```

In the OXID backend, check that the module output is activated under **Extensions → Modules**.

[![Module Enabled](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/module-enabled.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/module-enabled.png)

**Note:** You may also need to install the module from the command line. Run this command from the project root:

```
vendor/bin/oe-console oe:module:install vendor/omikron/oxid-factfinder
```

**Note:** If you have permission issues after installation, set the correct project permissions with `chown` and `chmod`. See the [official documentation](https://docs.oxid-esales.com/eshop/en/latest/installation/new-installation/preparing-for-installation.html#schritt-customising-file-and-directory-permissions).

### Backend Configuration

Once the module is activated, find the configuration page under **Extensions → Modules → FACT-Finder® Web Components | Omikron Data Quality GmbH → Settings**. The following sections cover each setting.

#### Main Settings

[![Main Settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/main-settings.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/main-settings.png)

This section contains the configuration required for the module to work. Web Components and server-side communication with the FactFinder instance use this configuration. Enter the credentials you receive here.

* Server URL — the FactFinder instance URL.\
  **Note:** The URL must include a protocol, such as `https://`, and end with the version-specific endpoint. For example, use `FACT-Finder-7.3` for version 7.3 or `fact-finder` for NG.
* Channel — the channel that provides the data.\
  **Note:** The number of channel fields matches the active application languages. Set the correct channel for each language.
* Username and password for importing data to FactFinder.
* Username and password for fetching data from FactFinder.
* Authorization Prefix and Authorization Postfix.\
  **Note:** FactFinder NG does not require these fields.
* Version — the FactFinder version in use.\
  **Note:** The module supports FactFinder 6.9 through NG. An incorrect version can prevent Web Components from communicating with FactFinder.
* API Version — the FactFinder API version in use.\
  **Note:** The module supports API versions `v4` and `v5`. An incorrect version can prevent Web Components from communicating with FactFinder.

#### Buttons

[![Buttons](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/configuration-buttons2.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/configuration-buttons2.png)

**Test Connection Button**

Click `Test Connection` to verify your credentials. This test uses form data, so you do not need to save first. **Note:** This test uses the `de` channel input value.

**Export Feed Button**

This is one way to export a feed. See [Admin Panel Export](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/tree/release/5.x#admin-panel-export) for details.

**Test FTP Connection Button**

Use this button to test whether your shop can connect to the configured FTP/SFTP server. It uses parameters passed with the request, so you do not need to save the configuration first.

**Update Field Roles Button**

Use this button to update field roles after changing them in FactFinder. By default, field roles match the columns exported by the module. If you change a role column name, such as `Master` or `ProductNumber`, update the field roles. These columns hold the `Master article number` and `Product number` roles, respectively.

#### Advanced Settings

[![Advanced Settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/advanced-settings.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/advanced-settings.png)

* `Use URL params?` — Select this option to add each query parameter to the URL.
* `Additional parameters` — Define values for `add-params`, `add-tracking-params`, `keep-url-params`, and `parameter-whitelist`. Web Components uses these values in its requests. See the [Web Components documentation](https://docs.fact-finder.com/webcomponents-overview/web-components-4.x./).
* `Anonymize User ID?` — Select this option to send an anonymized user ID with tracking requests. By default, the regular ID field from the user table is sent.
* `Use Proxy` — Select this option to send each Web Components request to the module controller first. The controller forwards it to FactFinder. **Note:** Read the Proxy section for setup instructions.
* `How to count single click on "Add to cart" button?` — Select how to count a single click on the **Add to cart** button.
* `Send the SID as userId when user not logged in?`

**Proxy**

The Proxy feature adds an OXID controller that acts as middleware between Web Components and FactFinder. The following diagram shows the data flow when the proxy is enabled. [![Communication Overview](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/communication-overview.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/communication-overview.png) The middleware controller lets you customize requests and responses. You can also implement a fallback strategy when a forwarded request does not produce a valid response.

```
   //src/Controller/SearchResultController.php:65
   protected function fallback(): void
    {
        //this function could be used to implement fallback logic in case of any communication error.
        $this->showJsonAndExit('');
    }
```

To enable the proxy, add rewrite rules to your HTTP server configuration. Web Components appends URL parts to the base URL, which OXID cannot read. OXID uses the `cl` and `fnc` query parameters to instantiate a controller and run its function. It does not route URL parts. Therefore, AJAX requests must target `index.php` with these parameters. Without these rules, each request returns a 404 error.

NGINX

```
  location ~ \.ff  {
      rewrite [a-zA-Z].ff /$1 break;
  }

  # the the version might need to be adjusted, depends on the API version you use
  location ~ /rest/v  {
      rewrite rest/v[0-9]/[a-zA-Z]*/ /$1 break;
   }
```

APACHE

```
RewriteRule (.*\.ff)$ /$1 [L]

# the the version might need to be adjusted, depends on the API version you use
RewriteRule /rest/v[0-9] /$1 [L]
```

#### Features Settings

[![Features Settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/features-settings.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/features-settings.png)

* `Use FACT-Finder® for category pages?` — Select this option to use Web Components on category pages. See the following section for details.
* Campaigns — Enables `ff-campaign-product` on product pages and `ff-campaign-feedbacktext` and `ff-campaign-shopping-cart` on cart pages.
* Recommendations — Enables `ff-recommendation` on product pages.
* Similar products — Enables `ff-similar-products` on product pages.
* Pushed products — Enables `ff-campaign-pushed-products` on cart pages.
* Disable cache — Controls the use of search result caches.

#### Using FACT-Finder® on category pages

To preserve category URLs and SEO, the module uses standard OXID routing. It passes custom parameters to the FactFinder search request. A search event is emitted as soon as a user opens a category page.

#### Feed Settings

[![Feed Settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/feed-settings.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/feed-settings.png)

This section lets you select attributes to export. To export an attribute in a separate column, select it and set `Multi-Attribute` to `No`. If `Multi-Attribute` is set to `Yes`, the attribute is placed in the aggregated `FilterAttributes` column. **Note:** Selection attributes are always placed in `FilterAttributes`.

#### Export Settings

[![Export Settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/export-settings.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/export-settings.png)

Use the following fields to export a feed file to your FTP server. FactFinder can then import the file.

* FTP host
* FTP port
* FTP user
* FTP password

Additional:

* SSL-enabled - check this option, if your FTP server requires connection using secure protocol
* Automatic import of product - enables import executed by FACT-Finder® after uploading\
  **Note:** This option will not work if you have no FTP server configured
* Import Data - triggers Data (search database)
* Import Suggest - triggers Suggest database
* Import Recommendation - triggers Recommendation database
* Basic Auth user for HTTP export
* Basic Auth password for HTTP export\
  **Note:** Basic Auth is used to secure HTTP based export, you can read more about in the next section.
* Log path - path to log file where export log will be saved
* Proceed with export when error occurred

### Export Methods

#### HTTP Export

This method makes the feed available at a specific URL. Configure FactFinder to download the feed from this URL:

```
[YOUR_SHOP_URL]?cl=http_article_feed&fnc=export
```

For category export:

```
[YOUR_SHOP_URL]?cl=http_category_feed&fnc=export
```

For suggest category export:

```
[YOUR_SHOP_URL]?cl=http_suggest_category_feed&fnc=export
```

**Note:** The feed file is generated on demand and is not immediately available at this URL. The process may take some time.

**Basic Authentication**

Use [Export Settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/tree/release/5.x#export-settings) to secure the HTTP export with Basic Authentication. Include the credentials in the URL. Otherwise, FactFinder cannot download the feed file. Use the following syntax:

```
https://[username]:[password]@[REST_OF_URL]
```

#### FTP Export

With this approach, the exported feed file is uploaded to an FTP/SFTP server. Once uploaded, FactFinder can begin an import based on the file. All settings for this export method are in [Export Settings](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/tree/release/5.x#export-settings). The **Key** and **Key Passphrase** fields apply only to SFTP. The **SSL Enabled** field applies only to FTP.

**Note:** Used FTP/SFTP server should be also accessible to FACT-Finder®.

**Admin Panel Export**

`Export Feed` button located in module configuration, could be used to manually trigger an export. By clicking this button, you trigger the whole export process, including upload to FTP server and triggering a FACT-Finder® import (if enabled).

**Note:** This method does not download the feed file to your local file system. If you need to view it, please use the [HTTP Export](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/tree/release/5.x#http-export)

**Note:** Category export is not available here as clicking button start import on channel but category feed is supposed to be an enrichment for main article feed

**Console Commands**

There are two console commands located in the module `bin` directory, available for use. Simply run them using the installed PHP CLI.

```
php [MODULE_LOCATION]/bin/[COMMAND_NAME].php
```

* `feed-write.php` - only saves the feed file on local file system
* `feed-upload.php` - run full integration (just like clicking the `Export Feed` button in admin panel)

If you are using Oxid Enterprise and its multishop feature, you can specify the shop ID by using the `-s` parameter, e.g.

```
php source/modules/ff/ffwebcomponents/bin/feed-write.php -s1
```

If your shop supports multiple languages, enter the language identifier of the language you want to export by adding `-l` parameter to the command (e.g. `php bin/feed-write.php -l 1`). You can check the language identifiers at "Master Settings -> Languages". You can specify the type of the feed with the `-t` option. Default value is `product`. In order to switch for category, please use `-t category`

[![Languages](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/raw/release/5.x/docs/assets/languages.png)](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/docs/assets/languages.png)

### Tracking

See the full [Tracking Guide](https://web-components.fact-finder.de/documentation/4.x/tracking-guide). This module follows the guide to track the following events:

#### Login

The SDK tracks this event automatically.

#### Click on Product

The `ff-record` element bindings track this event automatically. **Note:** Add the `data-redirect` directive for this to work.

#### Add Product to Cart

Use the `registerAddToCartListener` function to register `click` events on form submit buttons. **Note:** See `src/views/frontend/blocks/campaign/product.tpl` for an example.

#### Place an Order

The `ff-checkout-tracking` element tracks this event on the order confirmation page.

### Contribute

For more information, click [here](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/.github/CONTRIBUTING.md)

You can also open a new issue if You spot a bug or just have an idea for module improvement To check currently opened issues [here](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/issues).

### License

FACT-Finder® Web Components License. For more information see the [LICENSE](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/blob/release/5.x/LICENSE) file.


---

# 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/oxid/sdk-v6.x-sdk-v5.x/sdk-v5.x.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.