PHPackages                             omikron/oxid-factfinder - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. omikron/oxid-factfinder

ActiveOxideshop-module[Utility & Helpers](/categories/utility)

omikron/oxid-factfinder
=======================

FACT-Finder® Web Components for OXID eShop

v6.3.0(1mo ago)09.6k4[1 issues](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/issues)[2 PRs](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module/pulls)proprietaryPHPPHP ^8.1CI passing

Since Sep 14Pushed 1mo ago5 watchersCompare

[ Source](https://github.com/FACT-Finder-Web-Components/oxid-eshop-module)[ Packagist](https://packagist.org/packages/omikron/oxid-factfinder)[ RSS](/packages/omikron-oxid-factfinder/feed)WikiDiscussions release/6.x Synced 2d ago

READMEChangelog (10)Dependencies (16)Versions (49)Used By (0)

FACT-Finder® Web Components for OXID eShop
==========================================

[](#fact-finder-web-components-for-oxid-eshop)

[![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 to integrate the FACT-Finder® Web Components SDK into your Oxid Shop. In addition, it gives a concise overview of its primary functions. The first chapter *Installation* walks you through the suggested installation process. The second chapter *Backend Configuration* explains the customisation options in the Oxid backend. The final chapter *Web Component Integration* describes how the web components interact with the shop system and how to customise them.

Our Oxid plugin offers a basic working integration for default Oxid Apex theme. Most projects may require modifications in order to fit their needs. For more advanced features please check our official [WebComponnents documentation](https://web-components.fact-finder.de/documentation/5.x/install-dist).

Table of contents
-----------------

[](#table-of-contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Activating the Module](#activating-the-module)
- [Backend Configuration](#backend-configuration)
    - [Main Settings](#main-settings)
        - [Buttons](#buttons)
            - [Test Connection Button](#test-connection-button)
            - [Export Feed Button](#export-feed-button)
            - [Test FTP Connection Button](#test-ftp-connection)
            - [Update Field Roles Button](#update-field-roles)
    - [Advanced Settings](#advanced-settings)
        - [Proxy](#proxy)
    - [Features Settings](#features-settings)
        - [Using FACT-Finder® on category pages](#using-fact-finder-on-category-pages)
    - [Feed Settings](#feed-settings)
    - [Export Settings](#export-settings)
- [Export Methods](#export-methods)
    - [HTTP Export](#http-export)
    - [FTP Export](#ftp-export)
        - [Admin Panel Export](#admin-panel-export)
        - [Console Commands](#console-commands)
- [Tracking](#tracking)
    - [Login](#login)
    - [Click on Product](#click-on-product)
    - [Add Product to Cart](#add-product-to-cart)
    - [Place an Order](#place-an-order)
- [Modification Examples](#modifications-examples)
    - [Enrich data received from FACT-Finder](#enrich-data-received-from-fact-finder)
- [Contribute](#contribute)
- [License](#license)

Requirements
------------

[](#requirements)

- OXID eShop 7.0 or higher
- PHP version 8.1 or higher

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

Installation
------------

[](#installation)

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

```
composer require omikron/oxid-factfinder

```

Activating the Module
---------------------

[](#activating-the-module)

From the root of your Oxid installation, clear the cache with:

```
rm -rf source/tmp/*

```

Check in the Oxid backend "Extensions -> Modules" if the module output is activated.

[![Module Enabled](docs/assets/module-enabled.png "Module enabled")](docs/assets/module-enabled.png)

**Note:** Sometimes you need also install module from command line. Please execute from project root:

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

```

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

Backend Configuration
---------------------

[](#backend-configuration)

Once the module is activated, you can find the configurations page under "Extensions → Modules → FACT-Finder® Web Components | Omikron Data Quality GmbH -> Settings". All sections will be covered in the following paragraphs.

### Main Settings

[](#main-settings)

[![Main Settings](docs/assets/main-settings.png "Main settings")](docs/assets/main-settings.png)

This section contains a critical configuration, which is required in order for the module to work. All fields are self-explained. Configuration set here is used by both Web Components and during the server side communication with FACT-Finder® instance. Credentials you will be given should be placed here.

- Server URL - FACT-Finder® instance url
    **Note:** Server URL should contain a used protocol: (e.g. `https://`) and should end with `fact-finder` (e.g. `https://my-domain.fact-finder.de/fact-finder`)
- Channel - Channel you want to serve data from
    **Note** The number of channel fields is adjusted to the number of active languages used in application. Please make sure you set a correct channel for a given language.
- Username for the FACT-Finder Import - your username in FACT-Finder account (necessary if you want to automatically execute import data in FACT-Finder).
- Password for the FACT-Finder Import - your password in FACT-Finder account
- FACT-Finder API key - for fetching data from FF (necessary to use Web Components integration)

### Buttons

[](#buttons)

[![Buttons](docs/assets/configuration-buttons.png "Configuration Buttons")](docs/assets/configuration-buttons.png)

#### Update Field Roles Button

[](#update-field-roles-button)

This functionality allows you to update field roles if you have changed them in FACT-Finder. The field roles are by default configured accordingly to the columns exported by the module. If you are about change one of the column name that serves as a role e.g. `Master` or `ProductNumber`, that holds the `Master article number` and `Product number` roles respectively, please remember to update the field roles with that functionality

#### Export Feed Button

[](#export-feed-button)

It is a one of possible ways of exporting feed. You can find more details in section [Admin Panel Export](#admin-panel-export)

#### Test Connection Button

[](#test-connection-button)

By clicking the `Test Connection` button you can check if your FACT-Finder API key is correct and SDK could connect with FACT-Finder API successfully. This functionality uses form data, so there is no need to save first. **Note:** This functionality uses `de` channel input value.

#### Test FTP Connection Button

[](#test-ftp-connection-button)

This functionality allows you to test if your shop can successfully connect to configured FTP/SFTP server. It uses parameters passed down with the request so there is no need to save the configuration before.

#### Test Push Import Button

[](#test-push-import-button)

By clicking the `Test Push Import` button you can check if your FACT-Finder username and password is correct. This functionality uses form data, so there is no need to save first. **Note:** This functionality uses `de` channel input value.

### Advanced Settings

[](#advanced-settings)

[![Advanced Settings](docs/assets/advanced-settings.png "Advanced settings")](docs/assets/advanced-settings.png)

- `Anonymize User ID?` - check this option if you want to send user id with tracking requests in anonymized form. By default, the regular id field from user table is sent.
- `Use Proxy` - check this option if you want each request sends by Web Components first reach the dedicated module controller which forwards it to the FACT-Finder. **Note:** If you plan to use proxy, consider reading below paragraph as it requires full instruction how to enable it properly.
- `How to count single click on "Add to cart" button?` - select how would you like to count single click on "Add to cart" button
- `Send the SID as userId when user not logged in?`

#### Proxy

[](#proxy)

Proxy feature adds a oxid controller which serves as a middleware between Web Components and FACT-Finder®. The data flow with proxy enabled is illustrated by the graph below. [![Communication Overview](docs/assets/communication-overview.png "Communication Overview")](docs/assets/communication-overview.png)Having a middleware controller brings many possibilities to customize the request and the response. You can use `EnrichProxyDataEvent` to enrich data received from FACT-Finder. You can find more details about implementation [here](#enrich-data-received-from-fact-finder-in-proxycontroller). In addition, if forwarded request does not result with a correct response, you can implement fallback strategy, starting from this point.

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

To enable proxy you need to change your HTTP server configuration by adding rewrite rules. This is necessary because Web Components appends a URL parts to the base URL making it unreadable by the Oxid. This is because Oxid use query parameters `cl` and `fnc` to instantiate specific controller and execute its function. There is no routing that use url parts, hence any AJAX requests must target index.php file with the aforementioned parameters. Without these rules any request will lead to 404.

APACHE

```
    RewriteRule ^rest/v5/(.*)$ index.php?cl=search_result&fnc=proxy&$1 [L]
```

**Note:** Sending each request to FACT-Finder instance trough Shopware, you lose on performance as each request need to be handled first by HTTP server and then, by Shopware itself. This additional traffic could be easily avoided by not activating this feature if there's no clear reason to use it.

### Features Settings

[](#features-settings)

[![Features Settings](docs/assets/features-settings.png "Features settings")](docs/assets/features-settings.png)

- `Use FACT-Finder® for category pages?` - check this option to use Web Components in category pages. More information in separate paragraph.
- `Category Path field name` - by default, the module uses a field named `CategoryPath` (default category field name for FactFinder instance). If in your FactFinder instance configuration you have a different field name for Category field then you must set this name here.
- Campaigns - enables `ff-campaign-product` on product page and `ff-campaign-feedbacktext`, `ff-campaign-shopping-cart`on cart page
- Recommendations - enables `ff-recommendation` on product page
- Similar products - enables `ff-similar-products` on product page
- Pushed products - enables `ff-campaign-pushed-products>` on cart page

### Using FACT-Finder® on category pages

[](#using-fact-finder-on-category-pages)

Module in order to preserve categories URLs and hence SEO get use of standard Oxid routing with the combination of FACT-Finder® availability to pass custom parameters to search request. Once user lands on category page search event is emitted immediately.

### Feed Settings

[](#feed-settings)

[![Feed Settings](docs/assets/feed-settings.png "Feed settings")](docs/assets/feed-settings.png)This section allows setting attributes to export. If you want to export the attribute to separate column, choose it from the select input and set `Multi-Attribute` column value to `No`. if `Multi-Attribute` is set to `Yes`, the attribute is placed in an aggregate column `FilterAttributes`**Note:** Selection attributes are always placed in `FilterAttributes` automatically.

### Export Settings

[](#export-settings)

[![Export Settings](docs/assets/export-settings.png "Export settings")](docs/assets/export-settings.png)

Use following fields if you want to export feed file to your FTP server, where it could be then imported by FACT-Finder®.

- 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
--------------

[](#export-methods)

### HTTP Export

[](#http-export)

This method uses a specific URL under which the feed will be available. You can set FACT-Finder® to download the feed directly from this location:

```
[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:** Please keep in mind that the feed file is not directly available under the location. There is an export mechanism that does it on demand, so the whole process may take some time.

#### Basic Authentication

[](#basic-authentication)

Using [Export Settings](#export-settings) you can secure the HTTP export by setting up a Basic Authentication. Please remember that in this case you will need to include credentials in the URL, otherwise FACT-Finder® will not be able to download the feed file. You can include Basic Authentication credentials in URL using following syntax:

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

```

### FTP Export

[](#ftp-export)

With this approach, the exported feed file is uploaded to a specific FTP/SFTP server. Once the feed file is uploaded, FACT-Finder® is requested to begin an import based on uploaded file (optional). All settings related to this exporting method are found in [Export Settings](#export-settings). Fields Key and Key Passphrase are dedicated only to the SFTP. Field SSL Enabled is dedicated only to FTP.

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

#### Admin Panel Export

[](#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](#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

[](#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](docs/assets/languages.png "Languages")](docs/assets/languages.png)

Tracking
--------

[](#tracking)

Here you can find a full [Tracking Guide](https://web-components.fact-finder.de/documentation/4.x/tracking-guide). This module follows that guide in order to provide tracking of following events:

### Login

[](#login)

This event is tracked automatically by SDK.

### Click on Product

[](#click-on-product)

This event is tracked automatically by the `ff-record` element bindings. **Note:** for this to work a directive `data-redirect` has to be added

### Add Product to Cart

[](#add-product-to-cart)

We offer a `registerAddToCartListener` function which helps to register `click` events on form submit buttons. **Note:** Example usage can be found in `views/twig/extensions/themes/default/page/details/inc/productmain.html.twig`

### Place an Order

[](#place-an-order)

This event is tracked by the `ff-checkout-tracking` element which is implemented on order confirmation page

Modifications Examples
----------------------

[](#modifications-examples)

### Enrich data received from FACT-Finder

[](#enrich-data-received-from-fact-finder)

```
use Omikron\FactFinder\Oxid\Event\EnrichProxyDataEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class EnrichProxyDataEventSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [EnrichProxyDataEvent::class => 'enrichData'];
    }

    public function enrichData(EnrichProxyDataEvent $event): void
    {
        $data                 = $event->getData();
        $data['example_data'] = [
            'some_data'  => 'data_1',
            'next_data' => 'data_2',
        ];
        $event->setData($data);
    }
}
```

Contribute
----------

[](#contribute)

For more information, click [here](.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
-------

[](#license)

FACT-Finder® Web Components License. For more information see the [LICENSE](LICENSE) file.

###  Health Score

55

—

FairBetter than 97% of packages

Maintenance90

Actively maintained with recent releases

Popularity24

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity77

Established project with proven stability

 Bus Factor1

Top contributor holds 74.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~51 days

Recently: every ~137 days

Total

41

Last Release

51d ago

Major Versions

v3.1.1 → v4.1.22022-02-23

v3.1.2 → v4.2.02022-03-18

v3.1.3 → v4.2.12022-04-19

v4.4.3 → v5.0.02024-01-11

v5.1.0 → v6.0.02025-02-05

PHP version history (5 changes)v1.0.0PHP ^7.1

v4.0.0PHP ^7.2

v4.0.1PHP >=7.2

v3.1.0PHP >=7.1

v5.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/aace3f96144609268cdbdfc693d5cdd46de712260ec0837e500b4c0c5c6426db?d=identicon)[a-laurowski](/maintainers/a-laurowski)

---

Top Contributors

[![Rayn93](https://avatars.githubusercontent.com/u/12749730?v=4)](https://github.com/Rayn93 "Rayn93 (75 commits)")[![grzegorz-jamroz](https://avatars.githubusercontent.com/u/3972792?v=4)](https://github.com/grzegorz-jamroz "grzegorz-jamroz (14 commits)")[![paulfcdd](https://avatars.githubusercontent.com/u/11246832?v=4)](https://github.com/paulfcdd "paulfcdd (9 commits)")[![SvenBrunk](https://avatars.githubusercontent.com/u/4963144?v=4)](https://github.com/SvenBrunk "SvenBrunk (3 commits)")

---

Tags

fact-finderoxid-esalesoxid-eshopoxid-moduleweb-componentsOXIDmodulesweb componentseshopfact finder

###  Code Quality

TestsPHPUnit

Code StylePHP CS Fixer

### Embed Badge

![Health badge](/badges/omikron-oxid-factfinder/health.svg)

```
[![Health](https://phpackages.com/badges/omikron-oxid-factfinder/health.svg)](https://phpackages.com/packages/omikron-oxid-factfinder)
```

###  Alternatives

[ddoe/wysiwyg-editor-module

Summernote WYSIWYG Editor for OXID eShop.

191.0M5](/packages/ddoe-wysiwyg-editor-module)[oxid-esales/gdpr-optin-module

This is the GDPR opt-in module for the OXID eShop.

20473.8k3](/packages/oxid-esales-gdpr-optin-module)[oxid-professional-services/countryvatadministration

country vat administration

1733.8k](/packages/oxid-professional-services-countryvatadministration)[oxid-esales/geo-blocking-module

The module enables OXID eShop to be compliant with the EU geo-blocking regulations.

194.6k](/packages/oxid-esales-geo-blocking-module)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)