For precise zone placement that can’t be achieved with standard widgets, you can add PureClarity zones directly to your theme templates using HTML tags. The HTML syntax varies depending on your display mode configuration.

​
Before You Begin

Check your PureClarity display mode setting in Stores > Configuration > PureClarity > Mode to determine which HTML syntax to use.
Direct HTML integration requires theme customization and should be performed by developers familiar with Magento theme structure.

​
HTML Syntax by Mode

​
Client-Side Mode HTML

For installations using client-side display mode: 
<div data-pureclarity="bmz:ZONE-ID;"></div>
Characteristics:
  • Minimal markup required
  • JavaScript-driven content insertion
  • Asynchronous loading of recommendations
  • PureClarity-managed templates and styling

​
Server-Side Mode HTML

For installations using server-side display mode: 
<div data-serverside-pureclarity="bmz:ZONE-ID" 
     data-pureclarity-bmz-id="ZONE-ID" 
     class="pc_bmz" />
Characteristics:
  • Multiple attributes for server processing
  • Magento-rendered content
  • Custom template control
  • Server-side data integration
Using the wrong HTML syntax for your mode will prevent zones from displaying. Always verify your configuration mode before implementing HTML zones.

​
Zone ID Configuration

​
Zone ID Format

Replace ZONE-ID in the HTML examples with your actual PureClarity zone identifier: Examples:
  • Homepage hero: HP-01
  • Category page recommendations: CAT-01
  • Product page cross-sells: PDP-01
  • Search results: SR-01

​
Zone ID Best Practices

  • Use descriptive naming - Clear identification of zone purpose
  • Maintain consistency - Standardized naming across your site
  • Document zone mapping - Keep records of zone placements
  • Coordinate with campaigns - Ensure zone IDs match PureClarity admin
Zone IDs must exactly match the zone identifiers configured in your PureClarity campaigns. Mismatched IDs will result in empty zones.

​
Template Integration Locations

​
Common Integration Points

Theme Files:
  • app/design/frontend/[Vendor]/[theme]/Magento_Catalog/templates/
  • app/design/frontend/[Vendor]/[theme]/Magento_Checkout/templates/
  • app/design/frontend/[Vendor]/[theme]/Magento_Cms/templates/
Typical Placements:
  • Homepage sections - In CMS page templates
  • Category pages - In category view templates
  • Product pages - In product detail templates
  • Cart/Checkout - In shopping cart templates

​
Example Integrations

​
Homepage Hero Zone

<!-- In CMS page template or homepage.phtml -->
<div class="hero-section">
    <div data-pureclarity="bmz:HP-01;"></div>
</div>

​
Category Page Recommendations

<!-- In category/view.phtml -->
<div class="category-recommendations">
    <div data-pureclarity="bmz:CAT-01;"></div>
</div>

​
Product Page Cross-Sells

<!-- In catalog/product/view.phtml -->
<div class="product-recommendations">
    <div data-pureclarity="bmz:PDP-01;"></div>
</div>

​
Advanced HTML Integration

​
Conditional Zone Display

<?php if ($block->isZoneEnabled('HP-01')): ?>
    <div class="homepage-zone">
        <div data-pureclarity="bmz:HP-01;"></div>
    </div>
<?php endif; ?>

​
Responsive Zone Implementation

<!-- Desktop zone -->
<div class="hidden-xs">
    <div data-pureclarity="bmz:HP-01-DESKTOP;"></div>
</div>

<!-- Mobile zone -->
<div class="visible-xs">
    <div data-pureclarity="bmz:HP-01-MOBILE;"></div>
</div>

​
Fallback Content

<div class="zone-container">
    <div data-pureclarity="bmz:HP-01;"></div>
    
    <!-- Fallback content if PureClarity is unavailable -->
    <div class="fallback-content" style="display: none;">
        <?php echo $block->getFallbackContent(); ?>
    </div>
</div>
Fallback content provides a backup when PureClarity services are unavailable, ensuring your site maintains functionality and appearance.

​
CSS Styling Considerations

​
Zone Container Styling

.zone-container {
    min-height: 200px;
    margin: 20px 0;
    position: relative;
}

/* Loading state */
.zone-container[data-pureclarity]:empty::before {
    content: "Loading recommendations...";
    position: absolute;
    top: 50%;
    left: 50%;
    transform: translate(-50%, -50%);
    color: #999;
}

​
Responsive Design

@media (max-width: 768px) {
    .zone-container {
        margin: 10px 0;
        min-height: 150px;
    }
}

​
Theme Integration

/* Match your theme's existing styles */
.zone-container {
    background: var(--theme-background);
    border-radius: var(--theme-border-radius);
    padding: var(--theme-spacing);
}

​
Performance Optimization

​
Lazy Loading Zones

<div data-pureclarity="bmz:HP-01;" 
     data-lazy="true" 
     data-threshold="200">
</div>

​
Preload Critical Zones

<!-- Preload important zones for faster rendering -->
<link rel="preload" href="//[region].pureclarity.net/api/bmz/HP-01" as="fetch">

​
Minimize Layout Shift

.zone-container {
    /* Reserve space to prevent layout shift */
    min-height: 250px;
    width: 100%;
}
Layout shifts can negatively impact user experience and Core Web Vitals scores. Always reserve appropriate space for zone content.

​
Testing HTML Integration

​
Validation Checklist

  • Syntax verification - Correct HTML for your mode
  • Zone ID accuracy - Matches PureClarity campaign configuration
  • Template compilation - No Magento compilation errors
  • Content loading - Zones display recommendations correctly
  • Responsive behavior - Works across all device sizes
  • Fallback functionality - Graceful degradation when needed

​
Debug Mode Testing

Enable Zone Debug Mode to visualize zone placement:
  1. Enable debug mode in PureClarity configuration
  2. Clear Magento cache to apply changes
  3. Visit pages with HTML zones
  4. Verify zone placement and identifiers

​
Common Implementation Issues

​
Zone Not Displaying

Troubleshooting steps:
  1. Verify HTML syntax matches your configuration mode
  2. Check zone ID in both template and PureClarity admin
  3. Clear all caches (layout, blocks, page cache)
  4. Confirm template compilation without errors
  5. Test with debug mode enabled

​
Incorrect Content

Possible causes:
  • Zone ID mismatch between template and campaigns
  • Mode configuration doesn’t match HTML syntax
  • Campaign inactive or incorrectly configured
  • Feed data out of sync

​
Performance Issues

Optimization strategies:
  • Minimize zone count on single pages
  • Use appropriate caching strategies
  • Implement lazy loading for below-fold zones
  • Monitor server impact for server-side mode

​
Maintenance Best Practices

​
Version Control

  • Track template changes in version control systems
  • Document zone additions and modifications
  • Test across environments before production deployment
  • Maintain rollback capabilities for problematic changes

​
Regular Auditing

  • Review zone performance quarterly
  • Validate zone placement after theme updates
  • Check campaign alignment with business goals
  • Monitor user engagement with zone content

​
Update Procedures

  • Test zone functionality after Magento updates
  • Verify template compatibility with new versions
  • Update documentation when zones are modified
  • Coordinate with marketing on campaign changes

​
Alternative Integration Methods

​
Configuration Guides

​
Advanced Topics