webgriffe / sylius-clerk-plugin
Clerk.io plugin for Sylius.
Installs: 7 244
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 3
Forks: 1
Open Issues: 0
Type:sylius-plugin
Requires
- php: ^8.0
- ext-json: *
- sylius/sylius: ^1.11
- symfony/serializer: ^4.4 || ^5.0
Requires (Dev)
- behat/behat: ^3.6.1
- behat/mink-selenium2-driver: ^1.4
- dmore/behat-chrome-extension: ^1.3
- dmore/chrome-mink-driver: ^2.7
- flow/jsonpath: ^0.5.0
- friends-of-behat/mink: ^1.8
- friends-of-behat/mink-browserkit-driver: ^1.4
- friends-of-behat/mink-debug-extension: ^2.0.0
- friends-of-behat/mink-extension: ^2.4
- friends-of-behat/page-object-extension: ^0.3
- friends-of-behat/suite-settings-extension: ^1.0
- friends-of-behat/symfony-extension: ^2.1
- friends-of-behat/variadic-extension: ^1.3
- friendsofsymfony/oauth-server-bundle: ^1.6 || >2.0.0-alpha.0 ^2.0@dev
- phpspec/phpspec: ^7.0
- phpstan/extension-installer: ^1.0
- phpstan/phpstan: 0.12.99
- phpstan/phpstan-doctrine: 0.12.33
- phpstan/phpstan-strict-rules: ^0.12.0
- phpstan/phpstan-webmozart-assert: 0.12.12
- phpunit/phpunit: ^9.5
- polishsymfonycommunity/symfony-mocker-container: ^1.0
- sensiolabs/security-checker: ^6.0
- sylius-labs/coding-standard: ^4.0
- symfony/browser-kit: ^5.4
- symfony/debug-bundle: ^5.4
- symfony/dotenv: ^5.4
- symfony/intl: ^5.4
- symfony/web-profiler-bundle: ^5.4
- vimeo/psalm: 4.7.1
This package is auto-updated.
Last update: 2023-03-07 16:50:37 UTC
README
Clerk.io Plugin
This plugin integrates your Sylius store with Clerk.io, the world's #1 e‑commerce personalization platform (AI) for product recommendations.
Installation
-
Run
composer require webgriffe/sylius-clerk-plugin
. -
Add the plugin to the
config/bundles.php
file:Webgriffe\SyliusClerkPlugin\WebgriffeSyliusClerkPlugin::class => ['all' => true],
-
Add the plugin's routing by creating the file
config/routes.yaml
with the following content: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"
-
Finish the installation by installing assets:
bin/console assets:install bin/console sylius:theme:assets:install
Configuration
The Clerk.io integration with Sylius is per-channel. Every Clerk.io store must be syncronized with just only one Sylius channel. So, to configure this plugin you must create a file in config/packages/webgriffe_sylius_clerk.yaml
with the following contents:
webgriffe_sylius_clerk: 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
Where every entry in the stores
key must contain the Sylius channel code in channel_code
and the related Clerk's public/private API key in public_api_key
and private_api_key
.
Sync your data with Clerk.io
Login into your Clerk.io dashboard and go to the Data page. In the Data Sync Settings section, select Clerk.io JSON Feed as Sync Method and enter the following JSON Feed URL:
https://your-sylius-store.com/clerk/feed/channelId
Where https://your-sylius-store.com
is your Sylius store base URL and channelId
is the database ID of the Sylius channel you whant to sync.
Install Clerk.js on you store front
Like stated in the official Clerk documentation here, you have to put the Clerk.js tracking code on all pages of your store just before the </head>
tag. To do so this plugin expose a dedicated controller action which you can render in your Twig template, for example like the following:
{# templates/bundles/SyliusShopBundle/layout.html.twig #} {% extends '@!SyliusShop/layout.html.twig' %} {% block stylesheets %} {{ parent() }} {{ render(url('webgriffe_sylius_clerk_tracking_code')) }} {% endblock %}
From then you can use all the Clerk.js features on your store pages.
Install sales tracking on order success page
Like stated in the official Clerk documentation here, you should optimise Clerk.io by installing the instant sales tracking code on your thank you page. To do so this plugin expose a dedicated controller action which you can render in your thank you page Twig template, for example like the following:
{# 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 %}
Customizing
Basically, this bundle provides an easy way to generate a JSON feed compliant with the Clerk.io data feed specifications. The feed basically contains three arrays of the following entities:
- Products
- Categories (a.k.a. Taxons on Sylius)
- Orders
For each entity type the following two components are involved in feed generation:
- A
Webgriffe\SyliusClerkPlugin\QueryBuilder\QueryBuilderFactoryInterface
which is responsible to create aDoctrine\ORM\QueryBuilder
which builds the query to select the objects you want to include in the feed. - A
Symfony\Component\Serializer\Normalizer\NormalizerInterface
which is a common normalizer of the Symfony's Serializer component. The normalizer is the component responsible to convert every instance of the related entity type to an associative array which is then converted to JSON. To the normalization process will be passed a specialclerk_array
format. So, your normalizers should support only normalization for theclerk_array
format. In this way there's no risk to break other serializer usages for that objects.
The plugin already provides three query builder factories and three normalizers:
- Products:
Webgriffe\SyliusClerkPlugin\QueryBuilder\ProductsQueryBuilderFactory
andWebgriffe\SyliusClerkPlugin\Normalizer\ProductNormalizer
- Categories:
Webgriffe\SyliusClerkPlugin\QueryBuilder\TaxonsQueryBuilderFactory
andWebgriffe\SyliusClerkPlugin\Normalizer\TaxonNormalizer
- Orders:
Webgriffe\SyliusClerkPlugin\QueryBuilder\OrdersQueryBuilderFactory
andWebgriffe\SyliusClerkPlugin\Normalizer\OrderNormalizer
So, to customize the feed generation you can replace these implementations using the common Symfony techniques to do so (see here).
Contributing
To contribute you need to:
-
Clone this repository into your development environment
-
[OPTIONAL] Copy the
.env
file inside the test application directory to the.env.local
file:cp tests/Application/.env tests/Application/.env.local
Then edit the
tests/Application/.env.local
file by setting configuration specific for you development environment. -
Then, from the plugin's root directory, run the following commands:
(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)
-
Run test application's webserver on
127.0.0.1:8080
:symfony server:ca:install APP_ENV=test symfony server:start --port=8080 --dir=tests/Application/public --daemon
-
Now at https://127.0.0.1:8080/ you have a full Sylius testing application which runs the plugin
Testing
After your changes you must ensure that the tests are still passing. The current CI suite runs the following tests:
-
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
To run them all with a single command run:
composer suite
To run Behat's JS scenarios you need to setup Selenium and Chromedriver. Do the following:
-
Start Headless 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
-
Remember that the test application webserver must be up and running as described above:
symfony server:ca:install APP_ENV=test symfony server:start --port=8080 --dir=tests/Application/public --daemon
License
This library is under the MIT license. See the complete license in the LICENSE file.
Credits
Developed by Webgriffe®.