Warning

This app is on alpha version, which means we are working to improve it and it is not possible to add other accounts for tests. If you have any questions, please contact our Support.

The Product Recommendation app shows a selection of products using recommendation strategies. For example, you can use the Product Recommendation to suggest often bought-together products to the one that the user is looking for.

The Product Recommendation app does not fetch user data for itself. However, most recommendation strategies require user navigation data to provide relevant suggestions to users. Hence, before proceeding any further, make sure you have an app capable of tracking user navigation installed on your VTEX account.

Make sure you have the Biggy pixel app installed on your VTEX account or install it by the following steps:

1. Open a Support ticket about your interest in installing the Recommendations Shelf and Biggy Pixel apps. You should expect an App Key as a response. Save it for the 6th step of this tutorial.
2. Using your terminal, install the biggy.pixel app by running the following command:

3. Access your VTEX account by the Admin.
4. Using the Admin's sidebar, access the Apps section and select the Biggy Pixel app.
5. Click on Settings.
6. In the apiKey field, enter the App Key provided by the VTEX team.
7. Save your changes.

1. Using your terminal, install the recommendation-resolver app on your account. This app will solve the recommendation queries of your store shelves.

2. Add the recommendation-shelf app to your theme's dependencies on the manifest.json:

Now, you can use all blocks exported by the recommendation-shelf app. Check out the complete list below:

Block name	Description
recommendation-shelf	Displays a list of recommended products on any store page.
recommendation-buy-together	Displays a list of recommended products to buy together on the product details page.
recommendation-refresh	Displays a list of recommended products based on the user history on your store pages.

recommendation-shelf

An error occurred while loading the image https://raw.githubusercontent.com/vtex-apps/recommendation-shelf/master/docs/image%20(31).png

recommendation-buy-together

An error occurred while loading the image https://raw.githubusercontent.com/vtex-apps/recommendation-shelf/master/docs/image%20(32).png

recommendation-refresh

An error occurred while loading the image https://raw.githubusercontent.com/vtex-apps/recommendation-shelf/master/docs/Screenshot_3.png

3. Add the recommendation-shelf app to your store template. See the example below to know how to add it to a template:

You can add the recommendation-shelf in any store template desired, such as the store.home or store.product. You can also add the recommendation-buy-together and recommendation-refresh blocks if desired. For example:

To configure the recommendation-shelf you will need to add props to it. Check the following tables to know what props that the app includes and how to configure them.

Prop name	Type	Description	Default value
strategy	enum	Strategy used to fetch and display the recommended products. Check all possible values in the table below.	BEST_SELLERS
secondaryStrategy	enum	Secondary strategy used to fetch and display the recommended products if the initial strategy does not return results. This prop is optional. Check all possible values in the table below.	BEST_SELLERS
recommendation	object	Settings for the recommendation shelf component. Here you can define the total and the minimum number of recommendations that should be fetched	Check the recommendation props

Strategy	Description
BEST_SELLERS	Fetches and displays the best seller products.
MOST_POPULAR	Fetches and displays the most popular products.
PRICE_REDUCTION	Fetches and displays products with reduced prices.
NEW_RELEASES	Fetches and displays the latest released products.
NAVIGATION_HISTORY	Fetches and displays products based on the user's navigation history.
SIMILAR_PRODUCTS	Fetches and displays recommendations based on the similarity of products on the currently displayed product. This prop only works in the theme template store.product and store.search.
BEST_CHOICE	Fetches and displays the most visited and ordered products based on the similarity of products on the currently displayed product page. This prop only works in the theme template store.product and store.search.
BOUGHT_TOGETHER	Fetches and displays recommendations for products often bought together based on the similarity of products on the currently displayed product page. This prop only works in the theme template store.product and store.search.
RECOMMENDATION_HISTORY	Fetches and displays the most relevant products based on a specific customer history.
CART_HISTORY	Fetches and displays products based on the user's cart history.
ORDER_HISTORY	Fetches and displays products based on the user's order history.

See the example below to know how to add it to your template:

For each strategy and secondaryStrategy, you can apply props to specific pages. The possible page types are in the table below:

Page type	Description	Available to the strategy and secondaryStrategy
HOME	Recommendations are displayed on the Home page. This context selects the recommended products based on the last categories viewed by the user. If there is no past data from the user, it returns the store data.	BEST_SELLERS, MOST_POPULAR, PRICE_REDUCTION, NEW_RELEASES, NAVIGATION_HISTORY, RECOMMENDATION_HISTORY, ORDER_HISTORY
PLP	Recommendations are displayed on the Product List Page. This context uses the category of the first products on the list to select the recommended products.	BEST_SELLERS, MOST_POPULAR, PRICE_REDUCTION, NEW_RELEASES, NAVIGATION_HISTORY, RECOMMENDATION_HISTORY, ORDER_HISTORY, SIMILAR_PRODUCTS , BEST_CHOICE , RECOMMENDATION_HISTORY
PDP	Recommendations are displayed on the Product Description Page. This context uses the product information as a param to select the recommended products.	BEST_SELLERS, MOST_POPULAR, PRICE_REDUCTION, NEW_RELEASES, NAVIGATION_HISTORY, RECOMMENDATION_HISTORY, ORDER_HISTORY, SIMILAR_PRODUCTS, BEST_CHOICE, BOUGHT_TOGETHER, RECOMMENDATION_HISTORY
CART	Recommendations are displayed on the Cart page. This context uses the product category in the cart as a param to select the recommended products.	CART_HISTORY, SIMILAR_PRODUCTS
OTHERS	Recommendations are displayed on the other store pages, such as My Account. This context will return the store data or user’s navigation history.	BEST_SELLERS, MOST_POPULAR, PRICE_REDUCTION, NEW_RELEASES, NAVIGATION_HISTORY, RECOMMENDATION_HISTORY, ORDER_HISTORY

Prop name	Type	Description	Default value
count	object	Defines the total and the minimum number of recommendations that should be fetched.	\{"minimum": 5, "recommendations": 20\}

Prop name	Type	Description	Default value
minimum	number	Defines the minimum recommendations that should be fetched.	5
recommendations	number	Defines the total number of recommendations that should be fetched.	20

See the example below to know how to add it to your template:

To configure the recommendation-buy-together you will need to add props to it. Check the following tables to know what props that the app allows and how to configure them.

The only possible value for strategy is BOUGHT_TOGETHER.

Prop name	Type	Description	Default value
recommendation	object	Settings for the recommendation shelf.	undefined

Prop name	Type	Description	Default value
count	object	Defines the total and the minimum number of recommendations that should be fetched.	\{minimum: 5, recommendations: 20\}

Prop name	Type	Description	Default value
minimum	number	Defines the minimum recommendations that should be fetched.	5
recommendations	number	Defines the total number of recommendations that should be fetched.	20

To configure the recommendation-refresh you will need to add props to it. Check the following tables to know what props that the app allows and how to configure them.

Prop name	Type	Description	Default value
strategy	enum	Strategy used to fetch and display the recommended products. Possible values can be found in the table below.	RECOMMENDATION_HISTORY
secondaryStrategy	enum	Secondary strategy used to fetch and display the recommended products if the initial strategy does not return results. Possible values can be found in the table below.	RECOMMENDATION_HISTORY
recommendation	object	Settings for the recommendation shelf.	undefined

Strategy	Description
RECOMMENDATION_HISTORY	Fetches and displays products based on the user's navigation history.
CART_HISTORY	Fetches and displays products based on the user's cart history.
ORDER_HISTORY	Fetches and displays products based on the user's order history.

Prop name	Type	Description	Default value
count	object	Defines the total and the minimum number of recommendations that should be fetched.	\{minimum: 5, recommendations: 20\}

Prop name	Type	Description	Default value
minimum	number	Defines the minimum recommendations that should be fetched.	5
recommendations	number	Defines the total number of recommendations that should be fetched.	20

You can customize the blocks recommendation-shelf, recommendation-refresh, and recommendation-buy-togetherby adding the shelf-components app to your theme's dependencies on the manifest.json file:

Now it is possible to customize these blocks, building their components by using its children blocks default-shelf, refresh-shelf, and buy-together, respectively.

Below, you can find an implementation example for each one of them. If needed, use these blocks in your store theme code and make the desired changes according to your needs:

No CSS Handles are available yet for the app customization.