Aller au contenu principal

Microdata & SEO

Automatically generates Schema.org VideoObject structured data for your product videos, so search engines can display rich results — with a video thumbnail, duration, and play button — directly in Google search listings.

remarque

Available since v3.0.0

Overview​

When you enable microdata generation, the module fetches video metadata from YouTube and Vimeo's official APIs and outputs it as JSON-LD VideoObject markup in the <head> of each product page. For HTML5 self-hosted videos, the module builds the markup from the stored video title, URL, and thumbnail without any external API call.

Google uses this structured data to create video rich results: enhanced search listings that show a video thumbnail, the video title, and a duration badge alongside your product. These appear in both standard search and Google's dedicated video search tab, increasing click-through rates for products that have videos.

The metadata for each video is cached in your database for 7 days after the first page visit. Subsequent visits for the same video use the cached data, so API calls are minimal even on high-traffic stores. When the 7-day window expires, the module silently refreshes the data on the next page load.

YouTube microdata also captures view counts, comment counts, and keyword tags. Vimeo microdata captures play counts and tags. Both providers populate the interactionStatistic field, which is part of Google's recommended VideoObject properties.

Configuration​

  1. Go to Modules > Module Manager, find Product Video, and click Configure.
  2. Open the SEO & Microdata tab.
  3. Enable the master switch, enter your API credentials, and click Save.

Enable​

FieldValuesDefaultDescription
Add video microdata to the product pageOn / OffOffMaster switch. When on, the module outputs JSON-LD VideoObject markup on every product page that has an assigned video.

YouTube API​

FieldValuesDefaultDescription
API KeyText—Your YouTube Data API v3 key. Required to fetch titles, descriptions, thumbnails, upload dates, durations, and view counts for YouTube videos.

To get a YouTube API key:

  1. Go to console.developers.google.com and sign in.
  2. Create a project (or select an existing one).
  3. Enable the YouTube Data API v3 under APIs & Services.
  4. Go to Credentials, create a new API key, and copy it.
  5. Paste the key into the API Key field and save.

Without a valid YouTube API key, no microdata will be generated for YouTube videos — even if the master switch is on.

Vimeo API​

Vimeo requires three separate credentials obtained from a registered Vimeo developer application.

FieldValuesDefaultDescription
Vimeo Client IDText—The Client ID from your Vimeo app registration.
Vimeo Client SecretText—The Client Secret from your Vimeo app registration.
Vimeo App TokenText—The personal access token generated for your Vimeo app.

To get Vimeo API credentials:

  1. Go to developer.vimeo.com/apps and log in.
  2. Click Create app and fill in the required details.
  3. Once created, copy the Client ID and Client Secret from the app detail page.
  4. Under Personal access tokens, generate a new token with at least the public scope.
  5. Paste all three values into the corresponding fields and save.

All three Vimeo fields must be filled in together. If any one is missing, no Vimeo microdata will be generated.

HTML5 Videos​

FieldValuesDefaultDescription
HTML5 Videos TokenRead-only textAuto-generatedA security token generated automatically by the module. It is used internally by the front-end microdata capture controller for HTML5 videos. You do not need to copy or interact with this value.

Debug​

FieldValuesDefaultDescription
Enable API debug loggingOn / OffOffWhen on, any API errors (invalid key, network failure, video not found) are written to Back Office > Advanced Parameters > Logs. Enable temporarily when troubleshooting missing microdata, then turn off again.

How It Works​

YouTube and Vimeo videos​

When a customer opens a product page:

  1. The module checks whether microdata generation is enabled and whether the product has any YouTube or Vimeo videos.
  2. For each eligible video, it looks up the product_videos_microdata table in your database.
  3. If no cached entry exists, or if the cached entry is 7 or more days old, the module calls the YouTube Data API v3 (or Vimeo API) to retrieve: title, description, thumbnail URLs, upload date, duration, view count, and keyword tags.
  4. The metadata is saved to the database under that video's ID.
  5. A <script type="application/ld+json"> block containing the VideoObject markup is injected into the <head> of the product page.

On subsequent visits, steps 3–4 are skipped and the cached data is used directly, until 7 days have elapsed.

When a product has multiple videos, the module outputs a single JSON-LD block using the ItemList type, with each video as a numbered itemListElement. This lets Google understand that multiple videos are available for the product.

HTML5 self-hosted videos​

HTML5 videos do not require any external API. The module builds the VideoObject from the data already stored in your database: the video title, URL, and thumbnail path. Relative paths are automatically converted to absolute URLs.

The module also uses a front-end capture mechanism. The first time a visitor plays an HTML5 video, a lightweight AJAX call sends the video's actual duration (read from the browser's media element) to the module's microdata controller, which stores it in the cache. Subsequent generations of that video's microdata will include the real duration instead of the default PT0S placeholder.

HTML5 microdata is generated as soon as PV_GENERATE_MICRODATA is enabled — no API key required.

What is not supported​

Custom video providers and iframe-only embed providers do not generate VideoObject microdata. Only YouTube, Vimeo, and HTML5 video types are supported.

Usage Examples​

Example: Adding SEO microdata for a YouTube product demo

You sell a kitchen appliance and have a YouTube product demo video (e.g., https://www.youtube.com/watch?v=dQw4w9WgXcQ) assigned to the product. You enable Add video microdata, enter your YouTube API key, and save. On the next product page visit, the module fetches the video's title, description, thumbnail, and view count from YouTube and outputs a VideoObject block. Within a few days, Google's Rich Results Test confirms the structured data is valid and Google begins showing the video thumbnail in search results for the product.

Example: Using Vimeo microdata for a fashion brand

A clothing store hosts product videos privately on Vimeo. You create a Vimeo developer app, generate a personal access token with public scope, and enter all three credentials. After saving, product pages with Vimeo videos generate VideoObject markup including the Vimeo thumbnail, duration, and play count. Because caching is per video ID, adding the same Vimeo video to 30 product variants only results in one API call per 7-day cycle.

Example: Self-hosted HTML5 video with duration capture

A store hosts .mp4 product videos on their own server and has no API access. After enabling microdata generation (no API key needed for HTML5), each product page immediately outputs a basic VideoObject with the title, thumbnail, and content URL. The first time a real visitor plays the video in their browser, the actual duration is silently captured and stored. All future microdata for that video includes the correct ISO 8601 duration (e.g., PT2M35S).

Important Notes​

  • API keys are required for YouTube and Vimeo. The master switch alone is not enough for hosted-platform videos. Without a valid key, those videos produce no microdata.
  • Custom providers are not supported. Only YouTube, Vimeo, and HTML5 video types generate VideoObject markup.
  • Caching is per video ID, not per product. The same YouTube or Vimeo video shared across 50 products triggers only one API call per 7-day window.
  • Google indexing is not instant. After enabling microdata, use Google's Rich Results Test to validate the markup, but allow several days to a few weeks for Google to begin displaying rich results in search.
  • HTML5 video duration starts as PT0S. The real duration is only captured after the first real browser playback. If you need accurate durations immediately, you can manually update the product_videos_microdata table.
  • Multi-shop: Microdata is cached globally (not per shop). The same cached VideoObject is served across all shops in a multi-shop setup. If shops serve different videos for the same product, they share the same cache entry.
  • Videos must be publicly accessible. If a YouTube or Vimeo video is set to private or unlisted, the API may return incomplete data or an error, resulting in no microdata for that video.

Troubleshooting​

ProblemSolution
No JSON-LD block appears in the page sourceConfirm Add video microdata is enabled and the product has at least one YouTube, Vimeo, or HTML5 video assigned. Custom providers never generate microdata.
YouTube videos have no microdataCheck that your YouTube Data API v3 key is correct and the API is enabled in Google Cloud Console. Enable API debug logging and review Back Office > Advanced Parameters > Logs for the specific error.
Vimeo videos have no microdataVerify that all three Vimeo fields (Client ID, Client Secret, App Token) are filled in. A missing token is the most common cause. Enable API debug logging to see the API response.
Google Rich Results Test shows missing required fieldsThe API returned incomplete data, usually because the video is private or unlisted. Make the video public on YouTube or Vimeo and wait for the 7-day cache to expire.
Microdata is stale after you updated a videoThe 7-day cache has not expired. To force an immediate refresh, delete the matching row from the product_videos_microdata table in your database, then reload the product page.
HTML5 video duration always shows as PT0SThe front-end capture controller has not yet received a real browser playback for that video. Visit the product page yourself and play the video fully; the duration will be stored after the AJAX call completes.

Frequently Asked Questions​

Do I need both a YouTube key and Vimeo credentials if my store uses both providers?

Yes. Each provider requires its own credentials. You can configure them independently — enabling YouTube metadata without Vimeo (or vice versa) works fine for the videos of that provider. Videos from a provider without credentials simply produce no microdata.

Will enabling microdata slow down my product pages?

Only on the very first visit for each video, when the module calls the YouTube or Vimeo API. After that, the cached data is read directly from your database with a single SQL query. API calls have a 2-second timeout, so worst case a new video adds a small delay on its first load only.

My product has three videos from different providers — what does the structured data look like?

The module outputs a single JSON-LD block using the Schema.org `ItemList` type, with each video listed as a numbered `itemListElement`. Google can read this as a list of related videos for the product. Only providers that have valid credentials (or HTML5 videos) appear in the list.

Can I use this feature without any Google or Vimeo API account?

Yes, if all your product videos are HTML5 self-hosted files. HTML5 microdata is generated from locally stored data — no external API is needed. YouTube and Vimeo videos require their respective API credentials to generate structured data.

How do I know if my microdata is valid before Google indexes it?

Use Google's [Rich Results Test](https://search.google.com/test/rich-results) — paste your product page URL and it will show you whether the VideoObject structured data is valid, what fields are present, and any warnings. Run this after enabling the feature and before expecting results in search.

What happens if the YouTube API quota is exhausted?

YouTube Data API v3 has a daily quota (default 10,000 units per project). If the quota runs out, the API returns an error. With **API debug logging** enabled, you will see these errors in **Back Office > Advanced Parameters > Logs**. Because microdata is cached for 7 days, quota consumption is much lower than one API call per page view — it is one call per video per 7 days.