Zone debug mode helps you visualize where PureClarity zones are positioned on your site, making it easier to troubleshoot zone placement and configuration issues.

​
Enabling Zone Debug Mode

To enable zone debug mode:
  1. Navigate to Stores > Configuration > PureClarity
  2. Expand the Advanced section
  3. Set Debug Mode to “Yes”
  4. Click “Save Config”
Advanced options settings in PureClarity configuration page showing Debug Mode setting
Debug mode should only be enabled during development or troubleshooting. Always disable it on production sites before going live.

​
What Debug Mode Shows

When debug mode is enabled, zones that aren’t populated by PureClarity will display their identification information instead of remaining invisible.

​
Debug Display Format

Unpopulated zones will show:
  • Zone Name - The descriptive name of the zone
  • Zone ID - The unique identifier used in campaigns
Example of a zone shown in debug mode with Zone ID displayed

​
When to Use Debug Mode

​
Development Scenarios

  • Initial zone setup - Verify zones appear in correct locations
  • Widget placement testing - Confirm layout updates work as intended
  • Theme integration - Check zone positioning with custom themes
  • Multi-store configuration - Validate zones on different store views

​
Troubleshooting Scenarios

  • Missing zones - Identify if zones are placed but not populated
  • Layout issues - Verify zone containers and positioning
  • Campaign connectivity - Distinguish between placement and content issues
  • Cache problems - Confirm zones render after cache clears
Debug mode only shows zones that are properly placed but not receiving content from PureClarity. Zones with configuration errors may not appear at all.

​
Interpreting Debug Information

​
Zone Visibility States

Debug DisplayMeaningNext Steps
Zone name + ID visibleZone placed correctly, no contentCheck campaign configuration
Nothing visibleZone not placed or disabledVerify widget/layout configuration
Fallback contentZone working, using backup contentNormal operation or campaign inactive

​
Common Debug Scenarios

Scenario 1: Zone ID Shows
  • Status: Zone placement successful
  • Issue: No active campaign or campaign mismatch
  • Solution: Check campaign configuration in PureClarity admin
Scenario 2: No Debug Display
  • Status: Zone not rendering at all
  • Issue: Widget configuration or cache problem
  • Solution: Review widget setup and clear caches
Scenario 3: Wrong Position
  • Status: Zone shows in unexpected location
  • Issue: Layout update configuration error
  • Solution: Adjust widget layout settings

​
Debug Mode Best Practices

​
Development Workflow

  1. Enable debug mode before testing new zones
  2. Test all pages where zones should appear
  3. Document zone positions and IDs for team reference
  4. Disable debug mode before production deployment

​
Troubleshooting Workflow

  1. Enable debug mode to visualize zone issues
  2. Check zone placement on affected pages
  3. Verify zone IDs match campaign configuration
  4. Test with campaigns active and inactive
  5. Disable debug mode after issue resolution
Take screenshots of debug displays to document zone layouts and share with team members or support staff.

​
Security and Performance Considerations

​
Production Environment

  • Never leave enabled on live sites
  • Test privately before public deployment
  • Use staging environments for extensive debugging
  • Monitor performance as debug mode may add slight overhead

​
Access Control

  • Limit admin access to configuration changes
  • Document debug procedures for team members
  • Use development copies of production data when possible
Debug information could potentially reveal site structure details to visitors. Always disable debug mode on public-facing sites.

​
Advanced Debugging Techniques

​
Browser Developer Tools

Combine debug mode with browser inspector to:
  • Examine HTML structure around debug displays
  • Check CSS styling affecting zone appearance
  • Monitor network requests for PureClarity content
  • Test responsive behavior across device sizes

​
Debug Mode + Cache Testing

  • Clear specific caches and check zone behavior
  • Test with cache disabled during development
  • Verify zone persistence across cache rebuilds

​
Configuration Validation

​
Zone Troubleshooting

​
Magento Resources

​
Disabling Debug Mode

After troubleshooting:
  1. Return to Stores > Configuration > PureClarity
  2. Set Debug Mode to “No”
  3. Click “Save Config”
  4. Clear relevant caches
  5. Verify zones display properly without debug information
Remember to clear page cache and block HTML output cache after disabling debug mode to ensure debug displays are fully removed from your site.