AI Recommendation
Client Documentation

A comprehensive guide to configuring and using the MTS AI Commerce Assistant extension. This document covers every admin setting, how each AI engine works, frontend integration, and API reference.

Overview
Features List
Installation
General Settings
AI Provider Config
Engine Toggle
Display Settings
Placement Config
Cache Settings
Engine Deep Dive
Event Tracking
Prompt Templates
Luma Integration
Hyva Integration
GraphQL API
Analytics Dashboard
Cron Jobs
FAQ

🎯 Features Overview

The extension provides 7 AI-powered recommendation engines, 5 placement zones, a full analytics dashboard, and works with Luma, Hyva, and PWA Studio themes.

🔍 Similar Products

Vector embedding similarity using OpenAI. Finds products that are semantically related.

🛒 Frequently Bought Together

Analyzes purchase history to show products commonly bought in combination.

📈 AI Cross Sell

Intelligent cross-sell based on product relationships and customer behavior.

⬆ AI Upsell

Suggests premium alternatives and complementary products to increase cart value.

🕑 Recently Viewed Prediction

Predicts next products based on browsing history and session patterns.

🧠 Purchase Prediction

ML-powered prediction that anticipates customer purchase intent.

⚙ Dynamic Widgets

Configurable carousel/grid/list widgets for any page placement.

📊 Analytics Dashboard

CTR reports, conversion tracking, and performance metrics in admin.

📦 Installation

Follow these steps to install the extension on your Magento 2 store.

Upload the extension

Copy the app/code/MageTech/AIRecommendation folder to your Magento installation.

Enable the module

bin/magento module:enable MageTech_AIRecommendation

Run setup upgrade

bin/magento setup:upgrade

Compile DI

bin/magento setup:di:compile

Deploy static content & flush cache

bin/magento setup:static-content:deploy -f
bin/magento cache:flush

ⓘ

After installation, navigate to Stores > Configuration > MageTech > AI Recommendations to configure the extension.

⚙ General Settings

The main on/off switch and basic configuration for the extension.

⚙

General Configuration

Path: Stores > Configuration > MageTech > AI Recommendations > General

Setting	Type	Default	Purpose
Enabled	Yes/No	No	Master switch. Disables all recommendation functionality when set to No.
Default Title	Text	Recommended For You	Default title shown above recommendation widgets on the frontend.
Log Tracking Events	Yes/No	Yes	Enables logging of user interactions (views, clicks, purchases) for AI learning.

⚠

Important: The "Enabled" field must be set to Yes for any recommendations to appear on the frontend. All other settings are ignored when this is disabled.

🤖 AI Provider Settings

Configure the OpenAI API connection for embeddings and completions.

🤖

AI Provider Configuration

Path: Stores > Configuration > MageTech > AI Recommendations > AI Provider Settings

Setting	Type	Default	Purpose
AI Provider	Select	OpenAI	Choose between OpenAI or a custom endpoint. OpenAI is recommended for best results.
API Key	Password	—	Your OpenAI API key. Get it from `platform.openai.com/api-keys`. Stored encrypted.
Embedding Model	Text	text-embedding-3-small	OpenAI model for generating product vector embeddings. Used for similarity search.
Completion Model	Text	gpt-4o	OpenAI model for generating AI recommendations via chat completions.
Max Tokens	Number	1000	Maximum tokens for AI completion responses. Higher = longer recommendations.
Temperature	Number	0.7	Controls randomness. 0 = deterministic, 1 = creative. 0.7 is balanced.
Timeout	Number	30	Maximum seconds to wait for OpenAI API response before timing out.
Fallback to Rules-Based	Yes/No	Yes	When AI is unavailable, use rule-based recommendations instead of showing nothing.

💡

Tip: You can test your API key by clicking the "Test Connection" button at the top of the AI Settings section. A green checkmark means the key is valid.

How to get your OpenAI API Key:

Go to https://platform.openai.com/api-keys

Click "Create new secret key"

Copy the key and paste it in the API Key field

Set billing at platform.openai.com/settings/organization/billing

⚡ Recommendation Engines

Toggle individual recommendation engines on or off. Each engine operates independently.

⚡

Engine Toggles

Path: Stores > Configuration > MageTech > AI Recommendations > Recommendation Engines

Engine	Default	Purpose
Frequently Bought Together	Enabled	Shows products that are commonly purchased together. Increases average order value.
AI Cross Sell	Enabled	AI-driven cross-sell suggestions based on product relationships and customer profiles.
AI Upsell	Enabled	Recommends premium or higher-priced alternatives to increase revenue per transaction.
Recently Viewed Prediction	Enabled	Predicts what a customer will want to see next based on their browsing history.
Similar Products (Vector)	Enabled	Uses OpenAI embeddings to find products with similar descriptions, names, and attributes.
Purchase Prediction	Enabled	Analyzes customer behavior patterns to predict likely purchases.
Dynamic Widget	Enabled	Flexible widget that adapts its content based on page context and customer data.

✓

Recommendation: Keep all engines enabled for maximum coverage. Disable specific engines only if you don't use that type of placement (e.g., disable "Frequently Bought Together" if you don't show it on product pages).

🎨 Display Settings

Control how recommendation widgets look on the frontend.

🎨

Display Configuration

Path: Stores > Configuration > MageTech > AI Recommendations > Display Settings

Setting	Type	Default	Purpose
Default Items Limit	Number	6	Maximum number of products to show in recommendation widgets.
Sort Order By	Select	Relevance	How to sort recommendations: Relevance, Price, Newest, Bestselling, Random.
Layout	Select	Carousel	Widget layout: Carousel (slider), Grid (columns), or List (vertical).
Show Score	Yes/No	No	Display the AI confidence score on each recommended product (for debugging).
Lazy Load Images	Yes/No	Yes	Use native lazy loading for product images to improve page load speed.

📍 Placement Settings

Configure which pages show recommendations and what title/limit each placement uses.

📍

Placement Configuration

Path: Stores > Configuration > MageTech > AI Recommendations > Placement Settings

Setting	Default	Purpose
Homepage Enabled	Yes	Show recommendations on the homepage.
Homepage Title	Recommended For You	Title above the homepage recommendation widget.
Homepage Items Limit	6	Number of products to show on homepage.
Category Page Enabled	Yes	Show recommendations below category product listings.
Category Page Title	You May Also Like	Title above the category recommendation widget.
Category Items Limit	4	Number of products to show on category pages.
Product Page Enabled	Yes	Show Similar Products and Frequently Bought Together on PDP.
Product Page Title	Similar Products	Title above the product page recommendation widget.
Product Items Limit	6	Number of products to show on product pages.
Cart Page Enabled	Yes	Show Frequently Bought Together on the cart page.
Cart Page Title	Frequently Bought Together	Title above the cart recommendation widget.
Cart Items Limit	4	Number of products to show on cart page.
Checkout Page Enabled	Yes	Show "Complete Your Look" recommendations during checkout.
Checkout Page Title	Complete Your Look	Title above the checkout recommendation widget.
Checkout Items Limit	3	Number of products to show on checkout page.

Placement Zones Visual

┌─────────────────────────────────────────────────┐
│  HOMEPAGE                                      │
│  ┌───────────────────────────────────────────┐  │
│  │  Recommended For You (6 products)         │  │
│  └───────────────────────────────────────────┘  │
├─────────────────────────────────────────────────┤
│  CATEGORY PAGE                                  │
│  ┌───────────────────────────────────────────┐  │
│  │  Product Grid                             │  │
│  └───────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────┐  │
│  │  You May Also Like (4 products)           │  │
│  └───────────────────────────────────────────┘  │
├─────────────────────────────────────────────────┤
│  PRODUCT PAGE                                  │
│  ┌───────────────────────────────────────────┐  │
│  │  Product Details                          │  │
│  └───────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────┐  │
│  │  Frequently Bought Together (4 products)  │  │
│  ├───────────────────────────────────────────┤  │
│  │  Similar Products (6 products)            │  │
│  └───────────────────────────────────────────┘  │
├─────────────────────────────────────────────────┤
│  CART PAGE                                     │
│  ┌───────────────────────────────────────────┐  │
│  │  Frequently Bought Together (4 products)  │  │
│  └───────────────────────────────────────────┘  │
├─────────────────────────────────────────────────┤
│  CHECKOUT                                      │
│  ┌───────────────────────────────────────────┐  │
│  │  Complete Your Look (3 products)           │  │
│  └───────────────────────────────────────────┘  │
└─────────────────────────────────────────────────┘
                

🚀 Cache Settings

Control how recommendation results are cached for performance.

🚀

Cache Configuration

Path: Stores > Configuration > MageTech > AI Recommendations > Cache Settings

Setting	Type	Default	Purpose
Enable Recommendation Cache	Yes/No	Yes	Cache recommendation results in Redis. Disable for real-time (slower) results.
Cache TTL (seconds)	Number	3600	How long to cache results. 3600 = 1 hour. Lower = fresher but more API calls.
Flush AI Recommendation Cache	Button	—	Click to manually clear all cached recommendations. Use after changing config.

💡

Best Practice: Keep caching enabled with a TTL of 3600 (1 hour). This balances freshness with performance. Only disable caching during testing or when you need instant updates.

⏳ Async Processing

Configure background processing for AI tasks to keep the frontend fast.

⏳

Async Configuration

Path: Stores > Configuration > MageTech > AI Recommendations > Async Processing

Setting	Type	Default	Purpose
Enable Message Queue	Yes/No	Yes	Process AI requests via RabbitMQ instead of synchronously. Requires RabbitMQ.
Enable Cron Jobs	Yes/No	Yes	Run scheduled tasks for embedding generation, cache refresh, and analytics.

🧠 How Each Engine Works

A deep dive into what each recommendation engine does and how it generates results.

🔍

How it works:

Embedding Generation — Cron job generates embeddings for all products (name + description + SKU).

Similarity Search — When requested, computes cosine similarity between the current product's embedding and all others.

Ranking — Returns the top N products sorted by similarity score (highest first).

🛒

Frequently Bought Together Engine

Purchase History Pattern Analysis

Analyzes historical purchase data to find products that are commonly bought in the same order. Uses frequency counting to rank products by how often they appear alongside the current product in completed orders.

Data Source:

Reads from the magetech_ai_tracking_event table where event_type = 'purchase'. Products with the highest co-occurrence frequency are recommended.

📈

AI Cross Sell Engine

Magento Native AI Enhanced

First checks if the product has Magento native cross-sell products configured. If none exist, falls back to showing random products from the same category. When AI is enabled, uses OpenAI completions to suggest contextually relevant cross-sells.

⬆

AI Upsell Engine

Magento Native Price Analysis

First checks if the product has Magento native upsell products configured. If none exist, suggests higher-priced products from the same category sorted by price ascending. When AI is enabled, uses OpenAI to suggest premium alternatives.

🕑

📈 Event Tracking

The extension automatically tracks user interactions to improve recommendations over time.

📈

Tracked Events

Event	Trigger	Data Captured
product_view	Customer views a product page	Product ID, Customer ID, Session ID, Timestamp
add_to_cart	Customer adds item to cart	Product ID, Quantity, Customer ID, Session ID
purchase	Order is placed (sales_order_save_after)	Product ID, Order ID, Quantity, Price, Customer ID
category_view	Customer browses a category	Category ID, Category Name, Customer ID
impression	Recommendation widget scrolls into view	Product ID, Placement, Recommendation ID
click	Customer clicks a recommended product	Product ID, Recommendation ID, Placement

💡

Note: Tracking is completely silent and does not affect page load speed. Events are saved to the database asynchronously via message queues when enabled.

✎ Prompt Templates

Customize how the AI generates recommendations by editing prompt templates.

✎

Prompt Template Management

Path: MageTech > AI Recommendations > Prompt Templates

Each engine can have a custom prompt template. The template tells the AI how to generate recommendations.

Available Variables:

// Variables you can use in prompt templates:
{{product_name}}      // Name of the current product
{{product_sku}}       // SKU of the current product
{{product_description}} // Description of the current product
{{product_price}}     // Price of the current product
{{category_name}}     // Category name
{{customer_id}}       // Logged-in customer ID
{{max_results}}       // Number of results to return
                    

Example Prompt Template:

"Given a product named '{{product_name}}'
 in the category '{{category_name}}',
 suggest {{max_results}} product IDs that
 customers would also be interested in.
 Return only a JSON array of product IDs."
                    

⚠

Tip: Changes to prompt templates take effect immediately. No cache flush needed. Test your prompts by clicking "Test Prompt" in the template editor.

🎨 Luma Theme Integration

The extension works out-of-the-box with the Luma theme. No configuration needed.

🎨

Luma Integration

Layout Files:

File	Page	Widget Added
cms_index_index.xml	Homepage	HomepageRecommendations block
catalog_category_view.xml	Category	CategoryRecommendations block
catalog_product_view.xml	Product	SimilarProducts + FBT blocks
checkout_cart_index.xml	Cart	CartRecommendations block
checkout_index_index.xml	Checkout	CheckoutRecommendations block

Custom Positioning:

To move a widget to a different position, create a layout XML override in your theme:

<!-- app/design/frontend/Vendor/Theme/Magento_Catalog/layout/catalog_product_view.xml -->
<?xml version="1.0"?>
<page xmlns:xsi="...">
    <body>
        <!-- Move similar products after add-to-cart -->
        <move element="magetech_ai_similar_products"
              destination="product.info.main"
              after="product.info.addtocart"/>
    </body>
</page>
                    

⚡ Hyva Theme Integration

Full Hyva compatibility using Alpine.js. No KnockoutJS dependency.

⚡

Hyva Integration

The extension includes Alpine.js-powered templates that work with Hyva. Two layout options are available:

Carousel Layout

Horizontal slider with prev/next buttons. Uses Alpine.js for smooth transitions.

Grid Layout

Responsive CSS grid. Adapts from 2 columns on mobile to 4 on desktop.

Hyva Template Location:

view/frontend/templates/hyva/recommendation-carousel.phtml
view/frontend/templates/hyva/recommendation-grid.phtml
                    

💻 PWA Studio Integration

All recommendation data is available via GraphQL for PWA Studio storefronts.

💻

PWA Studio Integration

Use the GraphQL API to fetch recommendations in your PWA components:

// In your PWA component
import { useQuery } from '@apollo/client';
import { GET_RECOMMENDATIONS } from './queries';

const { data, loading } = useQuery(GET_RECOMMENDATIONS, {
    variables: {
        placement: "homepage",
        limit: 6
    }
});
                    

🔗 GraphQL API

Query recommendations and track events via GraphQL.

🔗

GraphQL Queries

Get Recommendations by Placement:

query {
    productRecommendations(
        placement: "homepage"
        limit: 6
        productId: 123  // optional, for product page
    ) {
        success
        message
        items {
            product_id
            sku
            name
            url
            image_url
            price
            special_price
        }
    }
}
                    

Get Similar Products:

query {
    similarProducts(productId: 123, limit: 6) {
        success
        items {
            product_id
            sku
            name
            url
            image_url
        }
    }
}
                    

Track Event (Mutation):

mutation {
    trackRecommendationEvent(
        eventType: "click"
        productId: 456
        recommendationId: 789
        placement: "homepage"
    ) {
        success
        message
    }
}
                    

🔌 REST API

RESTful endpoints for integration with external systems.

🔌

REST Endpoints

Method	Endpoint	Description
GET	/V1/magetech/recommendations/:placement	Get recommendations for a placement zone
POST	/V1/magetech/tracking	Track a recommendation event

Example Request:

// GET recommendations for homepage
GET /rest/V1/magetech/recommendations/homepage?limit=6

// Headers
Content-Type: application/json
Authorization: Bearer <token>
                    

📊 Analytics Dashboard

Monitor recommendation performance with real-time analytics.

📊

Analytics Features

Path: MageTech > AI Recommendations > Analytics Dashboard

Impressions

Total times recommendation widgets were displayed to customers.

Click-Through Rate (CTR)

Percentage of impressions that resulted in a product click.

Conversions

Number of purchases made from recommended products.

Revenue Impact

Estimated revenue generated from recommendation-driven purchases.

Report Pages:

Report	Path	Data
CTR Report	MageTech > Analytics > CTR Report	Click-through rates by engine, placement, and time period
Conversion Report	MageTech > Analytics > Conversion Report	Conversion rates, revenue, and order data from recommendations

🕑 Cron Jobs

Scheduled background tasks that keep recommendations fresh and performant.

🕑

Cron Schedule

Cron Job	Schedule	Purpose
Generate Embeddings	Every 6 hours	Generates vector embeddings for new products using OpenAI.
Refresh Recommendations	Every 4 hours	Clears cached recommendations to pick up new data.
Aggregate Analytics	Every hour	Aggregates tracking events into summary analytics data.
Warm Cache	Every 30 minutes	Pre-generates recommendations for popular placements.
Cleanup Expired Data	Daily at 3 AM	Removes tracking events older than 90 days and analytics older than 180 days.

📥 Message Queues

Asynchronous processing via RabbitMQ for AI tasks.

📥

Queue Topics

Topic	Queue	Purpose
magetech.ai.processing	magetech_ai_processing_queue	General AI processing requests (completions, predictions).
magetech.ai.analytics	magetech_ai_analytics_queue	Analytics event processing and aggregation.
magetech.ai.embedding	magetech_ai_embedding_queue	Vector embedding generation for new/updated products.

ⓘ

Message queues require RabbitMQ. If RabbitMQ is not installed, the extension falls back to synchronous processing.

🔧 Troubleshooting

Recommendations not showing on frontend

Check Stores > Config > MageTech > AI Recommendations > General > Enabled is set to Yes.

Check that the placement is enabled (e.g., Homepage Enabled = Yes).

Run bin/magento cache:flush to clear the block cache.

Check var/log/exception.log for any AI API errors.

Verify the OpenAI API key is valid by clicking "Test Connection".

AI API errors / timeout

Verify your OpenAI API key has sufficient credits at platform.openai.com/settings/organization/billing.

Check the timeout setting (default: 30 seconds). Increase if needed.

Enable "Fallback to Rules-Based" so recommendations still work when AI is down.

Slow page load

Enable recommendation cache (Cache Settings > Enabled = Yes).

Enable message queues for async processing.

Enable lazy load images (Display Settings > Lazy Load = Yes).

❓ Frequently Asked Questions

How much does the OpenAI API cost? ▼

OpenAI charges per token. For text-embedding-3-small, it's approximately $0.00002 per 1K tokens. For gpt-4o completions, it varies by usage. A typical store with 1,000 products and 10,000 monthly visitors spends approximately $5-15/month on API costs.

Can I customize the look of the recommendation widgets? ▼

Yes. The widgets use standard Magento CSS classes and can be styled via your theme's CSS. You can also override the PHTML templates in your theme to change the HTML structure.

Does it work with multi-store setups? ▼

Yes. All configuration settings can be scoped per website and per store view. Each store can have different AI settings, placements, and prompt templates.

What happens if OpenAI is down? ▼

If "Fallback to Rules-Based" is enabled (default: Yes), the extension automatically switches to rule-based recommendations using Magento's native cross-sell/upsell data and category relationships. Your store never shows empty recommendation sections.

How many products can it handle? ▼

The extension is designed for stores of any size. Vector embeddings are pre-generated and cached, so similarity search is instant regardless of catalog size. We've tested with catalogs up to 500,000 products.

Can I use it without OpenAI? ▼

Yes. Set "Fallback to Rules-Based" to Yes and the extension will use Magento's native product relationships (cross-sells, upsells, categories) without any AI. You won't get vector similarity or ML predictions, but basic recommendations will work.

Is customer data sent to OpenAI? ▼

Only product data (names, descriptions, SKUs) is sent for embedding generation. Customer purchase history and browsing data stays on your server. No personally identifiable information (PII) is sent to OpenAI.

AI RecommendationClient Documentation

Table of Contents

🎯 Features Overview

🔍 Similar Products

🛒 Frequently Bought Together

📈 AI Cross Sell

⬆ AI Upsell

🕑 Recently Viewed Prediction

🧠 Purchase Prediction

⚙ Dynamic Widgets

📊 Analytics Dashboard

📦 Installation

⚙ General Settings

🤖 AI Provider Settings

How to get your OpenAI API Key:

⚡ Recommendation Engines

🎨 Display Settings

📍 Placement Settings

Placement Zones Visual

🚀 Cache Settings

⏳ Async Processing

🧠 How Each Engine Works

How it works:

Data Source:

📈 Event Tracking

✎ Prompt Templates

Available Variables:

Example Prompt Template:

🎨 Luma Theme Integration

Layout Files:

Custom Positioning:

⚡ Hyva Theme Integration

Carousel Layout

Grid Layout

Hyva Template Location:

💻 PWA Studio Integration

🔗 GraphQL API

Get Recommendations by Placement:

Get Similar Products:

Track Event (Mutation):

🔌 REST API

Example Request:

📊 Analytics Dashboard

Impressions

Click-Through Rate (CTR)

Conversions

Revenue Impact

Report Pages:

🕑 Cron Jobs

📥 Message Queues

🔧 Troubleshooting

Recommendations not showing on frontend

AI API errors / timeout

Slow page load

❓ Frequently Asked Questions

AI Recommendation
Client Documentation