Skip to content

SEO Rich Snippets - Configuration

This document provides complete instructions for configuring the SEO Rich Snippets module in Magento 2.

Initial configuration

Module is disabled by default and needs to be enabled in the Admin Panel.

Admin Panel Configuration

Enabling the Module

  1. Log into the Admin Panel
  2. Navigate to: Stores → Configuration → Qoliber → SEO: Rich Snippets
  3. Open the Settings section
  4. Set Enabled to Yes
  5. Click Save Config
  6. Flush caches

Debug Mode

The module supports different rendering modes for the JSON-LD output:

Available Modes:

  • minified (Default) - Compact JSON output, recommended for production
  • pretty - Pretty-printed JSON with indentation, useful for debugging
  • disabled - No JSON-LD output

To configure:

  1. Navigate to: Stores → Configuration → Qoliber → SEO: Rich Snippets
  2. Open the Settings section
  3. Set Debug Mode to your preferred option
  4. Click Save Config

Production Settings

Always use minified mode in production for optimal page load performance.

Managing Snippets

Accessing Snippet Management

Navigate to: Content → SEO Rich Snippets → Snippets

This grid shows all snippets with: - Name and identifier - Active status - Page types where the snippet appears - Store views - Actions (Edit/Delete)

Creating a New Snippet

  1. Click Add New Snippet button
  2. Fill in the required fields (see below)
  3. Click Save
  4. Flush caches

Snippet Configuration Fields

General Information

Name (Required) - Display name for the snippet in admin - Example: "Product Schema", "Organization Info"

Identifier (Required) - Unique identifier for referencing in templates - Used in {{snippet.identifier}} syntax - Lowercase, alphanumeric, hyphens only - Example: product-schema, organization

Active (Required) - Enable/disable the snippet - Options: Yes/No - Inactive snippets are not rendered

Store View (Required) - Select which store views should display this snippet - Multi-select field - Choose "All Store Views" for global snippets

Page Targeting

You can target snippets to appear on specific pages using one or more methods:

Page Types (Multi-select) - homepage - Store homepage - product - Product detail pages - category - Category listing pages - cms - CMS pages (use CMS Page IDs for specific pages) - contact - Contact page - search - Search results page

CMS Page IDs (Multi-select) - Select specific CMS pages - Only applies when page type is "cms" or left empty - Example: About Us, Terms & Conditions pages

Custom URL Pattern - Match pages by URL pattern - Supports wildcards with * - Examples: - /sale/* - All URLs starting with /sale/ - /blog/*/view - Blog post detail pages - /special-offer - Exact match

Custom Handle - Match by Magento layout handle - Exact match only - Examples: - catalog_product_view - cms_index_index - catalog_category_view

Targeting Priority

If multiple targeting methods are used, the snippet will appear if any condition matches (OR logic).

JSON Schema Template

JSON Schema (Required) - The JSON-LD template with variables and DJson syntax - Supports: - Variables: {{variable.name}} - Nested snippets: {{snippet.identifier}} - Conditionals: @djson if condition - Loops: @djson for collection as item

See DJson Syntax for complete reference.

Store Configuration Requirements

For the default snippets to work properly, configure these Magento settings:

Store Information

Path: Stores → Configuration → General → Store Information

Required fields: - Store Name - Used in Organization and LocalBusiness schemas - Store Phone Number - Contact information - Store Address: - Street Address (Line 1) - City - ZIP/Postal Code - Country

Store Email Addresses

Path: Stores → Configuration → General → Store Email Addresses

Required fields: - General Contact - Sender Name - Sender Email

Path: Content → Design → Configuration → Select Store View → Edit

Upload your logo to: pub/media/logo/default/logo.svg

Or configure the logo path in the snippet template.

Default Snippet Configuration

After installation, review and enable the default snippets:

Always Enabled

These snippets should generally remain active:

  1. Organization (Homepage)

    • Company information
    • Requires: Store name, phone, email, address

  2. WebSite (Homepage)

    • Search box functionality
    • Requires: Base URL

  3. Product (Product Pages)

    • Product details with offers and reviews
    • Requires: Product data (automatic)

Enable as Needed

  1. BreadcrumbList (Product/Category Pages)

    • Navigation breadcrumbs
    • Automatic data from page breadcrumbs

  2. LocalBusiness (Contact Page)

    • Physical store location
    • Requires: Store information, opening hours configuration

  3. FAQPage (FAQ Pages)

    • Frequently asked questions
    • Requires: Manual configuration with questions/answers

Testing Rich Snippets

Google Rich Results Test

  1. Visit Google Rich Results Test
  2. Enter your product/page URL
  3. Click Test URL
  4. Review detected structured data
  5. Fix any errors or warnings

Manual Testing

  1. Visit a page where snippet should appear
  2. View page source (Ctrl+U / Cmd+U)
  3. Search for application/ld+json
  4. Verify JSON structure is valid
  5. Check that variables are resolved (no {{...}} remaining)

Debug Mode Testing

  1. Enable pretty debug mode
  2. Visit page
  3. View source
  4. JSON will be formatted with indentation for easy reading

Common Configuration Scenarios

Scenario: Different Snippets Per Store View

  1. Create snippet for Store View A

    • Select only "Store View A" in Store View field
    • Configure language-specific content

  2. Duplicate snippet for Store View B

    • Change identifier (e.g., product-schema-de)
    • Select only "Store View B"
    • Translate content

Scenario: Custom Product Page URL

If using custom product URL structure:

  1. Edit Product snippet
  2. Clear Page Types
  3. Set Custom URL Pattern: /products/*
  4. Save

Scenario: Disable Reviews

  1. Edit Product snippet
  2. Remove the @djson if product.reviewCount section
  3. Save
  4. Reviews will no longer appear in schema

Scenario: Add Custom Fields

To add custom product attributes:

  1. Edit Product snippet
  2. Add variable: {{product.your_attribute_code}}
  3. Save
  4. Attribute value will be automatically resolved

Troubleshooting

Snippet Not Appearing

  1. Check snippet is Active: Yes
  2. Verify Store View is correct
  3. Check page targeting settings match current page
  4. Flush all caches
  5. Check page source for application/ld+json

Variables Not Resolving

  1. Enable pretty debug mode
  2. Check for remaining {{...}} in output
  3. Verify variable path is correct (see Variables Reference)
  4. Check debug logs: var/log/debug.log

Invalid JSON

  1. Use JSONLint to validate
  2. Check for missing commas
  3. Verify DJson syntax is correct
  4. Check for unescaped quotes in content

Performance Issues

  1. Use minified mode in production
  2. Disable unused snippets
  3. Avoid complex nested loops
  4. Cache configuration properly

Best Practices

  1. Start with defaults - Review and customize pre-installed snippets before creating new ones
  2. Test thoroughly - Always test with Google Rich Results Test
  3. Keep it simple - Start with basic snippets, add complexity as needed
  4. Use conditions - Hide optional sections with @djson if when data might not exist
  5. Minify in production - Only use pretty mode for debugging
  6. Document changes - Add comments in snippet names for custom modifications
  7. Version control - Export/backup snippet JSON before major changes

Next Steps