Early Access

Magento 2 integration tutorial

Add Open Graph Metadata to Magento

Install, configure, verify, and operate the standalone Mosaicora Open Graph extension across Magento storefront pages.

What you will build

A Magento 2, Mage-OS, or Adobe Commerce storefront that publishes Open Graph and optional Twitter Card metadata with cached 1200×630 images from local catalog and CMS media.

Package: mosaicora/module-opengraphPlatforms: Magento 2, Mage-OS, Adobe CommerceRuntime: PHP 8.1–8.5Themes: Luma and Hyvä compatible
View on GitHubOpen live demo

Before you begin

  • Magento 2, Mage-OS, or Adobe Commerce with Catalog, CMS, Store, Web API, and GraphQL modules enabled.
  • PHP 8.1 through 8.5 and command-line access to the Magento project root.
  • Composer credentials for repo.magento.com when the Magento dependency tree requires them.
  • A deployment window for setup:upgrade, cache invalidation, and production compilation when applicable.
1

Step 1

Install and enable the module

Add the Composer package, register the module, and refresh Magento configuration.

Run every command from the Magento project root. Do not run composer install inside a mounted or symlinked module directory because a nested vendor tree can cause duplicate class loading.

Install and enable

composer require mosaicora/module-opengraph

bin/magento module:enable Mosaicora_OpenGraph
bin/magento setup:upgrade
bin/magento cache:flush config layout block_html eav full_page config_webservice

Production deployment

Run these when required by your normal production deployment process.

bin/magento setup:di:compile
bin/magento setup:static-content:deploy

Expected result

  • Mosaicora_OpenGraph is enabled.
  • setup:upgrade completes successfully.
  • Magento caches are refreshed.
2

Step 2

Configure storefront defaults

Enable metadata and set store-scoped defaults from the Magento admin.

Open Stores > Configuration > Mosaicora > Open Graph. Configuration is store-scoped where Magento supports it, so verify the selected website and store view before saving.

Under General, enable Open Graph tags, set the site name and default image, and choose whether to mirror values into Twitter Card tags.

Under Image Optimization, keep the default 1200×630 dimensions unless your publishing requirements need another size. Local Magento media can be resized and cached; external URLs are emitted unchanged.

Expected result

  • Open Graph tags are enabled for the intended store view.
  • A site name and usable default image are configured.
  • Image optimization settings match the desired social-card dimensions.
3

Step 3

Choose page-specific content

Control title, description, and image sources for products, categories, CMS pages, and the home page.

Configure product, category, and CMS source fields under Content Defaults. The module falls back through Magento’s existing metadata and content fields when a dedicated Open Graph value is not present.

Use the Open Graph fields on individual products, categories, and CMS pages when a page needs a deliberate social title, description, or image instead of the store-wide default.

Expected result

  • A product resolves a title, description, and image.
  • Category and CMS pages have suitable fallbacks.
  • The home page has a site name and default image.
4

Step 4

Resolve competing social tags

Ensure one extension or theme owns each Open Graph metadata key.

Disable Open Graph output from the theme or another SEO extension whenever possible. Duplicate og:title or og:image values make crawler behavior unpredictable.

If competing output cannot be disabled, enable Remove Competing Social Tags under General. The option removes only keys generated by Mosaicora and leaves unrelated metadata untouched.

5

Step 5

Verify every storefront page type

Inspect product, category, CMS, and home pages before sharing them publicly.

Flush full-page cache after configuration changes, open a public storefront URL, and inspect its initial HTML for Open Graph and optional Twitter Card tags.

Run representative product, category, CMS, and home URLs through the Open Graph Checker. Confirm the image is reachable, has the intended dimensions, and matches the selected store view.

Refresh relevant caches

bin/magento cache:flush config layout block_html full_page

Expected result

  • Product metadata includes price and availability when applicable.
  • Category, CMS, and home pages resolve their intended images.
  • No duplicate social metadata keys remain.

Reference

Advanced usage

REST and GraphQL metadata

Read the same resolved storefront metadata through public APIs for preview tools and headless storefronts.

  • GET /V1/mosaicora/opengraph/product/:sku
  • GET /V1/mosaicora/opengraph/category/:categoryId
  • GET /V1/mosaicora/opengraph/cms/:identifier
  • GET /V1/mosaicora/opengraph/home
  • ProductInterface.open_graph and CategoryInterface.open_graph
  • CmsPage.open_graph and StoreConfig.home_open_graph

Product GraphQL query

query ProductOpenGraph($sku: String!) {
  products(filter: { sku: { eq: $sku } }) {
    items {
      open_graph {
        enabled
        tags { name content }
      }
    }
  }
}

Default resolution and cache behavior

Understand where values and generated images come from when no explicit override exists.

  • Products fall back from meta_title to name and from meta_description to short_description or description.
  • Product images fall back from open_graph_image to image and small_image.
  • Categories and CMS pages use their metadata fields, content fields, and configured defaults.
  • Generated images are cached under pub/media/mosaicora/opengraph/cache.
  • Authorized administrators can clear generated Open Graph images from cache management.
  • Store-scoped ACL resources protect configuration and image-cache management.

Live examples

Inspect working category and product metadata on the Mosaicora Magento demo.

Bags categoryCategory metadata with a generated social image.Joust Duffle BagProduct metadata with price and availability.Voyage Yoga BagA second product using the default resolution workflow.

Help

Troubleshooting

No Open Graph tags appear

Confirm Mosaicora_OpenGraph is enabled, select the correct store scope, enable Open Graph Tags, and flush config, layout, block, and full-page caches.

The wrong image or text is selected

Review the page-specific Open Graph fields, configured content source attributes, and fallback order for that product, category, or CMS page.

Generated images stay stale

Clear generated Open Graph images through Magento cache management, then flush full-page cache. The cache key also changes when the local source file modification time changes.

Metadata appears twice

Disable social metadata in the competing theme or extension. If that is impossible, enable Remove Competing Social Tags for the affected store view.

Continue learning

Next.js integration

Follow the native App Router tutorial.

Open Graph Checker

Inspect the metadata and social image published by a public page.

All integrations

Compare the available Mosaicora integration paths.

Build Better Open Graph Images

Join the waitlist and tell us what your publishing workflow needs.