Magento 2
- 1 Introduction
- 1.1 Prerequisites:
- 1.1.1 Step-by-step (recommended):
- 1.1.2 All-at-once:
- 1.2 1. Declare the data integration (DI) services and run a full export
- 1.3 2. Activate tracker
- 1.4 3. Make API calls for any feature (search, recos, …) and render the response in your front-end with narrative templates
- 1.4.1 Step-By-Step
- 1.4.2 All-at-once
- 1.1 Prerequisites:
- 2 Important comments
- 3 Setup for the Data Integration Layer
- 4 (legacy) Setup for the Data Exporter Layer
- 5 Setup for the Framework Layer https://github.com/boxalino/rtux-magento2/wiki
- 5.1 Integration of the Framework Layer
- 5.1.1 Sorting
- 5.1.2 Response Registry
- 5.1.3 Facet delimiters
- 5.2 Integration of the API JS Tracker
- 5.1 Integration of the Framework Layer
- 6 Building up the Integration Layer - Step-By-Step
- 7 Building up the Integration Layer - All-At-Once
Introduction
Boxalino Winning Interactions Platform provides many Magento 2 features, 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-magento2 | a standard Magento2 plugin responsible to export Magento data to Boxalino | To be replaced by the Data Integration repository |
a Magento2 plugin responsible to export the eshop data following the Boxalino Data Structure | Install and update when Boxalino provides a new version | |
a standard Magento2 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) Magento2 plugin provided to examplify 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-magento2).
Prerequisites:
The intent of integrating the Boxalino API on a Magento 2 environment requires building a new repository/module in the Magento 2 project which will represent the Integration Layer.
There are 2 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-magento2 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 that you don’t implement any code that is not needed (you can always add it later).
In this case, just create a new Magento 2 module from scratch, known as your project`s Integration Layer (ex: namespace BoxalinoClientProject\BoxalinoIntegration
) as an empty module (you will need it in the next step to have a place to activate the tracker).
Follow the official Magento 2 guidelines for how to create a new module (ex: https://devdocs.magento.com/guides/v2.4/architecture/archi_perspectives/components/modules/mod_intro.html)
All-at-once:
In this case, you download (BUT DO NOT COPY/REQUIRE OR CLONE!) the rtux-integration-magento2 as a basis for your plugin (and then rename namespace) . 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.
1. Declare the data integration (DI) services and run a full export
Follow the steps described in the section: Setup for the Data Integration Layer.
Follow the steps described in the section: Setup for the Data Exporter Layer.
In these steps, after adding and activating the data-integration-magento2 module, you will configure its parameters, declare the required services and run a full export.
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-magento2 module, then you will configure its parameters and integrate the tracker.
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
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-magento2 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-magento2
Add the plugin to your project via composer
composer require boxalino/data-integration-magento2
Activate the plugin (Magento 2 default)
php bin/magento module:enable Boxalino_DataIntegration
Log in your Magento admin and configure the module with the configurations provided for your setup
Magento 2 Admin >> Stores >> Configuration >> Boxalino Data Integration
Set configuration per Website and disable the module where it is not in use.
each language (Store View) will be exported individually and is unique per data index (Boxalino account)
Configuration options description is available under each field or in the wiki https://github.com/boxalino/data-integration-magento2/wiki/Configurations
Add the generic services to your Integration Layer`s di.xml
https://github.com/boxalino/rtux-integration-magento2/blob/3.2.0/etc/di_config/di-full.xml copy this content in your project`s di.xml
full available description of the full sync available on wiki https://github.com/boxalino/data-integration-magento2/wiki/Integration:-Full
Trigger a full data index
php bin/magento boxalino:di:full:product <account_name>
More options for the full data index : https://github.com/boxalino/data-integration-magento2/wiki/Integration
Proceed with the Setup of the Framework Layer
(legacy) Setup for the Data Exporter Layer https://github.com/boxalino/exporter-magento2
Add the plugin to your project via composer
composer require boxalino/exporter-magento2
Activate the plugin (Magento 2 default)
php bin/magento module:enable Boxalino_Exporter
Log in your Magento admin and configure the module with the configurations provided for your setup
Magento 2 Admin >> Stores >> Configuration >> Boxalino Exporter
Set configuration per Website and disable the plugin where it is not in use.
each language (Store View) will be exported individually and is unique per data index (Boxalino account)
Configuration options description is available under each field or in the wiki https://github.com/boxalino/exporter-magento2/wiki/Configurations
More information on the available data indexes available in the wiki https://github.com/boxalino/exporter-magento2/wiki/SOLR-data-indexes
Trigger a full data index
php bin/magento indexer:reindex boxalino_exporter
More options for the full data index : https://github.com/boxalino/exporter-magento2/wiki/Full-data-sync
Proceed with the Setup of the Framework Layer
Setup for the Framework Layer https://github.com/boxalino/rtux-magento2/wiki
Add the plugin to your project via composer
composer require boxalino/rtux-magento2
Activate the module (Magento 2 default):
php bin/magento module:enable Boxalino_RealTimeUserExperience
the module contains JS files as well (build the theme)
Log in your Magento 2 admin and configure the module with the configurations provided for your setup
Magento 2 Admin >> Stores >> Configurations >> Boxalino API
Check the information on each configuration option in your admin view or in the wiki https://github.com/boxalino/rtux-magento2/wiki/Configurations
Make sure to use the proper configuration for the “Use Development Data Index” property
if true , the Data Integration Layer must be linked to the Data Index : Development
if false, the Data Integration Layer must be linked to the Data Index : Production
In order to kick off your account, a full export is required (step #5 from “Setup for the Data Integration Layer“)
Continue with the “Integration of the Framework Layer” steps
Continue with the “Integration of the API JS Tracker” step
Integration of the Framework Layer
Sorting
The API request schema has a list of properties. One of the properties is the sort property.
Review the sorting options desired for the project
in the default guidelines, the generic Magento2 sorting options are used (price, title, relevance) https://github.com/boxalino/rtux-integration-magento2/blob/master/etc/di.xml#L15
more information about the sorting : https://github.com/boxalino/rtux-integration-magento2/wiki/Sorting
It is possible to declare new sorting options by adding new definitions in the collection
the label property must exist in your translation files
Response Registry
As the name suggests, this data element is used to store the API response and access it within your integration scopes (ex: a single request for search, and data used for more layout blocks – facets & listing)
Declare the desired data objects for the interfaces
Facet delimiters
The facetValueDelimeter is a configured property used for the facet options join (in the URL)
Declare the desired character to be used as facet delimiter
https://github.com/boxalino/rtux-integration-magento2/blob/master/etc/di.xml#L52
it is used in the base ApiFacet Model which is recommended for the model property of the facet_navigation_api Layout Block
Integration of the API JS Tracker
The Boxalino API JS tracker must be activated ahead of any front-end integration. Together with the Data Exporter & Framework Layer, it will constitute the minimum requirements for a non-API go-live which will allow Boxalino to create relevant statistics for enabling other features (recommendations, textual suggestions, etc)
Check the HTML Template Requirements
Follow the tracker integration guidelines
the rtux-magento2 provides the base events track JS
the rtux-magento2 provides the observers for order & login track
base elements from rtux-magento2 are only used when integrated in the Integration Layer module
Test the tracker integration with the help of the Tracker Check List JS Tracker Check-List
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 & enable your project`s Integration Layer Magento 2 module
Follow the Setup for Framework Layer Magento 2 | Setup for the Framework Layer https://github.com/boxalino/rtux magento2/wiki
3. Follow the Setup for Data Integration Layer
The Boxalino API integration can start by following the recommended order :
Data Integration / Exporter (daily full export; delta per project requirements)
Home slider (ex: CMS context )
PDP recommendations / Cross-selling (as seen PDP sample )
Autocomplete (the recommended Javascript approach)
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
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”.
From a project level, require & enable the Data Integration Layer and the Framework Layer
composer require boxalino/rtux-magento2
composer require boxalino/data-integration-magento2
php bin/magento module:enable Boxalino_RealTimeUserExperience Boxalino_DataIntegration
Download the Boxalino Guidelines for the Integration Layer
we recommend to download the latest available tag/version or the one recommended for your Magento 2 version
From the downloaded archive, copy the content in your project`s Integration Layer module
Change the namespace by:
replacing BoxalinoClientProject\BoxalinoIntegration with your own project`s Integration Layer namespace
replacing the BoxalinoClientProject_BoxalinoIntegration with your own project namespace
update/replace the registration.php based on what is defined in your Integration Layer composer.json
update your project`s Integration Layer composer.json:
dependencies (as seen on https://github.com/boxalino/rtux-integration-magento2/blob/master/composer.json )
psr-4 (to match the registration.php declaration )
copy the content of the di-full.xml in your project`s di.xml (to activate the command for full data syncs for products, users & transactions)
Activate your project`s Integration Layer module (Magento 2
php bin/magento module:enable
command)Generic Magento2 deployment events (flush cache / run setup:upgrade / setup:di:compile / setup:static-content:deploy depending on your project practices)
Configure the Data Integration Layer and Framework Layer
check out the Framework Layer Configurations wiki https://github.com/boxalino/rtux-magento2/wiki/Configurations
check out the Data Integration Layer Configurations wiki https://github.com/boxalino/data-integration-magento2/wiki/Configurations
set the data integration configuration per Website and disable the plugin where it is not in use
the language (Store View) must be unique in the Website, otherwise, multiple Boxalino-accounts are needed
Run the data exporter command in order to initialize your account`s data index
php bin/magento boxalino:di:full:product <account_name>
read more on the available data indexes on the SOLR data indexes wiki page https://github.com/boxalino/data-integration-magento2/wiki/Data-Indexes
you can review the status of your data sync request with the use of our service https://github.com/boxalino/data-integration-magento2/wiki/Sync-Status-Review
Load the Boxalino Intelligence Admin configurations for a narrative API setup
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-magento2/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 BoxalinoClientProject_BoxalinoIntegration namespace with your project`s Integration Layer namespace
load in Boxalino Intelligence Admin
Menu: Marketing >> Narratives
copy and load as they are
The tracking, navigation, search, autocomplete, pdp recommendations will be replaced immediately
if there are other modules rewriting/extending Magento 2 behaviors - check for conflicts