PDP Context (upsell, basket, crosssell) - boxalino/rtux-integration-magento2 GitHub Wiki

Before you continue, make sure the required integration steps have been completed.

The PDP (product view) context is used in order to access recommendations customized for the product items defined as the "item contexts"(ex: crosssell, upsell, basket, etc). The content of the API response depends 100% on the layout blocks.

The content of the response depends 100% on your design and layout blocks desired.

Before testing the feature, the layout blocks & narrative layout must be defined in Boxalino Intelligence admin.

If there is no narrative assigned to the choice/widget requested, the response will be empty.

Integration description

The Layout Blocks JSON & Narrative Layout JSON sample is minimalistic (only a product_list and product item element). Following this integration, an items collection related to loaded product will be displayed. Magento2 already has the Related(Upsell, Crosssell, Promotion, Random) block which is used generically for added sections on PDP. In the provided strategy, the Layout Block uses a property "type" which is configured in the Narrative Layout by using values Magento2 template is familiar with.

  1. Strategy #2A will have a fallback to M2 blocks: will extend from Magento2 base blocks and declare new preferences for them.
  2. Strategy #2B is using virtual types. Strategy #2C is for a basket context..
  3. Strategy #2C is for the checkout CROSS-SELL block (adds all cart items as context items)

More documentation on the provided elements is available in the framework wiki.

For the guidelines bellow, the default Magento2 template is used: Magento_Catalog::product/list/items.phtml. You have to update the template to include the required API JS tracker HTML mark-ups

Steps

In order to show Boxalino product-related recommendations, the following steps are needed:

1. Implement the Boxalino RTUX API ContextInterface

On this step the ItemContext.php is created.

In the most basic integration (ex: when extending from the provided base ContextAbstract ) - only 4 functions are left to be implemented in order to set:

  • the products visibility (as filter values)
  • the products category (as filter - depends on the context)
  • the return fields (which can be set via layout XML as well)

The filters list can be changed by rewriting the addFilters(RequestInterface $request) function.

FYI: the ItemRequestDefinitionInterface must be defined on the context due to the nature of the context: product-based.

Please follow either strategy A,B or C presented bellow.

Strategy A

For this strategy the base Magento2 recommendations blocks are extended, updated and declared as preferences. (ex: Related, Crosssell, Upsell, Promotion, Random etc)

2.A Strategy A: Create the Related block

To keep things simple, the default Magento2 Related block is used as a parent in order to also ensure a safe fallback strategy. As always, the required context definition properties must be set: widget, hit count and product item id.

Because the default template is being used, it means that the $_itemCollection property must be replaced with the Narrative API response. In case there are more widget requests within the Narrative Layout definition - the collection is accessed depending on the "recommendation" type (same as it is used in the template)

3.A Update the DI

Strategy B

For this strategy 2 blocks are created:

  1. Product.php - a base
  2. View.php - used as virtual type for any PDP-view recommendation block that is required in the layout.

2.B Strategy B: Create the View block

This strategy implies to create virtual types for every recommendation type to be enabled on your layout (for the product view context).

To keep things simple, an extension of default Magento2 View block is used as a parent in order to have access to default functions. As always, the required context definition properties must be set: widget, hit count and product item id.

Because the default template is being used, it means that the getItems(), getItemCollection(), getAllItems() functions must be available.

In case there are more widget requests within the Narrative Layout definition - the collection is accessed depending on the "recommendation" type (same as it is used in the template)

3.B Declare the virtual types & update the preferences

Strategy C

This strategy is for the basket recommendations. In the Crossell.php the other products in basket are declared as context items as well.

2.C Strategy C: Create the Crosssell block

This strategy is different from the 2 above due to the fact that a list of sub-products is being set to the request.

It is extended the default Magento2 Cart Crosssell block in order to have access to default functions. As always, the required context definition properties must be set: widget, hit count and product item id.

Because the default template is being used, it means that the getItems() functions must be available.

In case there are more widget requests within the Narrative Layout definition - the collection is accessed depending on the "recommendation" type (same as it is used in the template)

3.C Declare DI

Extending the PDP narrative

With the use of the "accessor" property on the Layout Block, it is possible to request content from multiple widgets/choices. This is particularly useful for the product detail page: with one request, both similar&related&upsell&accessories content can be accessed. It is simply required to:

  1. replicate the title+product listing duo in your narrative structure
  2. set the proper "accessor"

Based on the JSON Narrative Layout provided bellow, the Upsell block can be integrated by following strategy A or strategy B.

How is this possible?

With the use of API Call registry the response can be accessed across blocks.

The block will know to access the right collection for the widget/context by checking the block property "type". This is defined in the Magento2 layout integration of the PDP recommendations.

Layout Blocks JSON

[{"id":815,"uniqueKey":"product","parametersJsonScheme":"{\n \"title\": \"Product\",\n \"type\": \"object\",\n \"properties\": {\n \"accessor\": {\n \"type\": \"string\",\n \"description\": \"hits accessor (typically leave empty)\"\n }\n }\n}","format":null,"widgets":[],"parameters":[{"name":"template","values":["BoxalinoClientProject_Boxalino Integration::api/catalog/product/list/item.phtml"]},{"name":"bx-hit","values":["accessor"]},{"name":"content-resource","values":["c-r=t"]},{"name":"name","values":["rtux_api_product_item"]},{"name":"type","values":["Boxalino\\RealTimeUserExperience\\Block\\Catalog\\Product\\ProductList\\Item\\Block"]}],"subRenderings":[],"route":"visual-elements","reqParams":null,"$fromServer":true,"parentResource":null,"restangularCollection":false,"isSelected":true},{"id":921,"uniqueKey":"pdp_recommendation_ids","parametersJsonScheme":"{\n \"title\": \"Product List\",\n \"type\": \"object\",\n \"properties\": {\n \"accessor\": {\n \"type\": \"string\",\n \"description\": \"hits accessor (typically leave empty)\"\n },\n \"type\": {\n \"type\": \"string\",\n \"description\": \"Recommendation block type (related, upsell, etc)\"\n }\n }\n}","format":null,"widgets":[],"parameters":[{"name":"bx-hits","values":["accessor"]},{"name":"model","values":["Boxalino\\RealTimeUserExperience\\Model\\Response\\Content\\ApiEntityCollection"]},{"name":"content-resource","values":["c-r=t"]},{"name":"name","values":["rtux_api_pdp_ids"]}],"subRenderings":[],"route":"visual-elements","reqParams":null,"$fromServer":true,"parentResource":null,"restangularCollection":false,"isSelected":true}]

Narrative Layout JSON (for similar/related)

[{"id":820,"status":null,"uniqueKey":"pdp","aliases":null,"widgets":["related"],"allWidgets":null,"parametersJsonScheme":null,"seoContent":{"title":[{"language":"de","value":""}],"metaTags":[],"h1":[{"language":"de","value":""}],"others":[{"name":"breadcrumbs","value":[{"language":"de","value":""}]}]},"contexts":[],"layoutModels":null,"acts":[{"parameters":[null],"chapter":{"format":"CPOActChapter","contexts":[],"subActs":[],"journeyStepUniqueKeys":null,"callToActions":null,"renderings":[{"parameters":[null],"rendering":{"contexts":[],"layoutModels":[],"visualElements":[{"visualElementModelUniqueKey":"pdp_recommendation_ids","label":"Related","parameters":[{"name":"accessor","values":[""],"value":""},{"name":"type","values":["related"],"value":"related"}],"visualElement":null,"subRenderings":[{"parameters":[null],"rendering":{"contexts":[],"layoutModels":[],"visualElements":[{"visualElementModelUniqueKey":"product","label":null,"parameters":[{"name":"accessor","values":[""],"value":""}],"visualElement":null,"subRenderings":[{"parameters":[null],"rendering":{"contexts":[],"layoutModels":[],"visualElements":[],"parameters":null}}],"startVal":{"accessor":""}}],"parameters":null}}],"startVal":{"accessor":"","type":"related"},"hiddenParams":{}},{"visualElementModelUniqueKey":"pdp_recommendation_ids","label":"Similar","parameters":[{"name":"accessor","values":["similar"],"value":"similar"},{"name":"type","values":["upsell"],"value":"upsell"}],"visualElement":null,"subRenderings":[{"parameters":[null],"rendering":{"contexts":[],"layoutModels":[],"visualElements":[],"parameters":null}}],"startVal":{"accessor":"similar","type":"upsell"},"hiddenParams":{}}],"parameters":null}}],"parameters":null}}],"parameters":[],"route":"narratives","reqParams":null,"$fromServer":false,"parentResource":null,"restangularCollection":false,"isSelected":true}]

Narrative Layout JSON (for basket)

[{"id":1014,"status":null,"uniqueKey":"basket","aliases":null,"widgets":["basket"],"allWidgets":null,"parametersJsonScheme":null,"seoContent":{"title":[{"language":"de","value":""}],"metaTags":[],"h1":[{"language":"de","value":""}],"others":[{"name":"breadcrumbs","value":[{"language":"de","value":""}]}]},"contexts":[],"layoutModels":null,"acts":[{"parameters":[null],"chapter":{"format":"CPOActChapter","contexts":[],"subActs":[],"journeyStepUniqueKeys":null,"callToActions":null,"renderings":[{"parameters":[null],"rendering":{"contexts":[],"layoutModels":[],"visualElements":[{"visualElementModelUniqueKey":"pdp_recommendation_ids","label":"Basket - Crosssell","parameters":[{"name":"accessor","values":[""]},{"name":"type","values":["crosssell"]}],"visualElement":null,"subRenderings":[{"parameters":[null],"rendering":{"contexts":[],"layoutModels":[],"visualElements":[{"visualElementModelUniqueKey":"product","label":null,"parameters":[{"name":"accessor","values":[""]}],"visualElement":null,"subRenderings":[{"parameters":[null],"rendering":{"contexts":[],"layoutModels":[],"visualElements":[],"parameters":null}}]}],"parameters":null}}]}],"parameters":null}}],"parameters":null}}],"parameters":[],"route":"narratives","reqParams":null,"$fromServer":true,"parentResource":null,"restangularCollection":false,"isSelected":true}]