README

Clerk.io 插件

此插件将您的 Sylius 店铺与 Clerk.io 集成，Clerk.io 是全球领先的电子商务个性化平台（AI）产品推荐平台。

安装

1. 运行 composer require webgriffe/sylius-clerk-plugin。

2. 将插件添加到 config/bundles.php 文件

   Webgriffe\SyliusClerkPlugin\WebgriffeSyliusClerkPlugin::class => ['all' => true],

3. 通过创建具有以下内容的 config/routes.yaml 文件来添加插件的路由

   webgriffe_sylius_clerk_shop:
       resource: "@WebgriffeSyliusClerkPlugin/Resources/config/shop_routing.yml"
       prefix: /{_locale}
       requirements:
           _locale: ^[a-z]{2}(?:_[A-Z]{2})?$
   
   webgriffe_sylius_clerk_admin:
       resource: "@WebgriffeSyliusClerkPlugin/Resources/config/admin_routing.yml"
       prefix: /admin
   
   webgriffe_sylius_clerk_feed:
       resource: "@WebgriffeSyliusClerkPlugin/Resources/config/feed_routing.yml"
   

4. 通过安装资产来完成安装

   bin/console assets:install
   bin/console sylius:theme:assets:install

配置

Sylius 与 Clerk.io 的集成是按渠道进行的。每个 Clerk.io 店铺都必须仅与一个 Sylius 渠道同步。因此，要配置此插件，您必须在 config/packages/webgriffe_sylius_clerk.yaml 文件中创建一个文件，内容如下

webgriffe_sylius_clerk:
  # optional - if you want to change the default feed path
  # storage_feed_path: '%kernel.project_dir%/%env(CLERK_FEED_PATH)%'  
  # storage_feed_path: '%kernel.project_dir%/var/storage'  
  stores:
    - channel_code: WEB-US
      public_api_key: web-us-public-key
      private_api_key: 123abc
    - channel_code: WEB-EU
      public_api_key: web-ew-public-key
      private_api_key: 890xyz

其中每个 stores 键的条目都必须包含 channel_code 中的 Sylius 渠道代码和在 public_api_key 和 private_api_key 中的相关 Clerk 公共/私有 API 密钥。

与 Clerk.io 同步您的数据

登录您的 Clerk.io 仪表板 并转到 数据 页面。在 数据同步设置 部分，选择 Clerk.io JSON Feed 作为 同步方法 并输入以下 JSON Feed URL

https://your-sylius-store.com/clerk/feed/channelId

其中 https://your-sylius-store.com 是您的 Sylius 店铺基础 URL，而 channelId 是您要同步的 Sylius 渠道的数据库 ID。

或者为该命令设置 cron 作业

bin/console webgriffe:clerk:generate-feed channelCode

并使用以下 JSON Feed URL

https://your-sylius-store.com/media/<channelCode>_clerk_feed.json

在您的前端商店上安装 Clerk.js

如官方 Clerk 文档中所述 此处，您必须在所有页面中 </head> 标签之前放置 Clerk.js 跟踪代码。为此，此插件提供了一个专用的控制器操作，您可以在您的 Twig 模板中渲染，例如以下内容

{# templates/bundles/SyliusShopBundle/layout.html.twig #}

{% extends '@!SyliusShop/layout.html.twig' %}

{% block stylesheets %}
    {{ parent() }}

    {{ render(url('webgriffe_sylius_clerk_tracking_code')) }}
{% endblock %}

从那时起，您就可以在商店页面上使用所有 Clerk.js 功能。

在订单成功页面上安装销售跟踪

如官方 Clerk 文档中所述 此处，您应该通过在感谢页面上安装即时销售跟踪代码来优化 Clerk.io。为此，此插件提供了一个专用的控制器操作，您可以在您的感谢页面的 Twig 模板中渲染，例如以下内容

{# templates/bundles/SyliusShopBundle/Order/thankYou.html.twig #}
{% extends '@!SyliusShop/Order/thankYou.html.twig' %}

{% block javascripts %}
    {{ parent() }}

    {{ render(url('webgriffe_sylius_clerk_sales_tracking', {orderId: order.id})) }}
{% endblock %}

自定义

基本上，此包提供了一种简单的方法来生成符合 Clerk.io 数据源规范 的 JSON 源。该源基本上包含以下实体的三个数组

• 产品
• 类别（在 Sylius 中称为税目）
• 订单
• 客户
• 页面

对于每种实体类型，涉及以下两个组件的生成源

• 一个负责创建用于选择您想要包含在源中的对象的 Doctrine\ORM\QueryBuilder 的 Webgriffe\SyliusClerkPlugin\QueryBuilder\QueryBuilderFactoryInterface。
• 这是一个 Symfony\Component\Serializer\Normalizer\NormalizerInterface 接口，它是 Symfony 的 Serializer 组件 的通用序列化器。序列化器负责将相关实体类型的每个实例转换为关联数组，然后将其转换为 JSON 格式。规范化过程将传递一个特殊的 clerk_array 格式。因此，您的序列化器应仅支持 clerk_array 格式的规范化。这样就不会存在破坏该对象其他序列化器使用的风险。

该插件已经提供了三个查询构建器工厂和三个序列化器

• 产品：Webgriffe\SyliusClerkPlugin\QueryBuilder\ProductsQueryBuilderFactory 和 Webgriffe\SyliusClerkPlugin\Normalizer\ProductNormalizer
• 分类：Webgriffe\SyliusClerkPlugin\QueryBuilder\TaxonsQueryBuilderFactory 和 Webgriffe\SyliusClerkPlugin\Normalizer\TaxonNormalizer
• 订单：以解析器的形式实现。请参阅 Webgriffe\SyliusClerkPlugin\OrderResolver 以获取默认源值（数据库）。如果您想自定义，您必须装饰 OrderResolver 并创建一个实现 Webgriffe\SyliusClerkPlugin\Resolver\OrderResolverInterface 的服务。您还需要装饰 OrderNormalizer 以获得针对 Clerk 的正确输出（基于您自己的数据源）
• 客户：Webgriffe\SyliusClerkPlugin\QueryBuilder\CustomersQueryBuilderFactory 和 Webgriffe\SyliusClerkPlugin\Normalizer\CustomerNormalizer
• 页面：该实体不是由 Sylius 核心提供的，因此您必须实现自己的解析器。请参阅 Webgriffe\SyliusClerkPlugin\PageResolver 中的示例。如果您想使用它，您必须装饰 PageResolver 并创建一个实现 Webgriffe\SyliusClerkPlugin\Resolver\PageResolverInterface 的服务

因此，要自定义数据生成，您可以使用通用的 Symfony 技术替换这些实现（请参阅 此处）。

贡献

要贡献力量，您需要

1. 将此存储库克隆到您的开发环境中

2. [可选] 将测试应用程序目录中的 .env 文件复制到 .env.local 文件

   cp tests/Application/.env tests/Application/.env.local

   然后，通过为您开发环境设置特定配置来编辑 tests/Application/.env.local 文件。

3. 然后，从插件的根目录，运行以下命令

   (cd tests/Application && yarn install)
   (cd tests/Application && yarn build)
   (cd tests/Application && APP_ENV=test bin/console assets:install public)
   (cd tests/Application && APP_ENV=test bin/console doctrine:database:create)
   (cd tests/Application && APP_ENV=test bin/console doctrine:schema:create)

4. 在 127.0.0.1:8080 上运行测试应用程序的 web 服务器

   symfony server:ca:install
   APP_ENV=test symfony server:start --port=8080 --dir=tests/Application/public --daemon

5. 现在，在 https://127.0.0.1:8080/，您有一个完整的 Sylius 测试应用程序，该应用程序运行该插件

测试

更改后，您必须确保测试仍然通过。当前的 CI 代码库运行以下测试

• Easy Coding Standard

  vendor/bin/ecs check src/ tests/Behat/

• PHPStan

  vendor/bin/phpstan analyse -c phpstan.neon -l max src/

• PHPUnit

  vendor/bin/phpunit

• PHPSpec

  vendor/bin/phpspec run

• Behat

  vendor/bin/behat --strict -vvv --no-interaction || vendor/bin/behat --strict -vvv --no-interaction --rerun

要运行所有测试的单一命令，请运行

composer suite

要运行 Behat 的 JS 场景，您需要设置 Selenium 和 Chromedriver。请按照以下步骤操作

1. 安装 Symfony CLI 命令.

2. 启动无头 Chrome

   google-chrome-stable --enable-automation --disable-background-networking --no-default-browser-check --no-first-run --disable-popup-blocking --disable-default-apps --allow-insecure-localhost --disable-translate --disable-extensions --no-sandbox --enable-features=Metal --headless --remote-debugging-port=9222 --window-size=2880,1800 --proxy-server='direct://' --proxy-bypass-list='*' http://127.0.0.1

3. 请记住，测试应用程序的 web 服务器必须像上面描述的那样运行

   symfony server:ca:install
   APP_ENV=test symfony server:start --port=8080 --dir=tests/Application/public --daemon

许可证

此库受 MIT 许可证的约束。有关完整许可证，请参阅 LICENSE 文件。

致谢

由 Webgriffe® 开发。