README

本文档帮助您将 FACT-Finder® Web 组件 SDK 集成到您的 Shopware 商店中。此外，它对其主要功能提供了一个简要概述。第一章节安装带您了解建议的安装过程。第二章节设置解释了 Shopware 后端中的自定义选项。最后一章 导出数据 描述了如何使用提供的控制台命令导出数据。

我们的 Shopware 插件为默认 Shopware Storefront 主题提供了一个基本的工作集成。大多数项目可能需要修改才能满足其需求。有关更多高级功能，请查看我们的官方 WebComponnents 文档。

系统要求
FACT-Finder® 支持的分区
安装
激活模块
主要设置
- 更新字段角色
导出设置
- 价格列格式
上传设置
导入设置
分类页面
导出数据
Web 组件集成
修改示例
贡献
许可

系统要求

Shopware 6.4
PHP 版本 7.4 或更高

注意：如果您使用 Shopware 6.5，请使用 SDK 版本 5.x: https://github.com/FACT-Finder-Web-Components/shopware6-plugin/tree/release/5.x

注意：对于 Shopware 6.6，请使用 Shopware 市场版本：https://store.shopware.com/en/factf26713613196f/factfinder-ai-powered-search-product-discovery.html

FACT-Finder® 支持的分区

安装

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

composer require omikron/shopware6-factfinder

安装成功后，它将显示在扩展列表中。根据 Shopware 6 的版本，视图可能会有所不同。

注意：插件只能通过 composer 安装，直接将插件源代码解压到 Shopware 6 项目目录中不会工作，因为插件包含外部依赖项，这些依赖项也需要安装。

激活模块

要激活模块，请使用位于扩展信息行左侧的开关。安装后，其配置可以在三个点图标下找到。所有部分将在以下段落中介绍。

主要设置

本节包含插件配置，这是模块正常运行所必需的。所有字段均有注释说明。此处设置的配置同时用于Web组件和与FACT-Finder®实例的服务器端通信。您将获得的凭据应放置于此。请记住，您必须清除商店缓存，以便新应用的配置开始工作。

服务器URL - FACT-Finder®实例URL
注意：服务器URL应包含使用的协议：（例如 https://）并应以端点结尾（ fact-finder ）
渠道 - 您想从中提供数据的服务渠道
用户名
密码
API版本 - 使用FACT-Finder® API版本
注意：模块支持FACT-Finder® API版本 v4 和 v5。选择错误的API版本可能导致Web组件无法与FACT-Finder®通信

您可以通过点击测试连接按钮来检查上述数据是否设置正确。请在点击按钮之前保存您的设置。

更新字段角色

此功能提供了一种下载在FACT-Finder®中配置的字段角色的方法。如果您不使用插件提供的feed或者由于某些原因更改了列名，请使用此功能。您可以在（Web组件文档）[https://web-components.fact-finder.de/documentation/4.x/field-roles] 中找到有关字段角色更多信息 注意：更新过程将为所有销售渠道运行，无需为每个渠道单独运行

服务器端渲染

此选项为类别和搜索结果页面上的ff-record-list元素启用服务器端渲染（SSR）。这意味着当用户导航到上述类型的页面时，HTML输出将包含预渲染的自定义元素。这对于SEO特别有用，因为ff-record-list渲染的产品数据可能会对浏览器页面评级产生很大影响。如果没有启用SSR，网络爬虫将无法扫描渲染内容，因为扫描时它尚未渲染。

注意：您可以在Web组件文档中的文章服务器端渲染 [ https://web-components.fact-finder.de/documentation/4.x/server-side-rendering ] 中找到有关SSR概念的更多信息。

高级设置

本节包含一个可选的插件配置，它提供额外的功能。

使用代理？ - 启用此功能后，一旦发送搜索查询，它不会立即到达FACT-Finder，而是传递给特定的控制器 src/Storefront/Controller/ProxyController.php，该控制器将请求传递给FACT-Finder系统，接收答案，处理它，然后将其返回到前端视图。您可以使用EnrichProxyDataEvent来丰富从FACT-Finder接收到的数据。您可以在此处找到有关实现的更多详细信息。

注意：通过Shopware向FACT-Finder实例发送每个请求，您将失去性能，因为每个请求都需要首先由HTTP服务器处理，然后由Shopware本身处理。如果没有任何明确的原因使用该功能，可以通过不激活此功能来轻松避免这种额外的流量。
如何计算“添加到购物车”按钮的单次点击场景
为所选查询设置重定向映射 - 将每个查询=url对放在单独的一行中。如果短语出现两次，则取列表顶部的第一个。URL可以是相对路径 /some/page 或绝对URL https://domain.com/some/page?someParameter=1。如果提供的对具有无效格式，则将其忽略。

导出设置

选择应忽略的筛选属性 - 在此处选择的产品属性将不会导出。默认情况下，所有属性都会被导出。注意：配置部分的产品属性将忽略这些设置。
选择应忽略的自定义字段 - 在此处选择的自定义字段将不会导出。默认情况下，所有自定义字段都会被导出。
导出所有货币的价格 - 如果禁用，则导出将仅包含一个价格列。如果启用，则所有产品价格将以给定销售渠道配置的所有货币导出。
启用导出缓存 - 如果启用，则导出时间会更短。该选项与店面展示相关联 - 这意味着每个产品列表都将被缓存。在构建缓存期间，将触发FeedPreprocessorEntryBeforeCreate事件，因此如果您想要缓存一些额外的数据，您可以轻松地挂钩。有关实现的更多详细信息，请参阅此处。

注意：当启用导出缓存时

如果缓存数据为空，则 - 我们正在构建新的导出缓存并将其存储在factfinder_feed_preprocessor数据库表中
如果缓存数据已存在，则它将使用缓存数据来准备导出
如果某些产品数据发生变化，则 - 在产品保存后，将自动重建此记录的缓存
如果需要重建整个缓存，则可以使用命令

php [SHOPWARE_ROOT]/bin/console factfinder:data:pre-process

价格列格式

如果将导出所有货币的价格设置设置为true，则价格列将以以下模式导出 Price_[货币ISO代码]，例如 Price_De

上传设置

以下设置用于将已导出的馈送到给定的FTP/SFTP服务器上传。

注意：默认端口设置是21。如果您的服务器在不同的端口上监听，请相应地更改它。

协议
服务器URL
端口
用户名
密码
根目录
私钥内容
密码短语

您可以通过单击测试FTP/SFTP连接按钮来检查上述数据是否设置正确。请单击按钮之前保存您的设置。

注意字段“私钥内容”和“密码短语”是可选的。仅在SFTP服务器需要此认证方法时使用它们。

导入设置

为 - 定义应触发的导入类型。可能的类型有：建议、搜索和推荐

分类页面

注意：此功能是实验性的，并且它很可能在不久的将来将进行重大修改。

插件提供了一种方法，使用页面构建器购物体验在分类页面上使用FACT-Finder® Web Components。提供了两个CMS块

列表
- ff-record-list
- ff-asn + 包括 ff-filter-cloud
- ff-pagination
- ff-sortbox
活动
- ff-campaign-feedbacktext
- ff-campaign-advisor
- ff-campaign-redirect
- ff-campaign-pushed-products

提供的Cms块和元素是为LandingPage类型的页面设计的。存在一个CategoryPage类型，但内置验证不允许保存该准备好的页面，除非它至少包含一个默认的产品列表块。遗憾的是，FACTFinder Web Components 列表块没有被考虑。

所有元素都在Commerce类别下可用

元素设置

给定块中的每个元素都包含专门的配置，允许在不必要在模板中添加硬编码值的情况下进行配置。

如果您不想渲染特定元素，只需将subscribe选项更改为false。这将使元素不会订阅到FACT-Finder®响应，因此它们将不会渲染任何HTML。

ASN 元素

订阅 - 激活元素
垂直 - 如果设置为true，则将btn-block CSS类添加到ff-asn-group，并将ff-asn的align属性设置为`vertical`。
ID - 元素标识符。如果为空，则使用CMS元素ID。
主题 - 元素订阅的主题。如果为空，则元素订阅到默认的asn主题。
回调参数 - 持有适合元素的FACT-Finder响应数据的变量名称。它将在回调范围内可见。
回调 - 允许操作接收到的函数。此数据在回调参数中可用。
Dom 更新 - dom-updated事件的监听器。此事件在渲染其HTML模板时触发。

记录列表元素

订阅 - 激活元素
无限滚动 - 向ff-record-list元素添加inifinity-scrolling属性。
无限防抖延迟 - 向ff-record-list元素添加infinite-debounce-delay属性。
ID - 元素标识符。如果为空，则使用CMS元素ID。
回调参数 - 适合元素的FACT-Finder响应数据的变量名称。它将在回调范围内可见。
回调 - 允许操作接收到的函数。此数据在回调参数中可用。
Dom 更新 - dom-updated事件的监听器。此事件在渲染其HTML模板时触发。

活动元素

顾问活动 - 渲染ff-campaign-advisor元素。
顾问活动名称 - 向ff-campaign-advisor添加label属性。
反馈活动 - 渲染ff-campaign-feedbacktext元素。
反馈活动标签 - 将活动元素绑定到具有给定标签的FACT-Finder活动，使其仅对其做出反应。
反馈活动标志 - 设置标志使活动元素对特定类型的FACT-Finder活动做出反应。
反馈活动 - 渲染ff-campaign-feedbacktext元素。
顾问活动名称 - 向ff-campaign-feedbacktext添加label属性。
重定向活动 - 渲染ff-campaign-redirect元素。
推送产品 - 渲染ff-campaign-pushed-products元素。
推送产品标志 - 设置标志使活动元素对特定类型的FACT-Finder活动做出反应。

注意：您可以在Web Components的文档中找到有关相关活动元素及其配置的更多信息。

块和元素模板

每个块和元素都有自己的模板，可以根据Shopware 6约定找到

对于块 - Resources/views/storefront/block
对于元素 - Resources/views/storefront/element，可以使用Shopware sw_extends标签进行扩展。

将布局分配给分类

页面布局完成后，您需要将布局分配给选定的类别。

我们强烈建议不要创建太多布局，因为目前提供的可能性仍然有限。未来的开发将带来更多的块和元素。

导出数据

FACT-Finder 允许导出不同类型的馈送，如产品、CMS 和品牌（或制造商）

您还可以在 services.xml 文件中的 factfinder.data_export.entity_type_map 参数中定义自己的数据类型以导出

馈送可以以两种方式导出：使用管理面板（www.yourhost.com/admin#/ui/feed/export/index）或使用 CLI

CLI

馈送导出在 Shopware CLI 应用程序中可用。您可以通过执行以下命令来运行它

php [SHOPWARE_ROOT]/bin/console factfinder:data:export

并遵循控制台中的说明。

如果您想在不交互模式下运行命令，请使用 -n 选项输入命令

php [SHOPWARE_ROOT]/bin/console factfinder:data:export -n

此命令可以与一个可选的参数一起运行，该参数指示您要针对的销售渠道 ID。ID 是字符串值。

php [SHOPWARE_ROOT]/bin/console factfinder:data:export -n SALES_CHANNEL_ID

如果需要指定特定的语言，还有一个第二个参数可以实现这一点。

php [SHOPWARE_ROOT]/bin/console factfinder:data:export -n SALES_CHANNEL_ID LANGUGAGE_ID

除了 -n 之外，还有两个附加选项

-u 在生成馈送后将馈送上传到配置的 FTP 服务器。
-i 使用先前上传的馈送运行 FACT-Finder® 导入
注意： 此选项仅与 -u 结合使用时才有效

默认情况下，导出输出数据到 STDOUT。可以很容易地使用 Linux 的输出重定向方式来重定向。

php [SHOPWARE_ROOT]/bin/console factfinder:data:export -n > export.csv

选择 CMS 导出的分类

在 CMS 导出中，我们通过为 CategoryEntity 引入自定义字段来过滤要导出的类别。您可以在类别编辑页面上找到它。

从管理面板导出

有一种可能运行整个集成：生成馈送，将其上传到 FTP 服务器并触发 FACT-Finder® 导入。可以在 扩展 部分下找到专用表单

选择字段允许您选择要运行的集成销售渠道和语言参数。选择导出类型为您提供创建 Shopware 实例中可用数据不同内容的可能性。可以导出

产品
品牌
CMS
类别

创建导出 向总线发送消息，然后管理员工作者（如果已启用）或 CLI 工作者可能会自动消费该消息。有关消息的更多信息，请参阅官方 Shopware 文档

如果您使用导出缓存功能（了解更多），您还可以通过点击 刷新缓存导出 按钮刷新您的导出缓存。此功能在以下情况下很有用：

您的导出缓存过旧或不完整
您以编程方式对数据库进行了更改
您想减少导出时间（使用缓存导出更快）

Web 组件集成

注意：请注意，插件目前仅支持使用 Twig 模板系统渲染的经典店面。

Web 组件文档

完整的 FACT-Finder® Web Components 文档可以在这里找到

包含脚本

该模块附带包含 FACT-Finder® Web Components 的脚本。包括脚本步骤已在该模块中实现。无需采取任何额外操作。

Resources/public/ff-web-components/vendor/custom-elements-es5-adapter.js
Resources/public/ff-web-components/vendor/webcomponents-loader.js
Resources/public/ff-web-components/ff-web-components/bundle.js

所有这些文件都包含在 Resources/views/storefront/layout/meta.html.twig 中。该文件扩展了默认主题 meta.html.twig 。注意：包括这些脚本对于 Web Components 的工作是必需的。请确保您包括它，或者如果您的店面不使用该文件，请按照所述顺序在自己的店面中包含所有脚本。

通信

主要配置元素 ff-communication 已添加到文件 src/Resources/views/storefront/base.html.twig 中。与 meta.twig.html 一样，它扩展了默认 Storefront 中定义的 base.html.twig 文件。此元素会自动填充模块配置中配置的数据。

注意：如果您的主题没有扩展默认 Storefront，请确保您实现了 ff-communication 元素，因为它必不可少，并且没有它 FACT-Finder® Web Components 将无法工作。

模板

插件模板可以在 Resources/views/storefront/ 中找到。与前面的部分一样，所有模板都尽可能扩展默认 Storefront。如果您使用 sw_extends 扩展它，可以使用这些模板，它提供了对多继承的支持。

跟踪

插件提供以下跟踪客户行为的方式

登录 - 当设置 user-id 时，通过 ff-communication 元素自动登录
点击产品 - 使用 ff-record 模板指令实现（参见点击跟踪）
添加到购物车 - 在 js 插件中实现
购买 - 使用 ff-checkout-tracking 元素实现（参见结账跟踪）

已实现的 Web 组件完整列表

插件实现了给定的 Web Components 列表

页面标题
- ff-communication
- ff-searchbox
- ff-suggest
搜索结果和导航页面
- ff-record-list
- ff-asn
- ff-sortbox
- ff-paging
- ff-filter-cloud
- ff-campaign-advisor
- ff-campaign-feedbacktext
- ff-campaign-redirect
产品详情页面
- ff-campaign-product
- ff-campaign-pushed-products
- ff-recommendation
- ff-similar-products
结账成功页面
- ff-checkout-tracking

修改示例

向数据添加新列

标准数据源包含FACT-Finder®运行所需的所有数据。然而，您可能希望导出与您的项目相关但不是默认Shopware安装部分的信息。本节将向您展示如何通过添加额外的列来扩展数据源。

首先创建字段提供者 - 一个实现Omikron\FactFinder\Shopware6\Export\FieldInterface的类，该类将用于导出您的数据。

use Shopware\Core\Framework\DataAbstractionLayer\Entity;

interface FieldInterface
{
    public function getName(): string;

    public function getValue(Entity $entity): string;
    
    public function getCompatibleEntityTypes(): array;
}

getName方法包含字段应导出的列名，getValue方法包含您的字段逻辑并接收当前正在导出的文章详情。getCompatibleEntityTypes方法包含一个Shopware实体类数组，其中可以应用给定的字段。

use Omikron\FactFinder\Shopware6\Export\Data\Entity\ProductEntity;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;

class CustomColumn implements FieldInterface
{
     public function getName(): string
     {
        return 'MyColumnName'; // Will be used as column header in the CSV feed
     }

    public function getValue(Entity $entity): string
    {
        // Implement logic to fetch and transform data for a given article detail  
    }
    
    public function getCompatibleEntityTypes(): array
    {
        return [ProductEntity::class];
    }
}

一旦定义了您的额外列，请使用Symfony DI（您可以在此处找到更多信息）将其注册为服务，并将它们设置为自动配置。通过这样做，您的字段将被标记为factfinder.export.field并可以自动检索。当然，自动配置只是我们提供的一种便利，您仍然可以手动将标记分配给服务。

导出存储在变体中的字段

默认情况下，仅从变体中导出以下字段：* 自定义字段 * 图片URL。如果您的设置需要从变体中导出更多字段，您需要在services.xml文件中为所需字段标记factfinder.export.variant_field。

//src/Resources/config/services.xml:100
<service id="Omikron\FactFinder\Shopware6\Export\Field\CustomFields">
    <tag name="factfinder.export.variant_field"/>
</service>

但是，从变体中导出数据可能需要在数据检索期间进行额外的连接。为了定义自定义关联（连接），请在该参数下设置它们。

//src/Resources/config/services.xml:39
<parameter key="factfinder.export.associations" type="collection">
    <parameter key="variant_cover">children.cover</parameter>
</parameter>

该集合中的所有参数都将用于后续的表达式中

$criteria->addAssociation($association);

其中$association在该示例中将是children.cover。

注意：请注意，添加越来越多的关联将对整体导出性能产生影响。

创建自定义实体导出

插件提供了一种灵活的导出机制，可以指定与不同类型的实体一起使用。在当前插件状态下，它允许导出三种类型的实体

销售渠道产品实体
分类实体
产品制造商实体

您可以通过提供至少三个类来扩展基本实体。为了做到这一点，您需要提供以下内容

实现Omikron\FactFinder\Shopware6\Export\ExportInterface的实现，该实现负责导出Shopware实体
实现Omikron\FactFinder\Shopware6\Export\Data\ExportEntityInterface，它是在导出形式中表示Shopware实体的表示形式。
实现Omikron\FactFinder\Shopware6\Export\Data\Factory\FactoryInterface，它负责产生上述可导出实体

通用实体工厂

如果您的实体不需要自定义逻辑来产生（例如，如果产品实体工厂还产生可变实体，如果产品可以配置属性），则不需要为它创建新的工厂。它将由Omikron\FactFinder\Shopware6\Export\Data\Factory\GenericEntityFactory处理。

注意：我们考虑实体为扩展Shopware\Core\Framework\DataAbstractionLayer\Entity类的类。

如果某些字段需要更复杂的逻辑，您可以创建额外的字段。这是一个实现Omikron\FactFinder\Shopware6\Export\Field\FieldInterface的类。在方法getCompatibleEntityTypes中，您可以指定该字段可以应用于哪些实体。适用于给定实体的所有字段将以迭代器形式传递给Omikron\FactFinder\Shopware6\Export\Data\ExportEntityInterface的实例。以下是一个示例（产品实体）

//src/Export/Data/Entity/ProductEntity.php:18
public function __construct(Product $product, iterable $productFields)
{
    $this->product       = $product;
    $this->productFields = $productFields;
}

然后您可以调用Omikron\FactFinder\Shopware6\Export\FeedFactory来创建一个Feed以

$feed = $this->feedFactory->create($context, YourCustomEntity::class);
$feed->generate();

注意： $context是Shopware\Core\System\SalesChannel\SalesChannelContext类的对象

扩展特定的 Web 组件模板

所有Web组件渲染的HTML都包含在Twig块中。如果您需要更改，只需扩展父文件并覆盖包含模板的块。例如，如果您需要为ff-record元素定义自己的模板，该元素负责在搜索结果页面上渲染记录瓷砖

{% sw_extends '@Parent/storefront/components/factfinder/record-list.html.twig' %}

{% block component_factfinder_record %}
    {# here comes the template #}
{% endblock %}

正如我们所看到的，我们使用sw_extends扩展父文件，然后定义重新定义的component_factfinder_record块。它包含在插件文件Resources/views/storefront/components/factfinder/record-list.html.twig中。使用此代码，您仅覆盖此块，父文件的其余HTML将被继承。

注意：该部分的模板代表由Web组件渲染的HTML，而不是.html.twig文件

在分类页面上分割 ASN

分割ASN方法的演示版本在此处可用。可以使用PageBuilder重现此功能。

添加两个FF-ASN CMS元素

配置主要ASN

配置第二个ASN

注意：在此设置中，必须禁用Filter Cloud，因为目前它没有对自定义主题的支持

重复的过滤变量

上面的示例将ASN组分为两个互斥的集合。如果您只想从第一个ASN复制一些过滤条件并将其放入第二个，只需将第一个ASN的配置更改为：

在这种情况下，我们不使用splice方法，而是使用slice，它不会修改原始数据。

注意：Dom Updated监听器可以是空的。第二个ASN的ASN组也存在于第一个中，因此没有必要将它们合并在一起。注意：由于所有ASN组都在第一个ASN中可用，因此可以使用Filter Cloud。

设置自定义字段角色

如果您不打算使用模块提供的馈送，或者您想将某些基本列的名称与默认名称不同，您必须记住调整FACT-Finder®和Web组件使用的字段角色。

默认字段角色在services.xml文件中定义为Symfony配置参数的数组

<parameter key="factfinder.field_roles" type="collection">  
 <parameter key="brand">Manufacturer</parameter>  
 <parameter key="deeplink">Deeplink</parameter>  
 <parameter key="description">Description</parameter>  
 <parameter key="ean">EAN</parameter>  
 <parameter key="displayProductNumber">ProductNumber</parameter>  
 <parameter key="imageUrl">ImageUrl</parameter>  
 <parameter key="masterArticleNumber">Master</parameter>  
 <parameter key="price">Price</parameter>  
 <parameter key="productName">Name</parameter>  
 <parameter key="trackingProductNumber">ProductNumber</parameter>  
</parameter>

为了覆盖由模块定义的这些参数，您必须在您的应用程序的services.xml中重新定义它们。那里定义的参数优先于模块中定义的默认值。

添加自定义导出缓存订阅者

use Omikron\FactFinder\Shopware6\Events\FeedPreprocessorEntryBeforeCreate;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class FeedPreprocessorEntryBeforeCreateSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [FeedPreprocessorEntryBeforeCreate::class => 'onCreateEntries'];
    }

    public function onCreateEntries(FeedPreprocessorEntryBeforeCreate $event)
    {
        $entry = $event->getEntry();
        $entry['additionalCache'] = [
            'some_data' => 'cache1',
            'some_data2' => 'cache2',
        ];
        $event->setEntry($entry);
    }
}

在 ProxyController 中丰富从 FACT-Finder 收到的数据

use Omikron\FactFinder\Shopware6\Events\EnrichProxyDataEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

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

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

贡献

我们欢迎贡献！有关更多信息，请点击此处

许可

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

omikron / shopware6-factfinder

维护者

详情