# omikron/magento2-factfinder

> FACTFinder Webcomponents SDK

`composer require omikron/magento2-factfinder`

Canonical URL: https://packagento.com/omikron/magento2-factfinder

## At a glance

- **Vendor**: omikron (https://packagento.com/omikron.md)
- **Latest version**: 5.3.0 — released 2026-05-26
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/omikron/magento2-factfinder and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require omikron/magento2-factfinder:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

FACTFinder Webcomponents SDK

## README

[![Packagist Version](https://img.shields.io/packagist/v/omikron/magento2-factfinder)](https://packagist.org/packages/omikron/magento2-factfinder)
[![Build status](https://github.com/FACT-Finder-Web-Components/magento2-module/workflows/build/badge.svg)](https://github.com/FACT-Finder-Web-Components/magento2-module/actions)
[![GitHub contributors](https://img.shields.io/github/contributors/FACT-Finder-Web-Components/magento2-module)](https://github.com/FACT-Finder-Web-Components/magento2-module/graphs/contributors)

This is a new version of SDK which support new WebComponents v5 NG.

This document helps you integrate the FACT-Finder Web Components SDK into your Magento 2 Shop. In addition, it gives a
concise overview of its primary functions. The first chapter *Installation* walks you through the suggested installation
processes. The second chapter “Backend Configuration” explains the customisation options in the Magento 2 backend. The
final chapter *Web Component Integration* describes how the web components interface with the shop system and how to
customise them. 

Our Magento 2 module offers a basic working integration for default Magento2 Luma 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
- [Requirements](#requirements)
- [Installation](#installation)
- [Activating the Module](#activating-the-module)
- [Backend Configuration](#backend-configuration)
    - [Main Settings](#main-settings)
        - [FACT-Finder version](#fact-finder-version)
        - [Server Side Rendering](#server-side-rendering)
    - [Advanced Settings](#advanced-settings)
        - [Currency and Country Settings](#currency-and-country-settings)
    - [Optional Custom Elements](#optional-custom-elements)
    - [Custom Elements Options](#custom-elements-options)
    - [Export Settings](#export-settings)
    - [CMS Export Settings](#cms-export-settings)
    - [Data Transfer Settings](#data-transfer-settings)
        - [Updating Field Roles](#updating-field-roles)
        - [Automatic Import](#automatic-import)
- [Data Export](#data-export)
    - [Feed Types](#feed-types)
    - [Integration Methods](#integration-methods)
        - [FTP Export](#ftp-export)
        - [HTTP Export](#http-export)
    - [Console Command](#console-command)
- [Web Component Integration](#web-component-integration)
    - [Searchbox Integration and Functions](#searchbox-integration-and-functions)
    - [Process of Data Transfer between Shop and FACT-Finder](#process-of-data-transfer-between-shop-and-fact-finder)
        - [Using Proxy](#using-proxy)
    - [Using FACT-Finder on category pages](#using-fact-finder-on-category-pages)
    - [Tracking](#tracking)
- [Modification examples](#modification-examples)
    - [Changing existing column names](#changing-existing-column-names)
    - [Adding new column](#adding-new-column)
        - [GenericField usage](#genericfield-usage)
    - [Adding custom product data provider](#adding-custom-product-data-provider)
    - [Configure field to be exported from variant](#configure-field-to-be-exported-from-variant)
- [Troubleshooting](#troubleshooting)
    - [Removing `/pub` from exported URLs](#removing-pub-from-exported-urls)
- [Contribute](#contribute)
- [License](#license)
    
### Requirements

This module supports:

- Magento 2 version 2.4.4 and higher
- PHP version 8.1 and higher

### Installation

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

    composer require omikron/magento2-factfinder

Optionally, you can specify a version constraint, e.g. `omikron/magento2-factfinder:^5.0`. Refer to Composer manual
for more information. If, for some reason, `composer` is not available globally, proceed to install it following the
instructions available on the [project website](https://getcomposer.org/doc/00-intro.md).

### Activating the Module

From the root of your Magento 2 installation, enter these commands in sequence:

    php bin/magento module:enable Omikron_Factfinder
    php bin/magento setup:upgrade

As a final step, check the module activation by running:

    php bin/magento module:status

The module should now appear in the upper list *List of enabled modules*.

Also, check in the Magento 2 backend "Stores → Configuration → Catalog → FACT-Finder" if the module output is activated.

![Module configuration](docs/assets/admin-section.png "Module configuration")

### Backend Configuration

Once the FACT-Finder module is activated, you can find the configurations page under "Stores → Configuration → Catalog → FACT-Finder". Here you can customise the connection to the FACT-Finder service. You can also activate and deactivate single web components, as well as access many additional settings.

#### Main Settings

At the top of the configurations page are the main settings. The information with which the shop connects to and authorises itself to the FACT-Finder Service are entered here. In the first line, activate your FACT-Finder integration. Before any changes become active, save them by clicking "Save Config".
In some cases, you need to manually empty the cache (System → Cache Management → Flush Magento Cache ).
Click the button "Test Connection" to check the connection to the FACT-Finder service.

**Note:** the **channel name, server URL and API key** need to be entered correctly to establish a connection.

Here you can also enable the rendering of category pages using FACT-Finder. More details can be found [here](#using-fact-finder-on-category-pages).

_(README truncated for .md surface. Full README on https://packagento.com/omikron/magento2-factfinder.)_

## Changelog

### [v5.3.0] - 2026.05.26
#### Add
- Add support for Magento v2.4.9
- Add support for PHP 8.4
- Add Recently viewed component

#### Update
- Update WebComponents library to version 5.2.1
- Add template to suggest element

### [v5.2.1] - 2025.07.17
#### Change
- Support tab navigation for search, suggest and paging components
- Improvements for European Accessibility Act (EAA)

#### Fix
- Cart tracking - parse price to float

#### Update
- Update WebComponents library to version 5.1.5

### [v5.2.0] - 2025.05.15
#### Add
- Add support for Magento v2.4.8

#### Update
- Update WebComponents library to version 5.1.2

#### Fix
- Add price attribute for ff-checkout-tracking-item
- Rewrite less files to support Magento v2.4.8

### [v5.1.1] - 2025.03.21
#### Fix
- Fix filter cloud issue on category pages

#### Update
- Update WebComponents library to version 5.1.1

### [v5.1.0] - 2025.02.20
#### Add
- Introduce Handlebars.js template engine instead of Mustache.js in SSR
- Implement Popular Searches
- Add `user-id` anonymization for tracking requests

#### Update
- Update WebComponents library to version 5.1.0

#### Fix
- Handle ClientException for SSR (invalid credentials, API issue etc.)
- Remove CategoryPath filter in URL and ASN on category page

### [v5.0.3] - 2025.01.20
#### Fix
- Set correct CategoryPath field name for searchParamsFromUrl

#### Update
- Update WebComponents library to version 5.0.0

### [v5.0.2] - 2024.12.08
#### Improve
- Add the ability to set a name for the CategoryPath field
- Do not redirect to result page if search execute already on results page

#### Update
- Update WebComponents library to version 5.0.0-pre.6

### [v5.0.1] - 2024.11.07
#### Update
- Update FactFinder logo
- Update WebComponents library to version 5.0.0-pre.4

#### Fix
- Support MSI - checking all inventory sources during export feed
- Fix feed path for UI export type
- Fix upload validation SSH key file issue
- Fix reset useId in WebComponents after user logout

### [v5.0.0] - 2024.07.08
#### BREAKING
- Upgrade FACT-Finder Web-Components to version 5.0.0-pre.1
- Drop support for FACT-Finder Web-Components v4
- Add support for PHP v8.2 and v8.3
- Upgrade magento libraries
- Upgrade composer dependencies
- Fix deprecations for magento/framework
- New SSR implementation for NG WebComponents
- Upgrade SDK to support Magento v2.4.7

#### Remove
- Remove SSR rendering delay time 

#### Fix
- Support MSI - checking all inventory sources for feed export

#### Add
- Add migration guide for upgrade WebComponents from v4 to v5

### [v4.3.0] - 2024.01.16
#### Add
- Add landing page campaign

### [v4.2.2] - 2023.11.10
#### Add
- Add campaigns to category view page
- Improve logging system

### [v4.2.1] - 2023.09.25
#### Fix
- Fix problem with ssr/record-list.phtml template

### [v4.2.0] - 2023.09.18
#### Add
- Add product campaign to product detail page
- Support redirect campaigns for SSR
#### Fix
- Fix displaying Fact-Finder campaigns for SSR
#### Change
- Upgrade Web Components version to v4.2.8

### [v4.1.7] - 2023.08.08
#### Fix
- Fix problems in factfinder_feed_export cron job by casting `storeid` to int.

### [v4.1.6] - 2023.07.19 
#### Fix
- Set default value for $pushImportResult to prevent initialization exception

### [v4.1.5] - 2023.07.05
#### Fix
- Fix sending sid for first session request (when SSR is active)

### [v4.1.4] - 2023.05.22
#### Fix
- Create one `ffwebc_sid` cookie per session
- Improve transfer `sid` param for SSR request
- Implement hooking into the pipeline for create `sid` cookie

### [v4.1.3] - 2023.05.15
#### Fix
- Add missing `sid` parameter for SSR FactFinder request
- Fix problem with export cron configuration
- Fix invalid return type for CLI export
- Fix problem with SFTP key auth connection
#### Change
- Upgrade Web Components version to v4.2.7

_(Changelog truncated for .md surface. Full history on https://packagento.com/omikron/magento2-factfinder.)_

## Recent Versions

| Version | Released |
|---|---|
| 5.3.0 | 2026-05-26 |
| 5.2.1 | 2025-07-17 |
| 5.2.0 | 2025-05-15 |
| 5.1.1 | 2025-03-21 |
| 5.1.0 | 2025-02-20 |
| 5.0.3 | 2025-01-20 |
| 5.0.2 | 2024-12-09 |
| 5.0.1 | 2024-11-07 |
| 4.4.0 | 2024-09-09 |
| 5.0.0 | 2024-07-08 |

Showing 10 of 97 versions. Full release history on https://packagento.com/omikron/magento2-factfinder.

## Dependencies

### Require

| Package | Constraint |
|---|---|
| ext-json | * |
| magento/framework | ^103.0.7 |
| magento/module-catalog | ^104.0.7 |
| magento/module-configurable-product | ^100.4.7 |
| magento/module-directory | ^100.4.7 |
| magento/module-inventory | 1.2.* |
| magento/module-store | ^101.1.7 |
| omikron/factfinder-communication-sdk | ^0.9.9 |
| php | ~8.1.0\|\|~8.2.0\|\|~8.3.0\|\|~8.4.0 |
| phpseclib/phpseclib | ~3.0 |
| salesforce/handlebars-php | 3.* |

### Require (dev)

| Package | Constraint |
|---|---|
| friendsofphp/php-cs-fixer | ^3.58 |
| magento/magento-coding-standard | * |
| pdepend/pdepend | ^2.16 |
| phpmd/phpmd | ^2.15 |
| phpunit/phpunit | ^9.6 |

## Quality

Latest release (5.3.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Pass | Pass | – | – |
| 2.4.8 | – | Pass | Pass | – |
| 2.4.9 | – | – | Pass | not tested |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 308 | 1 error, 307 warnings (ruleset: Magento2) — 9 auto-fixable with phpcbf |
| PHPMD | Warning | 8 | 8 rule violations (UnusedPrivateField:3, UnusedLocalVariable:1, MissingImport:1, UnusedPrivateMethod:1, ExcessiveMethodLength:1) |
| Cpd | Pass | 0 |  |
| Composer validate | Pass | 0 |  |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 34 | 34 | – | – |
| 2.4.8 | – | 35 | 35 | – |
| 2.4.9 | – | – | 34 | N/A |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 2 | 2 | – | – |
| 2.4.8 | – | 14 | not tested | – |
| 2.4.9 | – | – | 17 | not tested |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | Error | Error | – | – |
| 2.4.8 | – | Error | Error | – |
| 2.4.9 | – | – | Error | not tested |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["omikron/magento2-factfinder"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

omikron is a Magento 2 vendor on Packagento. See https://packagento.com/omikron.md for their full catalogue.