FactFinder: AI-powered Search & Product Discovery

FactFinder® Web Components for Shopware 6

Plugin documentation

WebComponents documentation

This document helps you to integrate the FACT-Finder® Web Components SDK into your Showpare Shop. In addition, it gives a concise overview of its primary functions. The first chapter Installation walks you through the suggested installation process. The second chapter Settings explains the customisation options in the Showpare backend. The final chapter Exporting Feed describes how to use provided console command to export the feed.

System Requirements

• Shopware 6.5 and 6.6

• PHP version 8.1 or higher

Installation

To install the plugin, open your terminal and run the command:

composer require omikron/shopware6-factfinder

After successfully installation, it will be visible in the extensions list. Depending on the Shopware 6 versions the view could be different.

Second method to install plugin is via marketplace.

Activating the Module

To activate the module, please use the switcher located on the left side of the row with extension info. After it is installed, its configuration is available under the three dots icon. All sections will be covered in the following paragraphs.

This section contains a plugin configuration, which is required in order for the module to work. All fields are self-explained. Configuration set here is used by both Web Components and during the server side communication with FactFinder® instance. Credentials you will be given should be placed here. Please remember that you have to clear the store cache in order the new applied configuration to start working.

• Server URL - FactFinder® instance url
  Note: Server URL should contain a used protocol: (e.g. https://) and should end with an endpoint ( fact-finder )
• Channel - Channel you want to serve data from
• Username
• Password

• API Version - Used FactFinder® api version

Module supports FactFinder® api version v4 and v5. By selecting the wrong api version you may cause the Web Components to be unable to communicate with FactFinder®

Update Field Roles

This functionality offers a way to download field roles configured in FactFinder®. Please use this if you don't use feed offered by the plugin or for some reason you have changed the column names. You can find more information about what Field Roles are in (Web Components documentation) Note:  Updating process is ran for all sales channels, no need to run it separately for each of them

Server Side Rendering

That option enables Server Side Rendering (SSR) for ff-record-list element on category and search result pages. That means when user navigate to a page of mentioned type, the HTML output will contain the pre-rendered custom elements. This is useful especially in terms of SEO because ff-record-list renders product data which could have much impact on page rating in browser. Without SSR enabled, web crawlers could not have a chance to scan the element rendered content because it will not yet be rendered on the time of scanning.

Note: More information about SSR concept you can find in the article Server Side Rendering from Web Components documentation.

This section contains a plugin configuration, which is optional and provides additional features.

• Use Proxy? - By enabling this, once a search query is sent, it does not immediately reach FactFinder, but is handed off to a specific controller src/Storefront/Controller/ProxyController.php which hands the request to the FactFinder system, receives the answer, processes it and only then returns it to the frontend view. You can use EnrichProxyDataEvent to enrich data received from FactFinder. You can find more details about implementation here.

    Note: Sending each request to FactFinder instance trough Shopware, you lose on performance as each request need to be handled first by HTTP server and then, by Shopware itself. This additional traffic could be easily avoided by not activating this feature if there's no clear reason to use it.

• Scenario how to count single click on "Add to cart" button
• Redirect mapping for selected queries - put each pair query=url in separate row. If the phrase appears twice, the first one from the top of the list will be taken. Url can be relative path /some/page or absolute url https://domain.com/some/page?someParameter=1. If provided pair has an invalid format then it will be ignored.

• Select Filter Attributes which should be ignored- product properties selected here will not be exported. By default, all properties are being exported. Note: Variant products properties which are part of the configuration will ignore that settings.
• Select Custom Fields which should be ignored - custom fields selected here will not be exported. By default, all custom fields are being exported.
• Export prices for all Currencies - if disabled, export will contain only one column Price. If enabled, all product price will be exported in all currency configured for a given sales channel.

If Export prices in all currencies setting is set to true, price columns will be exported in followed pattern Price_[currency ISO code] i.e. Price_De

Following settings are used for uploading already exported feed to a given FTP/SFTP server.

Note: The default port setting is 21. If your server is listening on different port, please change it accordingly.

• Protocol
• Server URL
• Port
• Username
• Password
• Root Directory
• Private Key Content
• Passphrase

Note* Fields "Private Key Content" and "Passphrase" are optional. Use them only if your SFTP server require this method of authentication.

• Enable Automatic Import for - define import types which should be triggered. Possible types are: Suggest, Search and Recommendation

Note: This feature is experimental, and it is highly possible that it will be significantly modified in a near future.

Plugin offers a way to use FactFinder® Web Components on category pages using page builder Shopping Experiences. There is two CMS blocks offered:

• Listing
  • ff-record-list
  • ff-asn + including ff-filter-cloud
  • ff-pagination
  • ff-sortbox
• Campaigns
  • ff-campaign-feedbacktext
  • ff-campaign-advisor
  • ff-campaign-redirect
  • ff-campaign-pushed-products

Offered Cms Blocks and Elements are designed to work on pages of type LandingPage. There is a type CategoryPage but the builtin validation will not allow saving that prepared page, unless it contains at least one default Product Listing Block. The block FACTFinder Web Components Listing is unfortunately not taken into account.

All elements are available under the category Commerce

Each of the element of given block contains dedicated configuration which allows to configure them without necessity of adding hardcoded values in the templates.

If you do not want to render a specific element, just change the subscribe option to false. This will make element will not subscribe to the FactFinder® response, hence they will not render any HTML.

• Subscribe - Activate element
• Vertical - If set to true, btn-block CSS class is added to ff-asn-group, and ff-asn gets a align property set to `vertical
• ID - Element identifier. If left empty, the CMS Element ID will be used.
• Topic - Topic which element is subscribed to. If left empty, the element subscribes to default asn topic
• Callback Argument - A name of variable holding FactFinder response data appropriate for the element. It will be visible inside Callback scope
• Callback - A function which allows to manipulate the received data. This data is available under the name set in CallbackArgument
• Dom Updated - A listener to dom-updated event. This event is triggered when rendered its HTML template

Record List Element

• Subscribe - activate element
• Infinity Scrolling - Adds the inifinity-scrolling attribute to the ff-record-list element
• Infinite Debounce Delay - addsinfinite-debounce-delay attribute to the ff-record-list element
• ID - Element identifier. If left empty, the CMS Element ID will be used.
• Callback Argument - A name of variable holding FactFinder response data appropriate for the element. It will be visibile inside Callback scope
• Callback - A function which allows to manipulate the received data. This data is available under the name set in CallbackArgument
• Dom Updated - A listener to dom-updated event. This event is triggered when rendered its HTML template

Campaigns Element

• Advisor Campaign - Renders ff-campaign-advisor element
• Advisor Campaign Name - Adds label attribute to ff-campaign-advisor.
• Feedback Campaign - Renders ff-campaign-feedbacktext element
• Feedback Campaign Label - Bind the campaign element to a FactFinder campaign with a given label, making it reacting only to it.
• Feedback Campaign Flag - Set a flag making the campaign element reacts to FactFinder campaign of the specific type
• Feedback Campaign - Renders ff-campaign-feedbacktext element
• Advisor Campaign Name - Adds label attribute to ff-campaign-feedbacktext.
• Redirect Campaign - Renders ff-campaign-redirect element
• Pushed Products - Renders ff-campaign-pushed-products element
• Pushed Products Flag - Set a flag making the campaign element reacts to FactFinder campaign of the specific type

Note: You can find more information about campaigns related elements and their configuration in Web Components documentation

Each of the block and element has it own templates which could be found, according to the Shopware 6 convention:

• for blocks - Resources/views/storefront/block
• for element - Resources/views/storefront/element which could be extended using Shopware sw_extends tag

Assigning Layout to Category

Once the page layout is done, you need to assign layout to selected categories.

We strongly recommend not creating many layouts as currently there's still only few possibilities offered anyway. Future development will bring more blocks and elements will be provided here.

FactFinder allows to export different types of feeds, like a products, cms and brands (or manufacturers)

Also you can define your own data types to export in services.xml file in factfinder.data_export.entity_type_map parameter

Feed can be exported in two ways: using admin panel (www.yourhost.com/admin#/ui/feed/export/index) or using CLI

CLI

Feed export is available in the Shopware CLI application. You can run it by executing:

and follow the instructions in console.

If You want to run command whitout interaction mode, type command with -n option:

The command can be run with an optional argument indicating the sales channel ID that you are targeting. The ID is an string value.

If a specific language needs to be specified, theres is a second argument which allows that.

There are two additional options (except -n):

• -u uploads the feed to the configured FTP server after feed is generated.
• -i runs the FactFinder® import with previously uploaded feed
  Note: This option works only in a combination with -u

by default export outputs data in the STDOUT. It could be easily redirected using Linux way of redirecting output.

Selecting Categories for CMS Export

With CMS Export we introduced custom field for CategoryEntity by which we filter the Categories going to be exported. You can find it on Category edit page. 

Exporting from Admin Panel

There is a possibility to run whole integration: generating feed, uploading it to FTP server and trigger FactFinder® import. A dedicated form can be found under Extensions section

Select fields allows you to select sales channel and languague parameter for which an integration shall be run. Select export type gives you possibility to create different content of data available in your Shopware instance. Export can be done for:

• Products
• Brands
• Cms
• Category

Create Export Send a message to a bus which then might be consumed automatically by an admin worker (if enabled) or by CLI worker. More information about messaging you can find in official Shopware documentation

Note: Please note that plugin right now is supporting only classic storefronts, rendered using Twig templating system.

Web Components Documentation

Full FactFinder® Web Components documentation you can find here

The module is shipped with script including FactFinder® Web Components. Including Scripts step is implemented in the module. No additional action is required.

• 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

All these files are included in Resources/views/storefront/layout/meta.html.twig. That file extends the default theme meta.html.twig . Note: Including these scripts is obligatory for Web Components to work. Make sure you include it or if your storefront does not use that file, include all scripts in mentioned order on your own.

Main configuration element ff-communication is added in file src/Resources/views/storefront/base.html.twig . Same as with meta.twig.html, it extends the base.html.twig file defined in default Storefront. This element is populated automatically with the data, configured in module configuration.

Note: If your theme doesn't extend the default Storefront, make sure you implement ff-communication element as it is mandatory and FactFinder® Web Components will not work without it.

Plugin templates could be found in Resources/views/storefront/. Just as with the previous sections, all templates are extending default Storefront wherever it is possible. You can use these templates if you are extending it using sw_extends which offers a support for a multi inheritance.

Plugin offers a following way of tracking customer actions

• login - logged automatically via ff-communication element when user-id is set
• click on product - implemented using ff-record template directives (see Click Tracking)
• add to cart - implemented in a js plugin
• purchase - implemented using ff-checkout-tracking element (see Checkout Tracking)

Plugin implements a list of given Web Components:

• Page Header

  • ff-communication
  • ff-searchbox
  • ff-suggest

• Search Result & Navigation Page

  • ff-record-list
  • ff-asn
  • ff-sortbox
  • ff-paging
  • ff-filter-cloud
  • ff-campaign-advisor
  • ff-campaign-feedbacktext
  • ff-campaign-redirect

• Product Detail Page

  • ff-campaign-product
  • ff-campaign-pushed-products
  • ff-recommendation
  • ff-similar-products

• Checkout Success Page

  • ff-checkout-tracking