Introduction
Boxalino Winning Interactions Platform provides many features Shopware6, like:
Search As you Type (Autocomplete Flyout)
Search result page with facets (refinement filters), pagination, and sorting
PDP product recommendations (via subscriber event)
Category Product-listing results (a.k.a. Navigation) with facets (refinement filters), pagination and sorting
CMS element (e.g.: products or blog post) for any Layout Integration (with Boxalino Narrative block)
Dynamic router (ex: for brand pages or landing pages)
to integrate Boxalino Winning Interactions Platform, you will need to use our 3 repositories:
Repository | Description | Usage |
---|---|---|
exporter-shopware6 | a standard Shopware6 plugin responsible to export Shopware data to Boxalino | To be replaced with the Data Integration repository |
a Shopware6 plugin responsible to export the Shopware data following the Boxalino Data Integration Data Structures | Install and update when Boxalino provides a new version | |
a standard Shopware6 plugin responsible to manage all the calls to Boxalino API for your front-end | Install and update when Boxalino provides a new version | |
a sample (tutorial) Shopware6 plugin provided to examplified how to integrate Boxalino (you can either build your own from scratch or download (and rename namespace) it to have all default features active directly, but do not copy or clone, as it is your environment and should not be updated from our repo) | Use as inspiration or download (and rename namespace) to bootstrap all features (but do not copy or clone!) and then develop, maintain and extend by yourself |
As per the diagram below, all the execution will be done from your integration plugin (which you will build based on the examples provided in rtux-integration-shopware).
Prerequisites:
The intent of integrating the Boxalino API on a Shopware 6 environment requires building a new repository/plugin in the Shopware6 project which will represent the Integration Layer.
There are two ways to do that:
Step-by-step (recommended)
All-at-once
Step-by-step (recommended):
In this case, you are not integrating the rtux-integration-shopware repository directly, you are simply using it as a reference and build the functionalities step-by-step by yourself.
Boxalino recommends this way as you have full control on what you do and it ensures you don’t implement any code that you don’t need (you can always add it later).
In this case, just create a new plugin from scratch, known as your project`s Integration Layer (ex: namespace Boxalino\RealTimeUserExperienceIntegration
), as an empty Plugin (you will need it in the next step to have a place to declare your export interfaces).
Follow the official Shopware 6 guidelines for how to create a new plugin (ex: https://docs.shopware.com/en/shopware-platform-dev-en/how-to/indepth-guide-bundle/setup)
All-at-Once:
In this case, you download (and rename namespace) (BUT DO NOT COPY OR CLONE!) the rtux-integration-shopware as a basis for your plugin. This will automatically activate all the standard features of Boxalino (search, navigation, product recommendations, …).
Boxalino does not recommend this way unless you know you want to use all the standard features and want to accelerate the process to get one (or many) shop(s) up and running quickly.
You can then review each of the features and modify and adjust them by yourself to fit your project requirements.
1. Declare data integration services and run full export
Follow the steps described in the section: Setup for the Data Integration Layer.
In these steps, after adding and activating the data-integration-shopware6, you will configure its parameters and declare the required services.
If you did the Prerequisite with Step-by-Step, you will need to declare the required Data Integration services in your plugin.
If you did the Prerequisite with All-at-Once, you will have already the default required data integration services.
Once this is done, you can integrate the Command Console services and run a full export.
If you run a full export with the option “Use Development Data Index”, then you will have a dev in dev after the full export and not a prod index. You can have two environment installed with the same account, one pushing dev data, the other one pushing prod data.
IN STEP 3, MAKE SURE TO SET THE PARAMETER DEV = TRUE IF YOU HAVE EXPORTED YOUR DATA IN DEV AND TO FALSE IF YOU HAVE EXPORTED YOUR DATA IN PROD. THE OTHER INDEX WILL BE EMPTY AND YOUR REQUESTS WILL NOT WORK!
2. Activate tracker
Follow the steps described in the section: Setup for the Framework Layer.
In these steps you will add and activate the rtux-shopware plugin, then you will configure its parameters and activate the configuration of the tracker.
We recommend you to go live once you have configured your Data Export (in production) and activated your tracker. This way, while you are working on the integration in your front-end (step 3) Boxalino will already receive your data and collect statistics!
3. Make API calls for any feature (search, recos, …) and render the response in your front-end with narrative templates
This section will greatly depends on whether you chose the Approach Step-By-Step or All-At-Once as described above.
Step-By-Step
Follow the steps described in the section: Building up the Integration Layer - Step-By-Step.
The process will vary depending on which feature you want to integrate (Search, Product Recommendations, …). However, they will always follow the same steps:
Configure in Boxalino Admin
the required Widget(s) in the first main view (you can save them with an empty strategy, it will simply mean that the products you will retrieve are not filtered or sorted in any special way).
the required Layout Blocks for each template which is involved in the rendering of the feature
the required Narratives for each required Widget(s) with the layout adapted to the
then press the test button to test with parameter test=true (or publish to test with parameter test=false)
and wait at least 5 minutes for the cache to refresh
Integrate the code to make the call to the Narrative API
Integrate the templates required to render the layout returned by the Narrative API
Default Layout Blocks and Narratives configuration are provided in the WIKI documentation of each feature, you will be able to simply import them in your admin if you don’t want to make any special changes to your templates or their layout.
All-at-Once
Follow the steps described in the section: Building up the Integration Layer - All-at-once.
The process here is primarily to configure all the required Widgets, Layout Blocks, and Narratives in one shot as all the features will be activated at once. The steps for this in the Boxalino Admin are the same as described in the Step-By-Step approach.
Important comments
In order to make sure that your integration goes smoothly, please take good notice of the following points:
Make sure that if you export your data in dev (vs prod), that you access the API with dev=true (vs false)
Make sure that you download (and rename namespace) but do not copy or clone the rtux-integration-shopware repository, even if you chose the approach “All-at-Once”. The integration layer needs to be your environment that you extend / modify and maintain.
Make sure that you do not call the API before you have configured the following aspects in the Boxalino Admin and have pressed test or publish:
Widgets (in the main view, even if you leave the configuration of the widget strategy empty), otherwise, the system will throw an error because you are calling a non-existing widget
Layout Blocks (that all the template you need have been configured in the Layout blocks, otherwise, you cannot create your Narratives (point c))
Narratives connected to Widgets of point a, as without narratives configured for the widget, your API response will be empty
Click Test (or Save&Test) and wait at least 5 minutes before using the API with the parameter test=true
Publish and wait at least 5 minutes before using the API with the parameter test=false
Setup for the Data Integration Layer https://github.com/boxalino/data-integration-shopware6
At this step we do not have to create the data synchronization strategies for the project.
Add the plugin to your project via composer
composer require boxalino/data-integration-shopware6
Activate the plugin (Shopware6 default)
./bin/console plugin:refresh
./bin/console plugin:install --activate --clearCache BoxalinoDataIntegration
Log in your Shopware admin and configure the plugin with the configurations provided for your setup
Shopware Admin >> Settings >> System >> Plugins >> Boxalino Data Integration
If the plugin configurations are not displayed, they can be accessed via direct link:
admin#/sw/plugin/settings/BoxalinoDataIntegration
Set configuration per Sales Channel and disable the plugin where it is not in use. The Headless channel must have the plugin disabled.
Use the ? icon to get information on the configurations options or check https://github.com/boxalino/data-integration-shopware6/wiki/Configurations
More information on the available data indexes available in the wiki https://github.com/boxalino/data-integration-shopware6/wiki/Data-Indexes
Add the generic services to your Integration Layer
You can skip this step if you chose the approach “All-at-Once” and want to keep the default services.the doc_product handler is the service responsible for the export of product information (as seen on https://github.com/boxalino/rtux-integration-shopware/blob/3.0.0/src/Resources/config/services/di/product.xml )
has configured a series of property handlers for different data structure export (ex: categories, stock, price, translation properties, options, image, link etc)
the doc_language handler will export the existing languages for the given sales channel (https://github.com/boxalino/rtux-integration-shopware/blob/3.0.0/src/Resources/config/services/di/language.xml )
the doc_attribute handler will export information on your product attributes (https://github.com/boxalino/rtux-integration-shopware/blob/3.0.0/src/Resources/config/services/di/attribute.xml )
the doc_attribute_value handler will export the facet options for the product attributes (https://github.com/boxalino/rtux-integration-shopware/blob/3.0.0/src/Resources/config/services/di/attribute_value.xml )
the doc_order handler is the service responsible for exporting your order information (as seen on https://github.com/boxalino/rtux-integration-shopware/blob/3.0.0/src/Resources/config/services/di/order.xml )
the doc_user handler will handle the SW6 logic for exporting user information (https://github.com/boxalino/rtux-integration-shopware/blob/3.0.2/src/Resources/config/services/di/user.xml )
Integrate the Product Export Console Command service (as seen on https://github.com/boxalino/rtux-integration-shopware/blob/3.0.0/src/Resources/config/services/di/product-console.xml )
Trigger a full data index
./bin/console boxalino:di:full:product
More options for the full data index :https://github.com/boxalino/data-integration-shopware6/wiki/Integration:-Full
A full data export has started.
The data integration will log it's process in a dedicated log ./var/log/boxalino-di-product-env.log
Proceed with the Setup of the Framework Layer.
Setup for the Framework Layer https://github.com/boxalino/rtux-shopware/wiki
Please check the requirements for using the Framework Layer repository https://github.com/boxalino/rtux-shopware/wiki/Requirements
Add the plugin to your project via composer
composer require boxalino/rtux-shopware
Activate the plugin (Shopware 6 default):
./bin/console plugin:refresh
./bin/console plugin:install --activate --clearCache BoxalinoRealTimeUserExperience
Log in your Shopware admin and configure the plugin with the configurations provided for your setup
Shopware Admin >> Settings >> System >> Plugins >> Boxalino RTUX Framework for Shopware v6
If the plugin configurations are not displayed, they can be accessed via direct link:
admin#/sw/plugin/settings/BoxalinoRealTimeUserExperience
Use the ? icon to get information on the configurations options or check https://github.com/boxalino/rtux-shopware/wiki/Configurations
Due to the JS files in the plugin (tracker, Shopware6 CMS blocks, etc), a theme compilation might be required:
./psh.phar administration:build
or./bin/build-administration.sh
./psh.phar storefront:build
or./bin/build-storefront.sh
In order to kick off your account, a full export is required.
Continue with the “Integration of the Framework Layer” steps
Integration of the Framework Layer
The API request schema has a list of properties. One of the properties is the sort property.
Before any API call/integration can be done, the ApiSortingModelInterface must be declared
Review the sorting options desired for the project
in the default guidelines, the generic Shopware6 sorting options are used (price, title, score) https://github.com/boxalino/rtux-integration-shopware/blob/2.5.2/src/Resources/config/services.xml#L31
it is possible to declare new sorting options by following the Shopware6 guidelines on adding new sorting methods
for ex: topseller https://github.com/boxalino/rtux-integration-shopware/blob/2.5.2/src/Resources/config/services.xml#L45
the frontend label (for
filter.sortTopseller
) must be added in your Shopware6 accountthe field it matches to (ex:
bq_order_count_products_group_id_all_time
) must exist in the data indexthis sample field bq_* are only available for production accounts, which go through our BigQuery ecosystem
The sorting options disclosed to the ApiSortingModel
with the use of the addSortingOptionCollection
function will only be valid for the Shopware6 views on which the content is provided from the Boxalino API.
Building up the Integration Layer - Step-By-Step
In this section, we described the building process of the integration layer with the approach described above as “Step-by-Step”.
Create & activate an empty Shopware6 plugin skeleton in your project codebase by following your project practices: in custom/plugins or vendor path
Follow the Setup for Data Integration Layer https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/349601793/Shopware+6#Setup-for-the-Data-Integration-Layer-%5BinlineCard%5D
Follow the Setup for Framework Layer https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/349601793/Shopware+6#Setup-for-the-Framework-Layer-https%3A%2F%2Fgithub.com%2Fboxalino%2Frtux-shopware%2Fwiki
At this point, the project`s Integration Layer must have a structure similar to the tag 1.0.0 in the Boxalino`s guidelines repository rtux-integration-shopware
https://github.com/boxalino/rtux-integration-shopware/tree/1.0.0
For the API requests to work, both the Data Integration Layer and the Framework Layer have the same value for the Use development data index configuration field
As mentioned in the Framework Layer Configurations wiki, when the Test mode is activated - the API request JSON is logged in the system file <root>/var/log/<env>.log, LEVEL INFO
The Boxalino API integration can start by following the recommended order :
Home slider (ex: CMS context )
PDP recommendations / Cross-selling (as seen PDP sample )
Autocomplete (the recommended Javascript approach)
Navigation (via Shopping Experience Layout)
Dynamic pages (ex: brand pages)
Every integration feature consists of:
Integration Description / About : an insight into the approach.
Steps
Layout Blocks JSON : default JSON element to be loaded in Intelligence Admin
Narratives Layout JSON : default JSON elements to be loaded in Intelligence Admin
JSON samples of both elements (layout blocks & narratives) are provided with each feature integration guidelines and can be imported in your Boxalino Intelligence Admin panel. Make sure to replace the @BoxalinoRealTimeUserExperienceIntegration namespace with the one of your project`s Integration Layer
Please be aware that the Layout Blocks, Facets & Narratives must be configured in Boxalino Intelligence Admin in order for the API requests to return any content.
Building up the Integration Layer - All-At-Once
In this section, we present the building process of the integration layer with the approach described above as “All-At-Once”. This strategy is being described in the video tutorial https://www.youtube.com/watch?v=Fl8d0MO0ub0
The rtux-integration-shopware repository must be replicated (copied, not cloned/required) ONLY if a full-feature integration baseline is desired.
Otherwise, create a simple Shopware6 plugin in your project and check the Step-by-step (recommended) approach
Create an empty Shopware6 plugin skeleton in your project codebase by following your project practices: in custom/plugins or vendor path
From a project level, require & activate the Data Integration Layer and the Framework Layer
composer require boxalino/rtux-shopware
composer require boxalino/data-integration-shopware6
./bin/console plugin:refresh
./bin/console plugin:install --activate --clearCache BoxalinoDataIntegration BoxalinoRealTimeUserExperience
Download the Boxalino Guidelines for the Integration Layer from the public repository
we recommend to download the latest available tag
Review the downloaded version composer.json
From the downloaded archive, extract the src folder
From the src folder, delete the Shopware Plugin Class
this file is specific to every plugin and your default/base Shopware6 Integration Layer Plugin already has one
Copy the src folder in your project`s Integration Layer
by doing so, you are merging the content of the Integration Guidelines in your own code-base
if your project does not require the extended features (ex: Instant Update ) - disable it`s load by commenting this imported XML
(optional) replace the /src/Resources/config/plugin.png with your agency`s icon or remove it
Change the namespace by:
replacing Boxalino\RealTimeUserExperienceIntegration with your own project`s Integration Layer namespace
Install and Activate your project`s Integration Layer plugin (Shopware6 command)
Re-compile the theme (administration and frontend)
./bin/build-administration.sh
./bin/build-storefront.sh
Configure the Data Integration Layer and Framework Layer in Shopware 6 admin
check out the Data Integration Layer Configurations wiki https://github.com/boxalino/data-integration-shopware6/wiki/Configurations
set the DI configuration per Sales Channel and disable the plugin where it is not in use
the Headless channel must have the plugins disabled
check out the Framework Layer Configurations wiki https://github.com/boxalino/rtux-shopware/wiki/Configurations
Run the data exporter command in order to initialize your account`s data index
./bin/console boxalino:di:full:product
each repository has it`s own individual logger handler; the logs are saved in boxalino-di-<type>-<env>.log files
read more on the available data indexes on the SOLR data indexes wiki page https://github.com/boxalino/data-integration-shopware6/wiki/Data-Indexes
Load the Narrative JSON Guidelines in Boxalino Intelligence Admin
ask Boxalino on the setup channel to assist
provide your project`s Integration Layer namespace
do it yourself
check out the JSON Guidelines page https://github.com/boxalino/rtux-integration-shopware/wiki/JSON-Guidelines-(Complete)
copy each JSON content in the required path from Boxalino Intelligence Admin
Menu: Advanced >> Template Resources
copy and load as they are
Menu: Merchandising >> Facets
copy and load as they are
Menu: Marketing >> Layout Block
copy the JSON structure
replace the @BoxalinoRealTimeUserExperienceIntegration namespace with your project`s Integration Layer namespace
load in Boxalino Intelligence Admin
Menu: Marketing >> Narratives
copy and load as they are
Menu: Strategies >> Touch Point Optimizers >> Search block >> click on the search widget
copy, import and save&test as they are
Per Shopware6 layout-strategy, the category uses the Shopping Experiences layouts. In order to enable navigation and edit the home page - new layouts with the narrative CMS block must be created.
check out CMS Element (for Shopping Experiences) Configurations and Practices
At this point:
the Data Integration Layer is installed and configured
the Framework Layer is installed, integrated and configured
the Integration Layer is duplicated
Integration Review
The integration process must continue, by:
Adding a CMS element on home page
check the CMS Context feature integration on wiki https://github.com/boxalino/rtux-integration-shopware/wiki/CMS-Context
Applying the recommended practices for CMS elements https://boxalino.atlassian.net/wiki/spaces/BPKB/pages/354877485/CMS+Element+for+Shopping+Experiences#Practices
Creating a new Shopware6 Shopping Experience Layout with the Boxalino CMS Element
for this, check the Navigation Context Integration steps https://github.com/boxalino/rtux-integration-shopware/wiki/Navigation-Context
Reviewing every feature`s integration
autocomplete (both client-side via JS and server fallback (optional))
product detail page recommendations
navigation (if the above Landing Pages have been configured as layouts on category)
search
sorting options
facets
Activating the tracker (https://github.com/boxalino/rtux-shopware/wiki/Tracker )
Reviewing the data integration strategies
Check out the rtux-integration-shopware WIKI https://github.com/boxalino/rtux-integration-shopware/wiki for more features guidelines or integration use-cases