README

本文档帮助您将 FACT-Finder® Web Components SDK 集成到 Oxid Shop 中。此外，它还简要概述了其主要功能。第一章安装指导您完成建议的安装过程。第二章 后端配置 解释了 Oxid 后端中的自定义选项。最后一章 Web 组件集成 描述了 Web 组件如何与商店系统交互以及如何自定义它们。

要求

OXID eShop 6.x
PHP 版本：7.2, 7.3, 7.4

注意：如果您使用 OXID eShop 7.x，请使用 SDK 版本 5.x

安装

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

composer require omikron/oxid-factfinder:^4.0

激活模块

从 Oxid 安装根目录开始，使用以下命令清除缓存

rm -rf source/tmp/*

在 Oxid 2 后端 "商店 → 配置 → 高级 → 高级" 中检查模块输出是否已启用。

后端配置

一旦模块被激活，您可以在 "扩展 → 模块 → FACT-Finder® Web Components | Omikron Data Quality GmbH → 设置" 下找到配置页面。以下段落将涵盖所有部分。

主要设置

本节包含一个关键配置，这是模块正常工作所必需的。所有字段均有自解释。在此设置的配置由 Web 组件和服务器端与 FACT-Finder® 实例通信时使用。您将获得的凭据应放置在此处。

服务器 URL - FACT-Finder® 实例 URL
注意：服务器 URL 应包含一个使用的协议：（例如 https://）并且应以针对特定版本的端点结尾（例如在版本 7.3 中为 FACT-Finder-7.3，在 NG 中为 fact-finder）
频道 - 您希望从中提供数据的频道
注意：频道字段的数量根据应用程序中使用的活动语言数量进行调整。请确保为给定语言设置正确的频道。
用户名 - 用于将数据导入 FF
密码 - 用于将数据导入 FF
用户名 - 用于从 FF 获取数据
密码 - 用于从 FF 获取数据
授权前缀
授权后缀
注意：FACT-Finder® NG 不需要设置 授权前缀 和 授权后缀 字段。在这种情况下，请省略这些字段。
版本 - 所使用的 FACT-Finder® 版本
注意：模块支持从版本 6.9 到 NG 的 FACT-Finder®。选择错误的版本可能会导致 Web 组件无法与 FACT-Finder® 通信。
API版本 - 使用FACT-Finder® API版本
注意：模块支持FACT-Finder® API版本v4和v5。选择错误的API版本可能会导致Web组件无法与FACT-Finder®通信

按钮

测试连接按钮

点击测试连接按钮可以检查您的凭据是否正确。此功能使用表单数据，因此无需先保存。注意：此功能使用de通道输入值。

导出数据按钮

这是导出数据的一种可能方式。更多详情请参阅管理员面板导出部分

测试 FTP 连接按钮

此功能允许您测试您的商店是否可以成功连接到配置的FTP/SFTP服务器。它使用请求中传递的参数，因此无需在之前保存配置。

更新字段角色按钮

此功能允许您在FACT-Finder中更改字段角色后更新字段角色。字段角色默认配置为模块导出的列。如果您打算更改作为角色使用的列名，例如Master或ProductNumber，它们分别持有Master文章编号和产品编号角色，请记得使用此功能更新字段角色

高级设置

使用URL参数？ - 如果您想将每个使用的查询参数推送到URL中，请选择此选项
附加参数 - 您可以在此处为每个这些属性定义额外参数：add-params、add-tracking-params、keep-url-params、parameter-whitelist。值将传递到Web组件中并在通信中使用。有关所述属性的更多信息，请参阅Web组件文档。
匿名化用户ID？ - 如果您想以匿名形式发送跟踪请求中的用户ID，请选择此选项。默认情况下，发送用户表中的常规ID字段。
使用代理 - 如果您想通过Web组件发送的每个请求首先到达专门的模块控制器，然后将其转发到FACT-Finder，请选择此选项。注意：如果您计划使用代理，请考虑阅读以下段落，因为它需要完整的说明才能正确启用。
如何计算“添加到购物车”按钮的单次点击？ - 选择您想要如何计算“添加到购物车”按钮的单次点击
用户未登录时发送SID作为userId？

代理

代理功能添加了一个oxid控制器，它作为Web组件和FACT-Finder®之间的中间件。启用代理时的数据流如下图中所示。具有中间件控制器可以带来许多自定义请求和响应的可能性。此外，如果转发的请求没有返回正确的响应，您可以从这个点开始实现回退策略。

   //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('');
    }

要启用代理，您需要通过添加两个重写规则来更改您的HTTP服务器配置。这是必要的，因为Web组件将URL部分附加到基本URL，使其对Oxid不可读。这是因为Oxid使用查询参数cl和fnc来实例化特定的控制器并执行其功能。没有使用URL部分的路由，因此任何AJAX请求都必须针对包含上述参数的index.php文件。没有这些规则，任何请求都将导致404。

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]

功能设置

在分类页面使用FACT-Finder®？ - 选择此选项以在分类页面中使用Web组件。更多信息请参阅单独的段落。
活动 - 在产品页面上启用ff-campaign-product，在购物车页面上启用ff-campaign-feedbacktext和ff-campaign-shopping-cart
建议 - 在产品页上启用 ff-recommendation
相似产品 - 在产品页上启用 ff-similar-products
推荐产品 - 在购物车页上启用 ff-campaign-pushed-products>

在分类页面上使用 FACT-Finder®

为了保留分类URL并因此利用SEO，使用标准的Oxid路由，结合FACT-Finder®的可用性，将自定义参数传递到搜索请求。当用户进入分类页面时，立即触发搜索事件（感谢使用search-immediate通信参数）。

数据源设置

此部分允许设置要导出的属性。如果您想将属性导出到单独的列，请从选择输入中选择它，并将多属性列值设置为否。如果多属性设置为是，则属性将放置在聚合列FilterAttributes中 注意：选择属性始终自动放置在FilterAttributes中。

导出设置

如果您想将导出文件传输到FTP服务器，以便由FACT-Finder®导入，请使用以下字段。

FTP主机
FTP端口
FTP用户
FTP密码

附加

启用SSL - 如果您的FTP服务器需要使用安全协议连接，请选择此选项
产品自动导入 - 启用上传后由FACT-Finder®执行的导入
注意：如果没有配置FTP服务器，则此选项将不起作用
导入数据 - 触发数据（搜索数据库）
导入建议 - 触发建议数据库
导入推荐 - 触发推荐数据库
HTTP导出基本认证用户
HTTP导出基本认证密码
注意：基本认证用于保护基于HTTP的导出，您可以在下一节中了解更多信息。

导出方法

HTTP 导出

此方法使用一个特定的URL，在URL下导出将可用。您可以设置FACT-Finder®直接从该位置下载导出。

[YOUR_SHOP_URL]?cl=http_article_feed&fnc=export

用于分类导出

[YOUR_SHOP_URL]?cl=http_category_feed&fnc=export

用于建议分类导出

[YOUR_SHOP_URL]?cl=http_suggest_category_feed&fnc=export

注意：请记住，导出文件不是直接在该位置下直接可用的。有一个按需执行的导出机制，因此整个过程可能需要一些时间。

基本认证

使用导出设置，您可以通过设置基本认证来保护HTTP导出。请记住，在这种情况下，您需要在URL中包含凭证，否则FACT-Finder®将无法下载导出文件。您可以使用以下语法在URL中包含基本认证凭证

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

FTP 导出

使用这种方法，导出的导出文件将上传到特定的FTP/SFTP服务器。一旦导出文件上传完毕，FACT-Finder®将根据上传的文件请求开始导入（可选）。与此导出方法相关的所有设置均位于导出设置中。字段“密钥”和“密钥通行短语”仅适用于SFTP。字段“SSL启用”仅适用于FTP。

注意：使用的FTP/SFTP服务器也应可供FACT-Finder®访问。

管理面板导出

导出导出按钮位于模块配置中，可以用于手动触发导出。通过单击此按钮，您将触发整个导出过程，包括上传到FTP服务器和触发FACT-Finder®导入（如果启用）。

注意：此方法不会将导出文件下载到您的本地文件系统。如果您需要查看它，请使用HTTP导出

注意：此处不提供分类导出，因为单击按钮开始导入通道，但分类导出应作为主要文章导出的增强。

控制台命令

在模块的bin目录中有两个控制台命令可供使用。只需使用安装的PHP CLI运行它们。

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

feed-write.php - 仅在本地文件系统上保存导出文件
feed-upload.php - 运行完整集成（就像在管理员面板中点击导出产品目录按钮一样）

如果您使用Oxid Enterprise及其多店铺功能，您可以通过使用-s参数来指定店铺ID，例如：

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

如果您的店铺支持多种语言，可以通过在命令中添加-l参数来输入您要导出的语言标识符（例如php bin/feed-write.php -l 1）。您可以在“主设置 -> 语言”中查看语言标识符。您可以使用-t选项指定目录类型。默认值为product。要切换到类别，请使用-t category

跟踪

在这里您可以找到一份完整的跟踪指南。此模块遵循该指南以提供以下事件的跟踪

点击产品

此事件由ff-record元素绑定自动跟踪。注意：为此功能正常工作，必须添加指令data-redirect

将产品添加到购物车

我们提供了一个registerAddToCartListener函数，该函数有助于在表单提交按钮上注册click事件。注意：示例用法可以在src/views/frontend/blocks/campaign/product.tpl中找到

下订单

此事件由在订单确认页面上实现的ff-checkout-tracking元素跟踪

贡献

有关更多信息，请点击这里

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

许可协议

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

omikron / oxid-factfinder

维护者

详细信息