User Guide - Magento 2 AI Product Recommendation

User Guide

Welcome to Magehq Docs

AI Product Recommendation for Magento 2 – User Guide

1. Introduction

MageHQ AI Product Recommendation for Magento 2 helps merchants display relevant product suggestions throughout the customer journey.

The extension can use AI-powered recommendations, local vector search, Google Vertex AI, recommendation rules, manual products, and fallback strategies to help customers discover suitable products faster.

Recommendations can be displayed on:

  • Product pages
  • Category pages
  • Cart page
  • Home page
  • CMS blocks
  • Checkout success page

The extension supports Magento Luma and Hyvä storefronts.

2. Main Features

  • AI-powered product recommendations
  • MageHQ AI Commerce connection
  • Direct AI provider connection
  • Local vector search
  • Optional Google Vertex AI integration
  • Flexible recommendation rules
  • Store view and customer group targeting
  • Product condition filtering
  • Manual fallback products
  • Trending and rule-based fallback products
  • Accuracy filtering
  • Minimum similarity score
  • Slider and grid layouts
  • Responsive recommendation cards
  • Add to Cart, Wishlist, and Compare
  • Configurable product handling
  • Luma and Hyvä compatibility
  • Recommendation analytics dashboard
  • Impression, click, and Add to Cart tracking
  • Server-side event deduplication
  • Tracking rate limiting
  • Order and revenue attribution support
  • Recommendation source and placement reporting

3. System Requirements

Before installing the extension, make sure your store meets the following requirements:

  • Magento Open Source or Adobe Commerce 2.4.x
  • PHP version supported by your Magento installation
  • Cron configured and running
  • Magento Admin access
  • Composer or manual module installation access
  • MageHQ AI Commerce modules when using the MageHQ API connection mode
  • A valid Google Cloud account when using Google Vertex AI

Google Vertex AI is optional and may generate additional Google Cloud charges.

4. Installation

4.1 Upload the Extension

Upload the extension files to:

 
app/code/Magehq/AIProductRecommendation
 

Install any required MageHQ dependency modules included with your package.

4.2 Enable the Module

Run the following commands from the Magento root directory:

 
php bin/magento module:enable Magehq_AIProductRecommendation
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush
 

For developer mode, static content deployment may not always be required.

4.3 Confirm the Module Status

Run:

 
php bin/magento module:status Magehq_AIProductRecommendation
 

The module should appear under the enabled modules list.

5. Accessing the Extension

After installation, log in to the Magento Admin Panel.

Navigate to:

 
MageHQ > AI Product Recommendations
 

The menu may include:

  • Dashboard
  • Recommendation Rules
  • Settings
  • Logs or analytics-related pages, depending on the installed version

General configuration is also available under:

 
Stores > Configuration > MageHQ Extensions > AI Product Recommendation
 

6. General Configuration

Go to:

 
Stores > Configuration > MageHQ Extensions > AI Product Recommendation
 

Select the required website or store view before saving store-specific configuration.

6.1 Enable the Extension

Set:

 
Enable AI Product Recommendation = Yes
 

When disabled, recommendation blocks are not displayed on the storefront.

6.2 Recommendation Count

Set the default number of products returned by a recommendation block.

Example:

 
Recommendation Count = 8
 

A rule-specific product limit can override this value.

When the product limit in a rule is set to 0, the extension uses the global recommendation count.

6.3 Cache Lifetime

Set the amount of time recommendation results can remain cached.

Caching helps recommendations appear faster and reduces unnecessary calls to external AI services.

After changing recommendation configuration, clear the Magento cache:

 
php bin/magento cache:flush
 

7. Connection Mode

The extension can support different recommendation providers.

Available connection modes may include:

  • MageHQ AI Commerce API
  • Direct Provider API
  • Local Vector Search
  • Google Vertex AI
  • Rule and fallback-only mode

The exact options depend on the installed MageHQ AI modules and extension version.

7.1 MageHQ AI Commerce API

Select this mode when your store uses the MageHQ AI Commerce service.

Make sure:

  • MageHQ AI Commerce Client is installed
  • Subscription or license configuration is valid
  • The store can connect to the MageHQ API
  • The required plan has access to AI Product Recommendation

Use the available connection test before enabling the feature on a production storefront.

7.2 Direct Provider Mode

Select Direct Provider mode when you want Magento to connect directly to a supported AI provider.

Enter the required API credentials and provider settings.

Credentials are processed on the server and must not be exposed in frontend HTML, JavaScript, or public API responses.

7.3 Local Vector Search

Local Vector Search can be used as:

  • The main recommendation source
  • A fallback source
  • An alternative when an external provider is unavailable

Local vector recommendations depend on available product embeddings and catalog indexing.

If recommendations are empty, confirm that product embeddings have been generated and are up to date.

8. Google Vertex AI Configuration

Google Vertex AI is optional.

Go to the Google Vertex AI section in the module configuration.

8.1 Enable Google Vertex AI

Set:

 
Google Vertex AI Enable = Yes
 

Only enable this option after entering valid Google Cloud configuration.

8.2 Google Cloud Project ID

Enter your Google Cloud project ID.

Example:

 
my-google-cloud-project
 

8.3 Google Cloud Location

Enter the Google Cloud location used by the configured service.

Example:

 
global
 

or a supported regional location.

8.4 Vertex AI Catalog ID

Enter the catalog identifier configured in Google Cloud.

Example:

 
default_catalog
 

8.5 Vertex AI Placement ID

Enter the placement identifier used for prediction requests.

8.6 Vertex AI Serving Config ID

Enter the serving configuration identifier when the configured Google service uses serving configurations.

8.7 Service Account JSON

Paste the complete Google Cloud Service Account JSON.

The JSON normally contains fields such as:

 
project_id
client_email
private_key
token_uri
 

Security recommendations:

  • Do not share the Service Account JSON publicly.
  • Do not place it in frontend code.
  • Use a service account with only the required permissions.
  • Rotate credentials if they are exposed.
  • Never include the private key in support screenshots.

8.8 Sync Products to Vertex AI

Enable this setting when product catalog information should be synchronized with Google.

Product sync may be performed through cron, queue processing, or a manual synchronization action, depending on the module version.

8.9 Sync Customer Events

Enable this setting when supported customer activity should be sent to Google for recommendation processing.

Review your privacy policy and applicable data protection requirements before enabling customer event synchronization.

8.10 Use Vertex AI Prediction API

Enable this option to request recommendation results from the configured Google prediction service.

8.11 Fallback to Local Vector Search

Set:

 
Fallback to Local Vector Search if Vertex Fails = Yes
 

This allows the extension to continue returning recommendations when the Google service is unavailable or returns no usable results.

8.12 Test the Connection

Click the available Test Connection button.

A successful test should validate:

  • Service Account JSON
  • OAuth token generation
  • Google API connectivity
  • Project and location configuration
  • Catalog, placement, or serving configuration where applicable

A connection test may generate a small Google Cloud API charge.

9. Accuracy Configuration

Accuracy controls help determine which AI recommendations are displayed.

9.1 Enable Accuracy Filtering

Set:

 
Enable Accuracy Filtering = Yes
 

When enabled, products below the configured minimum similarity threshold are excluded from AI results.

9.2 Minimum Match Score

Enter the minimum accepted match score.

Example:

 
0.50
 

This represents a 50% minimum similarity threshold when the provider returns normalized scores between 0 and 1.

The supported score range depends on the selected recommendation provider.

9.3 Allow Fallback Products

Enable fallback products when you want the block to remain visible even if no AI result reaches the required score.

Possible fallback sources include:

  • Manual fallback products
  • Rule-based fallback
  • Trending products
  • Local vector search
  • Catalog fallback

9.4 Debug Mode

Enable Debug Mode only while testing.

Debug Mode can display information such as:

  • AI Similarity
  • Recommendation source
  • Trending popularity score
  • Match reason
  • Fallback reason
  • Minimum score status

Disable Debug Mode on production storefronts unless this information is intentionally visible.

When Debug Mode is disabled, score and fallback debugging information should not appear on the storefront.

10. Display Configuration

The extension supports slider and grid presentation modes.

10.1 Slider Mode

Slider mode displays products in a responsive carousel.

Available options may include:

  • Products visible on desktop
  • Products visible on tablet
  • Products visible on mobile
  • Previous and next arrows
  • Pagination dots
  • Autoplay
  • Autoplay interval
  • Infinite loop

Use slider mode when many recommendations need to fit into a compact section.

10.2 Grid Mode

Grid mode displays products in a responsive product grid.

Use grid mode when all recommended products should be visible without carousel navigation.

10.3 Product Card Content

Recommendation cards can display:

  • Product image
  • Product name
  • Price
  • Special price
  • Review summary
  • Product swatches
  • Add to Cart
  • Wishlist
  • Compare
  • Choose Options

The available actions depend on the product type, theme, Magento configuration, and customer permissions.

11. Creating a Recommendation Rule

Go to:

 
MageHQ > AI Product Recommendations > Recommendation Rules
 

Click:

 
Add New Rule
 

11.1 Rule Information

Enter a descriptive rule name.

Example:

 
Product Page Similar Products
 

Set:

 
Status = Enabled
 

Disabled rules are not used on the storefront.

11.2 Store Views

Select the store views where the rule should be active.

Choose All Store Views only when the same rule should apply across the entire Magento installation.

11.3 Customer Groups

Select the customer groups that can receive recommendations from the rule.

Examples:

  • NOT LOGGED IN
  • General
  • Wholesale
  • Retailer

Make sure NOT LOGGED IN is selected when recommendations should be visible to guest customers.

11.4 Placement

Select where the rule should be displayed.

Possible placements include:

Product Page

Displays recommendations in the product detail page.

Common recommendation types:

  • Similar products
  • Frequently viewed together
  • Related alternatives
  • Complementary products

Cart Page

Displays recommendations based on products currently in the shopping cart.

Common uses:

  • Cross-sell products
  • Accessories
  • Frequently bought together products
  • Cart-value improvement

Category Page

Displays recommendations within a category page.

Common uses:

  • Trending products
  • Popular items
  • Personalized category suggestions

Home Page

Displays recommendations on the store home page.

Common uses:

  • Trending products
  • Personalized recommendations
  • Recently popular products
  • Featured AI suggestions

CMS Block

Allows recommendations to be inserted into a supported CMS location or configured block.

Checkout Success Page

Displays additional product suggestions after an order has been placed.

This placement is useful for future purchases and product discovery.

11.5 Recommendation Type

Select the recommendation type available for the selected placement.

The available options depend on the provider and module version.

Examples may include:

  • Similar Products
  • Frequently Bought Together
  • Trending Products
  • Personalized Products
  • Cart Recommendations
  • Related Products

11.6 Date From and Date To

Use these fields to schedule the rule.

Example:

 
Date From = November 20
Date To = November 30
 

The rule is only active during the configured period.

Leave both fields empty to keep the rule active without a date restriction.

11.7 Sort Order

Enter a sort order when multiple rules can match the same placement.

Lower values normally receive higher priority.

Example:

 
Sort Order = 10
 

11.8 Number of Products

Enter the maximum number of recommended products returned by the rule.

Example:

 
Number of Products = 6
 

Set it to 0 to use the global recommendation count.

11.9 Display Mode

Select:

 
Slider
 

or:

 
Grid
 

The selected mode applies to products returned by the rule.

12. Product Conditions

Product conditions control when a rule is eligible and which products can be recommended.

Depending on the rule implementation, conditions may be based on:

  • Category
  • SKU
  • Product type
  • Attribute set
  • Price
  • Brand
  • Manufacturer
  • Stock status
  • Product attributes
  • Current product context

Example condition:

 
Category is one of Accessories
 

Another example:

 
Brand equals MageHQ Brand
 

Use product conditions carefully. An overly restrictive condition can result in no recommendation products.

After editing conditions, save the rule and clear recommendation cache where required.

13. Manual Fallback Products

Manual fallback products are displayed when the primary recommendation source returns no usable result.&

Copyright © 2024 MageHQ