Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pureclarity.com/llms.txt

Use this file to discover all available pages before exploring further.

PureClarity offers two distinct display modes for rendering recommendations in Magento 2.x. Understanding these modes helps you choose the best approach for your specific requirements and technical constraints.

​
Accessing Mode Configuration

Navigate to Stores > Configuration > PureClarity and locate the “Mode” section. Mode settings in PureClarity configuration page in Magento 2 admin

​
Display Mode Options

​
Client-Side Mode (Default)

Recommended for: Most standard implementations
Processing location: PureClarity servers
Template management: PureClarity admin console In client-side mode, all recommendation data and HTML rendering occurs on PureClarity’s servers. When a customer visits your site, JavaScript requests recommendations directly from PureClarity and displays them in real-time. How it works:
  1. Page loads with PureClarity JavaScript
  2. Recommendations requested from PureClarity servers
  3. Complete HTML returned and inserted into zones
  4. No additional Magento processing required
Advantages:
  • Faster page loads - No server-side processing delays
  • Reduced server load - Offloads recommendation processing
  • Real-time updates - Content changes immediately in PureClarity admin
  • Global CDN delivery - Fast content delivery worldwide
  • Simplified implementation - No complex server-side customizations
Client-side mode is the standard implementation and works well for most e-commerce sites without complex pricing rules or customer-specific restrictions.

​
Server-Side Mode

Recommended for: Complex pricing, custom restrictions, or advanced customizations
Processing location: Your Magento server
Template management: Magento templates with PureClarity data In server-side mode, PureClarity provides product SKUs and recommendation logic, but Magento handles the final data assembly and HTML rendering using current store data. How it works:
  1. Page loads and triggers server-side recommendation request
  2. PureClarity returns SKUs and recommendation metadata
  3. Magento processes SKUs with current pricing, inventory, and rules
  4. Custom templates render final HTML with live data
  5. Complete recommendations inserted into page
Advantages:
  • Live pricing integration - Real-time price calculations
  • Customer-specific data - Personalized pricing and availability
  • Complex business rules - Custom logic and restrictions
  • Full template control - Complete customization of appearance
  • Inventory accuracy - Current stock levels reflected
Server-side mode requires additional development work and may impact page load performance. Use only when client-side mode cannot meet your requirements.

​
When to Choose Each Mode

​
Client-Side Mode Best For:

  • Standard pricing - Fixed prices without complex rules
  • Public catalogs - Same prices and availability for all customers
  • Fast implementation - Quick setup without custom development
  • High traffic sites - Reduced server load requirements
  • Global audiences - CDN-delivered content for speed

​
Server-Side Mode Best For:

  • Dynamic pricing - Customer group pricing, volume discounts
  • B2B features - Account-specific pricing and catalogs
  • Complex inventory - Multi-location, reserved, or allocated stock
  • Custom restrictions - Product visibility rules beyond standard Magento
  • Advanced integrations - ERP systems, custom pricing engines
Start with client-side mode unless you have specific requirements that demand server-side processing. You can always migrate to server-side mode later if needed.

​
Technical Implementation Details

​
Client-Side Implementation

<!-- Zone placement in templates -->
<div data-pureclarity="bmz:ZONE-ID;"></div>
JavaScript loading:
  • PureClarity script loads asynchronously
  • Recommendations request product data from PureClarity
  • Complete HTML inserted into zone containers
  • No Magento processing required

​
Server-Side Implementation

<!-- Zone placement in templates -->
<div data-serverside-pureclarity="bmz:ZONE-ID" 
     data-pureclarity-bmz-id="ZONE-ID" 
     class="pc_bmz" />
Processing flow:
  • Magento processes recommendation requests
  • SKUs retrieved from PureClarity
  • Product data loaded from Magento database
  • Custom templates render final output
  • HTML inserted into zone containers
Server-side mode requires additional template development and configuration. See Server-Side Mode Guide for detailed implementation instructions.

​
Performance Considerations

​
Client-Side Performance

Advantages:
  • Faster initial page load - No server-side processing delay
  • Cached content - CDN delivery and browser caching
  • Parallel loading - Recommendations load independently
  • Reduced server load - Offloaded processing
Considerations:
  • JavaScript dependency - Requires client-side JavaScript
  • Network requests - Additional API calls to PureClarity
  • Content delay - Slight delay before recommendations appear

​
Server-Side Performance

Advantages:
  • No client dependencies - Works without JavaScript
  • SEO friendly - Server-rendered content for crawlers
  • Complete control - Full optimization possibilities
Considerations:
  • Server processing - Additional load on Magento servers
  • Database queries - Extra product data retrieval
  • Page load impact - Potential slowdown during processing
  • Scaling challenges - Increased resource requirements

​
SEO and Accessibility

​
Client-Side SEO

  • JavaScript-dependent content may not be indexed
  • Asynchronous loading can delay content visibility
  • Modern crawlers generally handle JavaScript well
  • Fallback content can provide basic SEO value

​
Server-Side SEO

  • Server-rendered content is immediately indexable
  • No JavaScript dependency for search engines
  • Complete control over meta tags and structured data
  • Better accessibility for non-JavaScript environments
For SEO-critical recommendation content, consider server-side mode or implement proper fallback content for client-side implementations.

​
Migration Between Modes

​
Client-Side to Server-Side

Migration requirements:
  1. Template development for recommendation rendering
  2. Custom logic implementation for pricing and rules
  3. Testing and validation of recommendation accuracy
  4. Performance optimization for server-side processing

​
Server-Side to Client-Side

Migration considerations:
  1. Template simplification - Remove server-side logic
  2. Pricing validation - Ensure client-side pricing is acceptable
  3. Testing recommendations - Verify recommendation quality
  4. Performance monitoring - Check for improvement

​
Configuration Best Practices

​
Mode Selection Strategy

  1. Assess requirements - Pricing complexity, customizations needed
  2. Evaluate technical resources - Development capabilities
  3. Consider performance - Server load vs. page speed priorities
  4. Plan for scalability - Future growth and complexity

​
Implementation Guidelines

  • Start simple - Begin with client-side unless requirements dictate otherwise
  • Test thoroughly - Validate recommendations in both modes during evaluation
  • Monitor performance - Track impact on site speed and server load
  • Document decisions - Record reasoning for mode selection

​
Troubleshooting Mode Issues

​
Client-Side Troubleshooting

Recommendations not loading:
  • Check JavaScript console for errors
  • Verify PureClarity script loading
  • Confirm zone placement HTML
  • Test network connectivity to PureClarity
Content not updating:
  • Clear browser cache
  • Check PureClarity admin for campaign changes
  • Verify feed data is current
  • Test with different browsers

​
Server-Side Troubleshooting

Slow page loads:
  • Profile server-side processing time
  • Optimize database queries
  • Check server resource usage
  • Review custom template efficiency
Incorrect data display:
  • Verify Magento product data
  • Check custom pricing logic
  • Test template rendering
  • Validate recommendation SKUs

​
Zone Implementation

​
Advanced Features

​
Performance Monitoring