README

本文档帮助您将 FACT-Finder Web Components SDK 集成到您的 Magento 2 商店中。此外，它对其主要功能提供了一个简要概述。第一章安装指导您完成推荐的安装过程。第二章“后端配置”解释了 Magento 2 后端的定制选项。最后一章 Web 组件集成 描述了 Web 组件如何与商店系统交互以及如何定制它们。

要求

本模块支持

Magento 2 版本 2.4.4 及更高版本
PHP 版本 8.1 及更高版本

安装

要安装模块，请打开您的终端并运行以下命令

composer require omikron/magento2-factfinder

可选地，您可以指定版本约束，例如 omikron/magento2-factfinder:^1.3。有关更多信息，请参阅 Composer 手册。如果由于某些原因，composer 不可在全球范围内使用，请按照项目网站上的说明进行安装。

激活模块

从您的 Magento 2 安装根目录开始，依次输入以下命令

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

最后一步，通过运行以下命令检查模块激活

php bin/magento module:status

该模块现在应出现在上方的列表 已启用模块列表 中。

另外，请检查 Magento 2 后端 "商店 → 配置 → 高级 → 高级"，以确认模块输出已被激活。

后端配置

一旦 FACT-Finder 模块被激活，您可以在 "商店 → 配置 → 目录 → FACT-Finder" 下找到配置页面。在这里，您可以自定义与 FACT-Finder 服务的连接。您还可以激活和停用单个 Web 组件，以及访问许多其他设置。

主要设置

配置页面的顶部是主要设置。商店连接到并授权给 FACT-Finder 服务的详细信息在这里输入。在第一行，激活您的 FACT-Finder 集成。在更改生效之前，请通过点击 "保存配置" 保存它们。在某些情况下，您需要手动清空缓存（配置和 页面缓存）。点击 "测试连接" 按钮以检查与 FACT-Finder 服务的连接。

注意：需要正确输入渠道名称才能建立连接。

在这里，您还可以启用使用 FACT-Finder 渲染分类页面的功能。更多详细信息请参阅此处。

在“主要设置”部分末尾有一个选项 在搜索结果中显示'添加到购物车'按钮。激活此选项将在搜索结果页面上的产品旁边添加一个按钮，该按钮可直接将产品添加到购物车。此功能仅适用于简单产品。对于可配置产品，用户将被重定向到产品页面以选择特定产品变体。警告：添加到购物车的产品通过“MasterProductNumber”变量识别。为了使此功能正常工作，必须将“MasterProductNumber”字段导入 FACT-Finder 后端（在fact-finder.de）。

通过启用选项 激活日志记录，所有在与其他 FACT-Finder 服务器通信过程中抛出的异常都将保存在日志文件 var/log/factfinder.log 中。

注意：这是一个服务器端通信选项：Web Components 的行为不会受到影响。

FACT-Finder 版本

从版本 2 开始，该模块支持 7.3 和 NG。如果您使用的是较低版本，请安装NG 子模块

服务器端渲染

此选项启用分类页和搜索结果页上 ff-record-list 元素的服务器端渲染（SSR）。这意味着当用户导航到此类页面时，HTML 输出将包含预渲染的自定义元素。这对于 SEO 尤其有用，因为 ff-record-list 渲染的产品数据可能会对浏览器中的页面评级产生重大影响。如果没有启用 SSR，网络爬虫将无法扫描渲染内容，因为扫描时它尚未渲染。该模块使用 Mustache.php 库进行模板处理。

注意：有关 SSR 概念的更多信息，请参阅 Web Components 文档中的文章服务器端渲染。

注意：如果您在使用 SSR 时遇到 Fact-Finder 营销活动显示问题，请设置 SSR 组件的延迟时间。秒数取决于您的网站速度。

高级设置

高级设置包含用于 ff-communication Web 组件的附加参数。每个设置都设置为默认值，并附有简短的说明性文本。

货币和国家设置

您不需要设置货币或国家，仅针对模块用途。它将使用当前使用的货币，并将此信息作为 currency-code 和 country-code 参数传递给 ff-communication 组件。您可以在 Magento 通用设置下找到这些设置。

可选的自定义元素

我们提供的某些自定义元素仅在购买特定附加 FACT-Finder 模块时才能使用。在这里，如果您不使用此部分 FACT-Finder 功能，可以禁用它们。

注意：已添加分页，因为当在 ff-record 列表中启用无限滚动时，此自定义元素是多余的。

注意：着陆页营销活动的基础页 ID 基于 Magento CMS 页面标识符名称。

自定义元素选项

在此部分中，您可以找到特定自定义元素属性，您可以配置这些属性的值。此处存储的值传递到相应元素的模板中的特定位置。

导出设置

在本节中，用户可以决定属性是以单个字段导出还是分组到多属性字段中。将多属性设置为“否”会导致属性成为累积列FilterAttribute的一部分。将值设置为“是”会导致属性被导出到单独的列中。

属性导出适用于以下类型的属性

布尔值
价格
单选
多选
所有标量

数值属性

将多属性字段设置为数值，将导致该字段被导出到名为NumericalAttributes的单独多属性列。这将更容易在FACT-Finder中进行过滤配置。

注意：作为配置一部分的属性始终导出到FilterAttributes。

CMS 导出设置

您可以将您的CMS页面导出到FACT-Finder中，以在建议结果中展示它们。

页面黑名单 - 允许用户过滤掉不应导出的页面，例如“404未找到页面”不应在建议记录中可见

如果您想在项目中开始使用CMS导出，请联系分配给您的项目的人员或询问我们的服务中心。

注意：CMS导出仅通过控制台命令可用

数据传输设置

此选项配置了通过FTP/SFTP与FACT-Finder系统的连接。可以使用FTP/SFTP生成和传输商店数据到FACT-Finder。为了确保搜索等组件按预期工作，FACT-Finder需要产品数据是最新的。

对于FTP服务器，您可能需要指定用户名和密码。对于SFTP服务器，您可以使用两种认证方法：密钥或密码

注意 Magento上传器不允许没有扩展名的文件。如果您的密钥文件没有扩展名，请添加一个（例如 .rsa）注意如果密钥受保护，请勿忘记指定密钥密码

输入自动上传CSV文件的服务器。如果您不确定Magento能否连接到您的服务器，请使用“检查上传连接”选项。

CSV文件使用双引号"作为字段封装符，分号;作为字段分隔符。

选择附加属性选项提供了属性的复选列表。选择您想添加到CSV文件中的所有属性。

在点击现在生成导出文件开始导出之前，您需要通过点击“保存配置”来提交所有更改。例外情况是测试连接功能，它始终取对应字段的实际值。

更新字段角色

字段角色在创建新的渠道时分配，但可以随时更改。在这种情况下，您需要更新存储在Magento数据库中的用于跟踪的字段角色。要更新字段角色，请使用按钮更新字段角色

自动导入

一旦上传了（使用FTP导出）馈送文件，为了使FACT-Finder开始提供新数据，需要触发导入。模块允许您启用自动导入，这使得在馈送文件上传到FTP服务器后，FACT-Finder的导入将被触发。您还可以选择哪些数据类型应自动导入

数据（搜索）
建议这是一个多选字段，因此您可以同时选择它们

数据导出

在以下部分中，您将了解如何将您的馈送与FACT-Finder集成。无论选择哪种方法，馈送都是按相同的方式构建的，因此您可以从可能的方法中选择一种。

数据类型

模块能够导出以下类型的馈送之一

产品
CMS
类别

产品是 FACT-Finder 将用于生成您商店搜索结果的主要数据源。CMS 可以作为单独的搜索结果源使用（如果您在博客中拥有搜索功能），或用于丰富建议（如果您想根据用户搜索查询推荐相关博客文章）。类别用于通过添加类别 URL 类别到特定建议项来丰富建议。

集成方法

FTP 导出

此方法将数据源从商店系统导出并上传到 FTP 服务器。为了使用此导出方法，您需要配置 FTP 服务器（在《数据传输设置》部分中描述）。然后您可以点击下面的按钮（可见）来生成文件，然后通过 FTP 上传文件。

此按钮主要用于临时导出。在生产环境中，您更可能使用 Cron 作业，它将执行相同的工作，而无需每次您想要将新数据发送到 FACT-Finder 时都强制您点击导出按钮。要配置 Cron，请激活“自动生成导出文件”选项，并且导出将在每天凌晨 01:00 服务器时间生成。

在 crontab.xml 文件中，您可以看到一个表达式 <schedule>0 1 * * *</schedule>，这是默认值，但您可以在模块配置（下面可见的部分）中定义自己的 cron 表达式。这里设置的值将覆盖默认的 crontab 配置。请记住，此设置仅针对在 Magento 监督器下运行的具体任务。如果没有配置系统 Cron，则此设置不会工作。为此，您需要将 Magento Cron 入口点添加到您的系统 crontab 文件中。有关更多信息，请参阅本教程。

HTTP 导出

另一种集成您的数据源的方法是使用 FACT-Finder 内置功能定期从特定 URL 下载数据源，该 URL 可访问数据源。此 URL 应通过基本认证（在《数据传输设置》部分中配置的用户名和密码）进行保护，以确保只有经过认证的用户才能访问。如果您不安全地使此 URL，则实际上是允许任何人下载您的数据源！

导出在以下位置可用：https://YOUR_SHOP_URL/factfinder/export/product/store/YOUR_STORE_ID

如果没有提供 store id，则将使用默认商店生成数据源（默认情况下 ID 为 1）

您应在 FACT-Finder UI 中提供此 URL

控制台命令

如果您是开发人员并且想测试是否正确生成了数据源或您不想执行 magento cron，则可以使用内置在 Magento2 中的 Symfony Console 组件实现的控制台命令。命令名称：factfinder:export [TYPE]。您可以将此命令的执行添加到您的 crontab 文件中。

参数
- type（必填）- 设置用于导出数据的 FeedFactory 类的数据类型。如果对于给定的类型不存在数据提供程序，则会抛出异常。可能的默认值是 product 和 cms。
选项（所有选项都是可选的）
- store - 定义从其中获取产品数据的商店
- skip-ftp-upload - 跳过 ftp 上传
- skip-push-import - 跳过触发导入

Web 组件集成

您可以从 Magento 2 后台的配置页面激活和停用任何 Web 组件。

Web 组件的 HTML 代码可以在此文件夹中找到

src/view/frontend/templates/ff

模块样式可以在此文件夹中找到

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

由于 Magento 2 使用 Less，所有源样式都编写在此样式表语言中

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

您可以将模板集成到您的商店系统中的任何位置。推荐的方式是使用Magento2布局。例如，此SDK中的ff-suggest元素被集成到ff-searchbox模板中。

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

您也可以使用Magento布局API在模板中实例化块，但这不是推荐的方式。

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

通信元素

Web Components的主要配置元素ff-communication元素包含在模板src/view/frontend/templates/ff/communication.phtml中，该模板与专门的视图模型src/ViewModel/Communication.php一起提供。该模板是default布局的一部分，添加到after.body.start容器中。它是整个模块正常工作的关键，因此请确保它也被包含在您的项目中。

注意：避免同时覆盖模板和视图模型。

搜索框集成和功能

一旦在配置中激活了FACT-Finder集成，搜索框Web组件将自动激活。它将替换您的标准搜索。

您可以在以下位置找到FACT-Finder搜索的模板：

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

一旦您执行搜索，您将自动被重定向到新的改进的Magento 2搜索结果页面，该页面与FACT-Finder数据一起工作。此外，FACT-Finder还会在新搜索结果页面的URL中添加相关数据，如搜索的FACT-Finder通道或搜索查询字符串。模块的源代码包含在XML文件中的搜索结果布局定义

src/view/frontend/layout/factfinder_result_index.xml

该布局已集成了几个模板，其中包括显示搜索结果的ff-record-list。

商店与 FACT-Finder 之间数据传输的过程

默认情况下，搜索/建议请求会直接发送到FACT-Finder，绕过Magento后端。但是，如果出于某种原因，您想修改请求参数或在返回之前修改响应，您可以启用代理。

使用代理

启用此功能后，一旦发送搜索查询，它不会立即到达FACT-Finder，而是转交给特定的控制器

src/Controller/Proxy/Call.php

该控制器将请求交给FACT-Finder系统，接收答案，处理它，然后再将其返回到前端/web组件。您可以使用Magento拦截器机制添加afterExecute插件来丰富从FACT-Finder接收到的数据。

注意：通过Magento将每个请求发送到FACT-Finder实例，您会失去性能，因为每个请求都需要先由HTTP服务器处理，然后由Magento本身处理。如果没有任何明确的原因使用此功能，可以轻松避免这种额外的流量，不激活此功能。

在分类页面使用 FACT-Finder

该模块使用标准的Magento路由与FACT-Finder可用性的组合来保留分类URL和SEO，为搜索请求传递自定义参数。一旦用户到达分类页面，搜索请求就会立即执行（归功于使用search-immediate通信参数）。要启用此功能，请在主设置部分中打开相应的选项。

跟踪

该模块使用Web Components API跟踪以下事件：

点击产品
将产品添加到购物车
下订单
用户登录

要追踪产品点击，请确保您的记录模板使用了追踪指南中描述的data-redirect指令。添加到购物车是通过在src/view/frontend/web/js/catalog-add-to-cart-mixin.js:28脚本中使用WEB组件API来追踪的。为了使其正常工作，请确保您使用的是基本的catalog-add-to-cart.js，否则混合效果将不会应用。结账追踪是通过ff-checkout-tracking元素完成的。该元素在src/view/frontend/templates/ff/checkout-tracking.phtml中添加，该模板扩展了checkout_onepage_success布局。如果您在结账时没有使用此布局，请确保将其附加到您自己的布局中。为此，您可以使用视图模型src/ViewModel/Order.php，该模型从后端提供所有必要的数据到模板。登录追踪是通过额外的CustomerData部分ffcommunication完成的。此部分应在src/etc/frontend/sections.xml中进行配置，并应响应用户登录动作，并在之后重新加载包含的数据。

修改示例

我们的Magento 2模块提供了开箱即用的完整集成。然而，大多数项目可能需要修改以满足其需求。以下是一些常见的定制示例。

更改现有列名

该模块在主DI配置etc/di.xml中定义了预定义的列名。这些遵循我们的最佳实践。默认的数据提供程序配置为导出具有相同名称的列的数据，因此要更改列名，您需要添加两个修改。

在您的自定义模块di.xml中定义新列名。以下代码片段显示了如何更改主产品编号（在名为Master的模块中）的名称。

<virtualType name="Omikron\Factfinder\Model\Export\CatalogFeed">
    <arguments>
        <argument name="columns" xsi:type="array">
            <item name="Master" xsi:type="string">CUSTOM_NAME</item>
        </argument>
    </arguments>
</virtualType>

一旦在di.xml中更改了列名，请向数据提供程序添加一个插件，并用新名称替换标准名称。请记住，您不需要复制其余元素。它们不会被删除，因为DI配置加载机制将所有定义合并为单个输出。示例实现

<type name="Omikron\Factfinder\Model\Export\Catalog\ProductType\SimpleDataProvider">
    <plugin name="custom-provider" type="YOUR_VENDOR\YOUR_MODULE\Plugin\AfterToArrayPlugin" />
</type>

public function afterToArray($subject, $result)
{
    return ['CUSTOM_NAME' => $result['Master']] + $result;
}

最后，运行bin/magento cache:clean config以替换您刚刚创建的旧DI配置。

添加新列

标准数据包包含FACT-Finder®工作所需的所有数据。然而，您可能想要导出与项目相关的附加信息，这些信息不是默认的Magento 2安装的一部分。为了做到这一点，让我们看一下FieldProvider定义。

<type name="Omikron\Factfinder\Model\Export\Catalog\FieldProvider">
    <arguments>
        <argument name="productFields" xsi:type="array">
            <item name="ImageURL" xsi:type="object">Omikron\Factfinder\Model\Export\Catalog\ProductField\ProductImage</item>
            <item name="CategoryPath" xsi:type="object">Omikron\Factfinder\Model\Export\Catalog\ProductField\CategoryPath</item>
            <item name="Attributes" xsi:type="object">Omikron\Factfinder\Model\Export\Catalog\ProductField\Attributes</item>
        </argument>
    </arguments>
</type>

构造函数参数productFields存储了需要比仅从产品检索数据更复杂逻辑的字段引用。假设我们想要添加一个包含图像URL的新列BrandLogo。在您的模块DI中，以添加默认的方式添加新字段定义。

同样，没有必要复制所有其他字段定义：Magento将合并现有的列与您刚刚添加的列。为了让您的字段导出器正常工作，它必须实现Omikron\Factfinder\Api\Export\FieldInterface。导出品牌标志的类骨架可能如下所示

class BrandLogo implements \Omikron\Factfinder\Api\Export\FieldInterface
{
    public function getValue(Product $product): string
    {
        // Getting products brand logo URL...
    }
}

最后，您需要在di.xml中的目录数据包定义中定义新列。

<virtualType name="Omikron\Factfinder\Model\Export\CatalogFeed">
    <arguments>
        <argument name="columns" xsi:type="array">
            <item name="BrandLogo" xsi:type="string">BrandLogo</item>
        </argument>
    </arguments>
</virtualType>

GenericField 使用

如果提取逻辑只是从产品中检索属性值而不进行任何进一步的数据转换，可以使用GenericField的虚拟类型，而不是实现FieldInterface。此类的构造函数只需要一个要导出的属性代码。

<virtualType name="Omikron\Factfinder\Model\Export\Catalog\ProductField\Brand" type="Omikron\Factfinder\Model\Export\Catalog\ProductField\GenericField">
    <arguments>
        <argument name="attributeCode" xsi:type="string">manufacturer</argument>
    </arguments>
</virtualType>

现在运行bin/magento cache:clean config以使用新的DI配置。

添加自定义通信参数

模块配置允许您将常量值传递给每个参数，但是有时您可能需要提供变量值，即依赖于当前登录的客户。为了做到这一点，您应该创建自定义参数提供者。

class CustomAddParams implements \Omikron\Factfinder\Api\Config\ParametersSourceInterface
{
       public function getParameters(): array
       {
           return [
               'add-params'  => $this->getMyVariableParameters(),
           ];
       }
}

所有注册的参数提供者都会在循环中执行，其结果将存储在关联数组中，最后将传递到前端。

请注意，在此执行级别上，每当参数提供者返回一个已在结果数组中存在的键的值时，参数将被覆盖。通过使用Magento依赖注入机制，从项目级别添加的参数提供者将在最后评估，但如果你想添加多个，你需要保持它们的顺序。在以下示例中，如果CustomProviderFirst和CustomProviderSecond提供的参数数组在给定键上有交集，则结果将返回CustomProviderSecond的值。

    <type name="Omikron\Factfinder\Model\Config\CommunicationParametersProvider">
        <arguments>
            <argument name="parametersSource" xsi:type="array">
                <item name="first" xsi:type="object">YOUR_VENDOR\YOUR_MODULE\Model\Config\CustomProviderFirst</item>
                <item name="second" xsi:type="object">YOUR_VENDOR\YOUR_MODULE\Model\Config\CustomProviderSecond</item>
            </argument>
        </arguments>
    </type>

添加自定义产品数据提供者

如果你需要定义新的产品类型，并且其数据不能由任何现有的数据提供者提供，你应该创建一个自定义数据提供者并将其映射到你的产品类型。此操作与之前的操作一样，可通过Magento DI机制实现。在你的模块DI中添加以下xml代码

    <type name="Omikron\Factfinder\Model\Export\Catalog\DataProvider">
        <arguments>
            <argument name="entityTypes" xsi:type="array">
                <item name="customProductType" xsi:type="string">YOUR_VENDOR\YOUR_MODULE\Model\Export\Catalog\ProductType\CustomDataProvider</item>
            </argument>
        </arguments>
    </type>

<?php
class CustomDataProvider implements DataProviderInterface
{
    /** @var Product */
    protected $product;

    public function __construct(Product $product)
    {
        $this->product = $product;
    }

    /**
     * @inheritdoc
     */
    public function getEntities(): iterable
    {
        // Your logic
    }
}

这是一个最小配置。$product构造函数将被自动传递，在getEntities方法中，你应该提取所有所需的数据

配置从变体导出的字段

默认情况下，模块从可配置产品导出数据。它的变体只覆盖了你在类中可以看到的少数字段

src/Model/Export/Catalog/Entity/ProductVariation.php

这是为了提供最佳性能，但如果你的变体在某些属性（如颜色、尺寸等）上有所不同，你可以配置应该从变体中导出的字段。使用variantFields参数来配置。以下是模块中的示例，我们想从变体中导出ImageURL，因为某些可配置属性可能会影响产品外观（颜色是一个很好的例子）。

<type name="Omikron\Factfinder\Model\Export\Catalog\FieldProvider">
    <arguments>
        <argument name="productFields" xsi:type="array">
            <item name="CategoryPath" xsi:type="object">Omikron\Factfinder\Model\Export\Catalog\ProductField\CategoryPath</item>
            <item name="Brand" xsi:type="object">Omikron\Factfinder\Model\Export\Catalog\ProductField\Brand</item>
            <item name="FilterAttributes" xsi:type="object">Omikron\Factfinder\Model\Export\Catalog\ProductField\FilterAttributes</item>
        </argument>
        <argument name="variantFields" xsi:type="array">
            <item name="ImageURL" xsi:type="object">Omikron\Factfinder\Model\Export\Catalog\ProductField\ProductImage</item>
        </argument>
    </arguments>
</type>

故障排除

从导出 URL 中删除 `/pub`

如果导出的数据文件包含带有pub/的URL，那么你的文档根很可能被设置为/pub文件夹。为了在URL中跳过这部分，请将以下条目添加到你的项目的env.php文件中

'directories' => [
    'document_root_is_pub' => true
],

贡献

更多信息，请点击这里

你也可以在发现错误或只是对模块改进有想法时打开一个新问题。要检查目前打开的问题，请点击这里。

许可

FACT-Finder® Web Components许可证。有关更多信息，请参阅LICENSE文件。

omikron / magento2-factfinder

维护者

详细信息