Installation
Before installing the extension, please make sure to Backup your web directory and store database
You will require to install MageDelight Base Extension first. If it is not installed then please download it from https://www.magedelight.com/pub/extensions/magedelight-base.zip and unzip the package file into the root folder of your Magento 2 installation.
Root Directory is - "app/code/magedelight/#YourExtensionName#"
- Unzip the extension package file into the root folder of your Magento 2 installation.
- Connect to SSH console of your server:
- Navigate to the root folder of your Magento 2 setup
Run command as per below sequence,
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy
php bin/magento cache:clean
- log out from the backend and log in again
If you are using Magento 2.3 or later then you do not need to activate license. Extension will be activated with silent activation mechanism and does not require activation keys to be entered manually.
Installation with Composer
Composer repository using this command:
composer config repositories.magedelight-repo composer https://packages.magedelight.com/
Replace repo public key and private key with your public and private key
composer config http-basic.gitlab.magedelight.com $PUBLIC_KEY $PRIVATE_KEY
composer require mage_delight/vertex_ai_recommendations_module
composer require mage_delight/module-vertex-ai-recommendations-sample-data
To obtain your public and private keys, please navigate to the "My Account" section. In the "Download Extension Packages" tab, you will find the keys available for your access.
Backend Configuration (Admin side)
| Field | Description |
|---|---|
| Enabled | Enables or disables the AI Product Recommendation module for the selected store view. When set to Yes, the extension activates synchronization with Google Vertex AI and allows recommendation models to be used on the storefront. When set to No, all AI-based recommendation functionality will be disabled for that scope. |
| Show Products | Defines the maximum number of recommended products that will be displayed in each recommendation block on the storefront. The value must be between 1 and 10. Adjusting this value allows merchants to control the number of AI-generated product suggestions shown to customers. |
| Product Attributes | Allows administrators to select additional Magento product attributes that should be exported and synchronized with Google Vertex AI. These attributes enrich the catalog data used by the AI models to generate more accurate and context-aware recommendations. By default, SKU and Manufacturer (mapped as Brand) are always included in the export. Adding more attributes such as category, color, size, or description improves recommendation accuracy. |
| Tracked User Events | Specifies which storefront user interactions should be tracked and sent to Google Vertex AI for model training and personalization. These events help the AI engine understand customer behavior patterns and generate more relevant recommendations. Supported events include actions such as Home Page View, Category Page View, Product Detail Page View, Add to Cart, Remove From Cart, Shopping Cart Page View, Purchase Complete, and Search. Tracking these events ensures continuous learning and optimization of recommendation models. |
| Field | Description |
|---|---|
| Primary AI Provider | Specifies the main AI service provider used to generate product recommendations for the store. In this configuration, Google Vertex AI is selected as the primary provider, enabling the extension to utilize Google's machine learning models for delivering personalized product suggestions based on customer behavior and catalog data. |
| Embedding Provider | Allows administrators to select a provider responsible for generating product embeddings used by the AI recommendation models. By default, this is set to Google Vertex AI. If left unchanged, the system will use the same provider configured in the Primary AI Provider setting. This option is useful when merchants want to override the embedding service with a different AI provider. |
| Test AI Providers | This button verifies the connection between Magento and the configured AI providers. When clicked, the system performs a connection test to ensure the AI service credentials and configuration are valid and that Magento can successfully communicate with the AI provider. This helps administrators confirm that the integration with Google Vertex AI is properly configured before enabling recommendation features on the storefront. |
| Field | Description |
|---|---|
| Google Cloud Project ID | Enter the Google Cloud Project ID associated with your Google Cloud account where Vertex AI Search for Commerce is configured. This project ID allows the Magento extension to connect with your Google Cloud environment and access the AI recommendation services. |
| Location | Specifies the Google Cloud region or location where the Vertex AI services are deployed. The default value is global, which is recommended for most implementations as it allows Vertex AI to operate across multiple regions for optimal performance and availability. |
| Catalog ID | Defines the Vertex AI catalog identifier used for storing and managing product data within Google Cloud. By default, this value is set to default_catalog, which represents the primary catalog where Magento product data will be synchronized and used for training recommendation models. |
| Branch ID | Select the catalog branch used for managing product imports and recommendation serving. Branches help manage different versions of catalog data within Vertex AI. Options such as Branch 0, Branch 1, and Branch 2 allow administrators to control which catalog branch is used for product synchronization and recommendation generation. |
| Set as Serving Branch | This action sets the selected Branch ID as the default serving branch used by the Vertex AI Predict and Search APIs. Once set, all recommendation queries will retrieve results from this branch. A confirmation prompt may appear before applying the change to prevent accidental switching. |
| Service Account JSON | 1. Navigate to Service Accounts
2. Create the Service Account
3. Generate the JSON Key
Paste the Google Cloud Service Account JSON key generated from your Google Cloud Console. This credential allows Magento to securely authenticate with Google Cloud APIs and perform operations such as product catalog synchronization, event tracking, and retrieving AI-powered product recommendations. |
| Field | Description |
|---|---|
| Clear Vertex AI Cache | This option allows administrators to manually clear the cached recommendation data generated by the Vertex AI integration for the current store. Clicking the Clear Vertex AI Cache button removes stored recommendation responses so that the system fetches fresh results from Google Vertex AI. This is useful when catalog data, configuration settings, or recommendation models have been updated and you want the storefront to reflect the latest AI-generated recommendations immediately. |
| Cache Lifetime (hours) | Defines the duration (in hours) for which AI-generated product recommendations are cached before being refreshed. Acceptable values range from 1 to 168 hours. Lower values ensure more real-time recommendations, while higher values improve performance by reducing API calls to Vertex AI. |
| Field | Description |
|---|---|
| Auto-Delete Old Logs | Enables or disables automatic deletion of event sync logs using a cron job. When enabled, the system will periodically remove logs that exceed the defined retention period to prevent unnecessary data accumulation. |
| Delete Logs Older Than (Days) | Specifies the number of days after which event sync logs will be deleted. Logs with a
the cron job. For example, setting this to 7 will delete logs older than 7 days. |
| Cleanup Frequency | Defines how often the cron job runs to clean up old event sync logs. Options typically include daily or other scheduled intervals, allowing control over how frequently log maintenance occurs. |
| Cleanup Time of Day | Specifies the exact time when the cleanup cron job will execute. This allows administrators to schedule log deletion during off-peak hours to minimize system impact and ensure optimal performance. |
| Field | Description |
|---|---|
| Enable Cron | Enables or disables the cron job responsible for refreshing the Vertex AI model status metadata. When enabled, the system automatically updates the model status based on the defined schedule to ensure accurate and up-to-date recommendation behavior. |
| Frequency | Defines how often the cron job runs to refresh the Vertex AI model status. Options such as daily allow administrators to control how frequently the system checks and updates model metadata. |
| Time of Day | Specifies the exact time when the cron job will execute. This allows scheduling of model status updates during off-peak hours to minimize performance impact and ensure smooth system operation. |
| Field | Description |
|---|---|
| Sync Customer Data | Exports customer demographic data from Magento to Google Vertex AI. This data helps the AI models understand customer segments and improve personalization for product recommendations. |
| Sync Products | Synchronizes the Magento product catalog with Vertex AI. Product information such as SKU, title, categories, and selected attributes is exported so the AI engine can analyze catalog data and generate accurate recommendations. |
| Sync Add to Cart Events | Exports Add to Cart activity and quote data to Vertex AI. These behavioral signals help the AI model understand customer purchase intent and improve recommendations like Frequently Bought Together. |
| Sync Orders | Sends historical order and purchase data to Vertex AI. This information is used to identify buying patterns and train recommendation models such as Buy It Again and Frequently Bought Together. |
| Generate Detail Page Views | Generates and exports Product Detail Page view events to Vertex AI. These events are required for training recommendation models such as Recommended for You or Others You May Like. A minimum number of events (typically 10,000 or more) is recommended for accurate AI training. |
| Generate Home Page Views | Generates Home Page view events and sends them to Vertex AI. These events help train AI models used for homepage personalization and product discovery recommendations. A minimum dataset (typically 10,000 events) is recommended for optimal results. |
| Field | Description |
|---|---|
| Enable | Enables or disables the Recently Viewed Model Type recommendation block for the selected store view. When set to Yes, the system displays recently viewed products to customers on the storefront. When set to No, the recently viewed recommendation section will not appear. |
| Display Position | Defines the storefront pages where the Recently Viewed Products block will be displayed. Merchants can choose one or more locations such as Home Page, Product Page, or Cart Page to control where the recommendations appear. |
| Title | Specifies the main title displayed above the recently viewed products section on the storefront. This helps identify the recommendation block for customers. Example: Recently Viewed Products. |
| Sub Title | Allows administrators to define a subtitle or descriptive text displayed below the main title. This text provides additional context for customers about the recommendation block. Example: Products you recently viewed. |
| Sort Order | Determines the display priority of the recently viewed products section relative to other recommendation blocks on the page. Lower values display the section earlier, while higher values place it further down the page. |
| Field | Description |
|---|---|
| Enable | Enables or disables the Recommended for You recommendation model for the selected store view. When set to Yes, AI-driven personalized product recommendations will be displayed on the storefront. When set to No, this recommendation block will not appear. |
| Display Position | Defines the pages where the Recommended for You product recommendations will appear. Administrators can choose one or more locations such as Home Page, Product Page, or Cart Page to strategically display personalized recommendations to customers. |
| Title | Specifies the main title displayed for the Recommended for You recommendation block on the storefront. This title helps customers understand the purpose of the recommendations. Example: Recommended for You. |
| Sub Title | Defines the subtitle shown below the main title in the recommendation section. This text provides additional context to encourage customers to explore the suggested products. Example: Products we think you'll love. |
| Sort Order | Determines the display priority of the Recommended for You section relative to other recommendation blocks on the page. Lower values display the section earlier, while higher values place it further down in the page layout. |
| Field | Description |
|---|---|
| Enable | Enables or disables the Others You May Like recommendation model for the selected store view. When enabled, the system displays AI-generated product suggestions that are relevant to the product currently viewed by the customer. When disabled, this recommendation block will not be shown on the storefront. |
| Display Position | Defines the pages where the Others You May Like recommendations will appear. Administrators can select one or more locations such as Home Page, Product Page, or Cart Page to display the recommendation block. |
| Title | Specifies the main heading displayed above the recommendation section on the storefront. This title helps customers identify the purpose of the recommendations. Example: Others You May Like. |
| Sub Title | Allows administrators to define a descriptive subtitle shown below the main title. This text provides additional context and encourages customers to explore similar product suggestions. Example: Similar products you might enjoy. |
| Sort Order | Determines the display priority of the Others You May Like recommendation block relative to other recommendation sections on the page. Lower values appear earlier in the page layout, while higher values place the block further down the page. |
| Field | Description |
|---|---|
| Enable | Enables or disables the Frequently Bought Together recommendation model for the selected store view. When enabled, the system displays AI-generated product suggestions that are commonly purchased together with the currently viewed or selected product. When disabled, this recommendation section will not appear on the storefront. |
| Display Position | Defines the pages where the Frequently Bought Together recommendations will be displayed. Administrators can choose one or more locations such as Home Page, Product Page, or Cart Page to show these recommendations. |
| Title | Specifies the main title displayed above the Frequently Bought Together recommendation block on the storefront. This title helps customers identify related product suggestions. Example: Frequently Bought Together. |
| Sub Title | Allows administrators to define a descriptive subtitle displayed below the main title. This message encourages customers to explore additional products that other customers have purchased with the same item. Example: Customers who bought this also bought. |
| Sort Order | Determines the display priority of the Frequently Bought Together section compared to other recommendation blocks on the page. Lower values display the section earlier, while higher values position it further down the page layout. |
| Field | Description |
|---|---|
| Enable | Enables or disables the Similar Items recommendation model for the selected store view. When enabled, the system displays AI-generated product suggestions that share similar attributes with the currently viewed product, such as category, brand, color, or other product characteristics. When disabled, the similar items recommendation block will not appear on the storefront. |
| Display Position | Defines the pages where the Similar Items recommendations will be displayed. Administrators can select one or more locations such as Home Page, Product Page, or Cart Page to control where the recommendation block appears. |
| Title | Specifies the main title displayed above the Similar Items recommendation section on the storefront. This heading helps customers identify alternative or related product suggestions. Example: Similar Items. |
| Sub Title | Allows administrators to define a descriptive subtitle displayed below the main title. This text provides additional context and encourages customers to explore similar products. Example: Products similar to this one. |
| Sort Order | Determines the display priority of the Similar Items recommendation block relative to other recommendation sections on the page. Lower values display the section earlier, while higher values place it further down the page layout. |
| Field | Description |
|---|---|
| Enable | Enables or disables the Buy It Again recommendation model for the selected store view. When enabled, the system displays AI-generated product suggestions based on items the customer has previously purchased. When disabled, the Buy It Again recommendation section will not appear on the storefront. |
| Display Position | Defines the pages where the Buy It Again recommendations will be displayed. Administrators can select one or more locations such as Home Page, Product Page, or Cart Page to show previously purchased product suggestions. |
| Title | Specifies the main title displayed above the Buy It Again recommendation block on the storefront. This heading helps customers easily identify products they have purchased before. Example: Buy It Again. |
| Sub Title | Allows administrators to define a descriptive subtitle displayed below the main title. This text encourages customers to quickly reorder products they have previously purchased. Example: Products you've purchased before. |
| Sort Order | Determines the display priority of the Buy It Again section relative to other recommendation blocks on the page. Lower values display the section earlier, while higher values position it further down the page layout. |
| Field | Description |
|---|---|
| Enable | Enables or disables the On Sale recommendation model for the selected store view. When enabled, the system displays AI-generated product recommendations for items that are currently discounted or part of an active promotion. When disabled, the On Sale recommendation block will not appear on the storefront. |
| Display Position | Defines the pages where the On Sale product recommendations will be displayed. Administrators can choose one or more locations such as Home Page, Product Page, or Cart Page to highlight promotional products to customers. |
| Title | Specifies the main title displayed above the On Sale recommendation block on the storefront. This heading helps customers easily identify discounted or promotional products. Example: On Sale. |
| Sub Title | Allows administrators to define a subtitle displayed below the main title. This message highlights the value of the promotion and encourages customers to explore discounted products. Example: Great deals you don’t want to miss. |
| Sort Order | Determines the display priority of the On Sale section relative to other recommendation blocks on the page. Lower values display the section earlier, while higher values position it further down in the page layout. |
| Field | Description |
|---|---|
| Enable Frontend Cache Fallback | Enables or disables the use of browser storage as a fallback mechanism for product recommendations. When enabled, cached recommendations stored in the browser will be used if the Vertex AI API fails or returns no data due to an error, ensuring a consistent user experience. |
| Frontend Cache Lifetime (seconds) | Defines the maximum duration (in seconds) for which recommendations are stored in the browser cache before they are considered expired. Acceptable values range from 60 to 604800 seconds. Lower values ensure fresher data, while higher values improve performance and availability during API failures. |
Sample Data
`ai:initialize:vertex` | Initialize Vertex AI: test connection, create catalog, create serving configs, verify recommendations
`ai:export:products` | Export products to Vertex AI
`ai:export:order-history` | Export order history and purchase patterns to Vertex AI
`ai:export:customer-data` | Export customer demographic data to Vertex AI
`ai:export:add-to-cart` | Export add-to-cart events from quote data to Vertex AI
`ai:sync:incremental` | Incremental sync (products, orders, customers) with Vertex AI
`ai:generate:detail-page-views` | Generate detail page view events for Vertex AI (min 10,000)
`ai:generate:home-page-views` | Generate home page view events for Vertex AI (min 10,000)
`ai:generate:purchase-events` | Generate purchase events (complete orders) for Vertex AI
`ai:test:vertex` | Test Vertex AI integration and get sample recommendations
`ai:test:events` | Test Vertex AI event tracking
`ai:verify:events` | Verify event tracking with Vertex AI
`ai:validate:data-sync` | Validate data synchronization between Magento and Vertex AI
`ai:vertex:check-catalog` | Check Vertex AI catalog status
`ai:audit:endpoints` | Audit all Vertex AI API endpoints
`ai:cache:clear` | Clear AI recommendations cache
`--store-id` | `-s` | Store ID (default: 0)
`--batch-size` | `-b` | Batch size for exports (e.g. 100)
`--since` | | Sync changes since date (Y-m-d H:i:s)
`--type` | `-t` | Sync type: products, orders, customers, or all
`--dry-run` | | Show what would be synced without performing sync
bin/magento ai:export:products --store-id=1 --batch-size=50
bin/magento ai:sync:incremental --store-id=1 --type=products --dry-run
Backend Functionality
Vertex AI Model Overview
| Field | Description |
|---|---|
| Reload All Models | Allows administrators to manually refresh the status of all Vertex AI recommendation models at once. This ensures that the latest model data and configurations are fetched and reflected in the system. |
| Model Status (Per Model) | Displays the current status of each recommendation model such as Recently Viewed, Recommended For You, Others You May Like, Frequently Bought Together, Similar Items, Buy It Again, and On Sale. Status indicators like administrators quickly identify whether models are functioning correctly or require attention. |
| Reload (Per Model) | Enables administrators to individually reload and refresh the status of a specific recommendation model. This is useful for troubleshooting or updating a particular model without affecting others. |
Vertex AI Model Details
| Field | Description |
|---|---|
| Display Name | Shows the human-readable name of the recommendation model displayed on the storefront (e.g., “Items you recently viewed” or “Recommended for you”). |
| Model Type | Represents the internal identifier of the recommendation model used by Vertex AI (e.g.,
|
| Optimization Objective | Defines the goal of the recommendation model, such as optimizing for click-through rate (CTR) or engagement. This determines how the AI ranks and suggests products. |
| State | Indicates whether the model is currently active or inactive. Active models are used to generate recommendations, while inactive ones are not serving results. |
| Training State | Displays the current training status of the model, such as training in progress or completed. This helps track whether the AI model is ready for use. |
| Data State | Shows the health of the data used by the model. Values like valid data, while |
| Last Tune Time | Represents the last time the model was fine-tuned or updated based on new data and training cycles. |
| Last Synced At | Displays the most recent date and time when data was successfully synchronized between Magento and Vertex AI. |
| Status | Provides the overall synchronization or processing status of the model, such as successful sync or error state, helping administrators monitor system health. |
Vertex AI Event Sync Log
| Field | Description |
|---|---|
| Refresh Logs | Allows administrators to reload and fetch the latest event sync logs from the system. This ensures that the grid displays the most up-to-date synchronization activity between Magento and Vertex AI. |
| Clear Logs | Enables administrators to manually delete all event sync logs. This is useful for maintaining system performance, clearing outdated records, or resetting logs for troubleshooting purposes. |
| Event Log Grid | Displays a detailed list of all event synchronization records between Magento and Vertex AI. It includes key information such as Event Type, Source, Visitor ID, Store View, Product IDs, Search Query, Sync Status, Sync Method, and Synced At timestamp, providing full visibility into data flow and processing. |
| Event Type | Represents the type of user interaction being tracked, such as Home Page View, Product Detail Page View, Category Page View, or Shopping Cart actions. |
| Source | Indicates the origin of the event data, such as real-time tracking or sample data used for testing and initialization. |
| Visitor ID | Displays the unique identifier associated with a user or session, helping track user behavior across events. |
| Store View | Identifies the Magento store view where the event occurred, supporting multi-store and multi-language setups. |
| Product IDs | Shows the associated product identifiers involved in the event, if applicable (e.g., product views or cart actions). |
| Search Query | Captures the search terms entered by the user when applicable, helping improve recommendation accuracy and search insights. |
| Sync Status | Indicates the result of the synchronization process (e.g., success or failure), helping monitor integration health. |
| Sync Method | Specifies the method used for synchronization, such as SDK or API-based communication with Vertex AI. |
| Synced At | Displays the date and time when the event was successfully synchronized with Vertex AI. |
| Action | Provides options such as viewing detailed information for each log entry, enabling deeper inspection and debugging of specific events. |
Event Detail
| Field | Description |
|---|---|
| Event Type | Represents the type of event captured, such as home page view, product view, category view, or other user interactions tracked for AI recommendations. |
| Source | Indicates the origin of the event data, such as real-time tracking or system-generated sample data. |
| Visitor ID | Displays the unique identifier assigned to the visitor or session, enabling tracking of user behavior across interactions. |
| Store | Specifies the Magento store view where the event occurred, supporting multi-store environments. |
| Sync Status | Shows the result of the event synchronization process with Vertex AI, such as success or failure. |
| Sync Method | Indicates the method used to send event data to Vertex AI, such as SDK or API-based integration. |
| Event Data (JSON) | Provides the raw event payload in JSON format, including details such as event type, visitor ID, timestamp, and additional attributes (e.g., page, product, or action data). This helps in debugging and validating event data sent to Vertex AI. |
Frontend Functionality
The Recently Viewed Products section appears on the storefront to help customers quickly revisit items they have previously explored.
A clear heading such as “Recently Viewed Products” is displayed along with a supporting subtitle like “Products you recently viewed” to provide context.
Products are presented in a horizontal slider or carousel layout, allowing customers to easily scroll through recently viewed items.
Each product card includes important product details such as product image, product name, price, rating, and available variants (size or color).
Customers can directly take action using the Add to Cart button available within each product card.
The section may also include quick action icons such as wishlist or comparison options for added convenience.
Navigation arrows allow customers to browse through the product list smoothly without leaving the current page.
This feature improves the shopping experience by reducing the need to search for previously viewed items and encouraging customers to return to products they were interested in.
Demo
Click here to visit frontend.
Click here to visit backend admin panel.
Thank you for choosing MageDelight!