Saltar al contenido principal

Microdatos y SEO

Genera automáticamente datos estructurados Schema.org VideoObject para los vídeos de tus productos, para que los motores de búsqueda puedan mostrar resultados enriquecidos — con miniatura del vídeo, duración y botón de reproducción — directamente en los listados de búsqueda de Google.

nota

Disponible desde v3.0.0

Descripción general​

Cuando activas la generación de microdatos, el módulo obtiene los metadatos de los vídeos desde las APIs oficiales de YouTube y Vimeo y los genera como marcado JSON-LD VideoObject en el <head> de cada página de producto. Para los vídeos HTML5 alojados localmente, el módulo construye el marcado a partir del título, la URL y la miniatura del vídeo almacenados, sin ninguna llamada a API externa.

Google utiliza estos datos estructurados para crear resultados enriquecidos de vídeo: listados de búsqueda mejorados que muestran una miniatura del vídeo, el título y un indicador de duración junto a tu producto. Aparecen tanto en la búsqueda estándar como en la pestaña de búsqueda de vídeos de Google, lo que aumenta la tasa de clics para los productos que tienen vídeos.

Los metadatos de cada vídeo se almacenan en caché en tu base de datos durante 7 días tras la primera visita a la página. Las visitas posteriores para el mismo vídeo usan los datos almacenados en caché, por lo que las llamadas a la API son mínimas incluso en tiendas con mucho tráfico. Cuando expiran los 7 días, el módulo actualiza los datos de forma silenciosa en la siguiente carga de página.

Los microdatos de YouTube también capturan el número de visualizaciones, comentarios y etiquetas de palabras clave. Los de Vimeo capturan el número de reproducciones y etiquetas. Ambos proveedores rellenan el campo interactionStatistic, que forma parte de las propiedades VideoObject recomendadas por Google.

Configuración​

  1. Ve a Módulos > Gestor de módulos, busca Product Video y haz clic en Configurar.
  2. Abre la pestaña SEO y Microdatos.
  3. Activa el interruptor principal, introduce tus credenciales de API y haz clic en Guardar.

Activar​

CampoValoresPredeterminadoDescripción
Añadir microdatos de vídeo a la página de productoActivado / DesactivadoDesactivadoInterruptor principal. Cuando está activado, el módulo genera marcado JSON-LD VideoObject en cada página de producto que tenga un vídeo asignado.

API de YouTube​

CampoValoresPredeterminadoDescripción
Clave APITexto—Tu clave de YouTube Data API v3. Necesaria para obtener títulos, descripciones, miniaturas, fechas de subida, duraciones y número de visualizaciones de los vídeos de YouTube.

Para obtener una clave de API de YouTube:

  1. Ve a console.developers.google.com e inicia sesión.
  2. Crea un proyecto (o selecciona uno existente).
  3. Activa la YouTube Data API v3 en APIs y Servicios.
  4. Ve a Credenciales, crea una nueva clave de API y cópiala.
  5. Pega la clave en el campo Clave API y guarda.

Sin una clave de API de YouTube válida, no se generarán microdatos para los vídeos de YouTube, aunque el interruptor principal esté activado.

API de Vimeo​

Vimeo requiere tres credenciales separadas obtenidas desde una aplicación de desarrollador de Vimeo registrada.

CampoValoresPredeterminadoDescripción
Vimeo Client IDTexto—El Client ID de tu registro de aplicación de Vimeo.
Vimeo Client SecretTexto—El Client Secret de tu registro de aplicación de Vimeo.
Vimeo App TokenTexto—El token de acceso personal generado para tu aplicación de Vimeo.

Para obtener las credenciales de la API de Vimeo:

  1. Ve a developer.vimeo.com/apps e inicia sesión.
  2. Haz clic en Create app y completa los datos requeridos.
  3. Una vez creada, copia el Client ID y el Client Secret desde la página de detalle de la aplicación.
  4. En Personal access tokens, genera un nuevo token con al menos el alcance public.
  5. Pega los tres valores en los campos correspondientes y guarda.

Los tres campos de Vimeo deben rellenarse juntos. Si falta cualquiera de ellos, no se generarán microdatos de Vimeo.

Vídeos HTML5​

CampoValoresPredeterminadoDescripción
HTML5 Videos TokenTexto de solo lecturaGenerado automáticamenteUn token de seguridad generado automáticamente por el módulo. Se utiliza internamente por el controlador de captura de microdatos del front-end para vídeos HTML5. No es necesario copiarlo ni interactuar con este valor.

Depuración​

CampoValoresPredeterminadoDescripción
Activar registro de depuración de APIActivado / DesactivadoDesactivadoCuando está activado, cualquier error de la API (clave inválida, fallo de red, vídeo no encontrado) se escribe en Back Office > Parámetros avanzados > Registros. Actívalo temporalmente al diagnosticar microdatos ausentes y desactívalo después.

Cómo funciona​

Vídeos de YouTube y Vimeo​

Cuando un cliente abre una página de producto:

  1. El módulo comprueba si la generación de microdatos está activada y si el producto tiene algún vídeo de YouTube o Vimeo.
  2. Para cada vídeo elegible, consulta la tabla product_videos_microdata en tu base de datos.
  3. Si no existe ninguna entrada en caché, o si la entrada tiene 7 o más días de antigüedad, el módulo llama a la YouTube Data API v3 (o a la API de Vimeo) para obtener: título, descripción, URLs de miniaturas, fecha de subida, duración, número de visualizaciones y etiquetas de palabras clave.
  4. Los metadatos se guardan en la base de datos bajo el ID de ese vídeo.
  5. Un bloque <script type="application/ld+json"> con el marcado VideoObject se inyecta en el <head> de la página de producto.

En visitas posteriores, los pasos 3–4 se omiten y los datos en caché se usan directamente, hasta que transcurren 7 días.

Cuando un producto tiene varios vídeos, el módulo genera un único bloque JSON-LD usando el tipo ItemList, con cada vídeo como un itemListElement numerado. Esto permite a Google entender que hay varios vídeos disponibles para el producto.

Vídeos HTML5 alojados localmente​

Los vídeos HTML5 no requieren ninguna API externa. El módulo construye el VideoObject a partir de los datos ya almacenados en tu base de datos: el título del vídeo, la URL y la ruta de la miniatura. Las rutas relativas se convierten automáticamente en URLs absolutas.

El módulo también utiliza un mecanismo de captura en el front-end. La primera vez que un visitante reproduce un vídeo HTML5, una llamada AJAX ligera envía la duración real del vídeo (leída desde el elemento multimedia del navegador) al controlador de microdatos del módulo, que la almacena en caché. Las generaciones posteriores de los microdatos de ese vídeo incluirán la duración real en lugar del marcador de posición predeterminado PT0S.

Los microdatos HTML5 se generan en cuanto PV_GENERATE_MICRODATA está activado — no se requiere clave de API.

Lo que no está soportado​

Los proveedores de vídeo personalizados y los proveedores que solo admiten incrustación mediante iframe no generan microdatos VideoObject. Solo se admiten los tipos de vídeo YouTube, Vimeo y HTML5.

Ejemplos de uso​

Ejemplo: Añadir microdatos SEO para una demostración de producto en YouTube

Vendes un electrodoméstico de cocina y tienes un vídeo de demostración de producto en YouTube (por ejemplo, https://www.youtube.com/watch?v=dQw4w9WgXcQ) asignado al producto. Activas Añadir microdatos de vídeo, introduces tu clave de API de YouTube y guardas. En la siguiente visita a la página de producto, el módulo obtiene el título, descripción, miniatura y número de visualizaciones del vídeo desde YouTube y genera un bloque VideoObject. En pocos días, la Prueba de Resultados Enriquecidos de Google confirma que los datos estructurados son válidos y Google comienza a mostrar la miniatura del vídeo en los resultados de búsqueda del producto.

Ejemplo: Usar microdatos de Vimeo para una marca de moda

Una tienda de ropa aloja vídeos de producto de forma privada en Vimeo. Creas una aplicación de desarrollador de Vimeo, generas un token de acceso personal con alcance public e introduces las tres credenciales. Tras guardar, las páginas de producto con vídeos de Vimeo generan marcado VideoObject que incluye la miniatura, la duración y el número de reproducciones de Vimeo. Como el almacenamiento en caché es por ID de vídeo, añadir el mismo vídeo de Vimeo a 30 variantes de producto solo genera una llamada a la API por cada ciclo de 7 días.

Ejemplo: Vídeo HTML5 alojado localmente con captura de duración

Una tienda aloja vídeos de producto .mp4 en su propio servidor y no tiene acceso a ninguna API. Tras activar la generación de microdatos (no se necesita clave de API para HTML5), cada página de producto genera inmediatamente un VideoObject básico con el título, la miniatura y la URL del contenido. La primera vez que un visitante real reproduce el vídeo en su navegador, la duración real se captura de forma silenciosa y se almacena. Todos los microdatos futuros de ese vídeo incluyen la duración ISO 8601 correcta (por ejemplo, PT2M35S).

Notas importantes​

  • Las claves de API son necesarias para YouTube y Vimeo. El interruptor principal por sí solo no es suficiente para los vídeos de plataformas alojadas. Sin una clave válida, esos vídeos no producen microdatos.
  • Los proveedores personalizados no están soportados. Solo los tipos de vídeo YouTube, Vimeo y HTML5 generan marcado VideoObject.
  • El almacenamiento en caché es por ID de vídeo, no por producto. El mismo vídeo de YouTube o Vimeo compartido en 50 productos solo genera una llamada a la API por ventana de 7 días.
  • La indexación de Google no es inmediata. Tras activar los microdatos, usa la Prueba de Resultados Enriquecidos de Google para validar el marcado, pero permite varios días o algunas semanas para que Google empiece a mostrar resultados enriquecidos en la búsqueda.
  • La duración del vídeo HTML5 empieza como PT0S. La duración real solo se captura tras la primera reproducción real en el navegador. Si necesitas duraciones precisas de inmediato, puedes actualizar manualmente la tabla product_videos_microdata.
  • Multi-tienda: Los microdatos se almacenan en caché de forma global (no por tienda). El mismo VideoObject en caché se sirve a todas las tiendas en una configuración multi-tienda. Si las tiendas sirven vídeos diferentes para el mismo producto, comparten la misma entrada de caché.
  • Los vídeos deben ser de acceso público. Si un vídeo de YouTube o Vimeo está configurado como privado o no listado, la API puede devolver datos incompletos o un error, lo que resultará en la ausencia de microdatos para ese vídeo.

Solución de problemas​

ProblemaSolución
No aparece ningún bloque JSON-LD en el código fuente de la páginaConfirma que Añadir microdatos de vídeo está activado y que el producto tiene al menos un vídeo de YouTube, Vimeo o HTML5 asignado. Los proveedores personalizados nunca generan microdatos.
Los vídeos de YouTube no tienen microdatosComprueba que tu clave de YouTube Data API v3 es correcta y que la API está activada en Google Cloud Console. Activa el Registro de depuración de API y revisa Back Office > Parámetros avanzados > Registros para ver el error específico.
Los vídeos de Vimeo no tienen microdatosVerifica que los tres campos de Vimeo (Client ID, Client Secret, App Token) estén rellenados. Un token faltante es la causa más frecuente. Activa el Registro de depuración de API para ver la respuesta de la API.
La Prueba de Resultados Enriquecidos de Google muestra campos requeridos ausentesLa API devolvió datos incompletos, normalmente porque el vídeo es privado o no está listado. Haz el vídeo público en YouTube o Vimeo y espera a que expire la caché de 7 días.
Los microdatos están desactualizados tras actualizar un vídeoLa caché de 7 días no ha expirado. Para forzar una actualización inmediata, elimina la fila correspondiente de la tabla product_videos_microdata en tu base de datos y recarga la página del producto.
La duración del vídeo HTML5 siempre aparece como PT0SEl controlador de captura del front-end aún no ha recibido una reproducción real en el navegador para ese vídeo. Visita la página del producto y reproduce el vídeo completamente; la duración se almacenará tras completarse la llamada AJAX.

Preguntas frecuentes​

¿Necesito tanto una clave de YouTube como credenciales de Vimeo si mi tienda usa ambos proveedores?

Sí. Cada proveedor requiere sus propias credenciales. Puedes configurarlos de forma independiente: activar los metadatos de YouTube sin Vimeo (o viceversa) funciona perfectamente para los vídeos de ese proveedor. Los vídeos de un proveedor sin credenciales simplemente no generan microdatos.

¿Activar los microdatos ralentizará las páginas de producto?

Solo en la primera visita para cada vídeo, cuando el módulo llama a la API de YouTube o Vimeo. Después, los datos en caché se leen directamente de tu base de datos con una única consulta SQL. Las llamadas a la API tienen un tiempo de espera de 2 segundos, por lo que en el peor caso un vídeo nuevo añade un pequeño retraso solo en su primera carga.

Mi producto tiene tres vídeos de diferentes proveedores, ¿cómo quedan los datos estructurados?

El módulo genera un único bloque JSON-LD usando el tipo Schema.org ItemList, con cada vídeo listado como un itemListElement numerado. Google puede leer esto como una lista de vídeos relacionados para el producto. Solo aparecen en la lista los proveedores que tienen credenciales válidas (o los vídeos HTML5).

¿Puedo usar esta función sin ninguna cuenta de Google o Vimeo?

Sí, si todos tus vídeos de producto son archivos HTML5 alojados localmente. Los microdatos HTML5 se generan a partir de los datos almacenados localmente — no se necesita ninguna API externa. Los vídeos de YouTube y Vimeo requieren sus respectivas credenciales de API para generar datos estructurados.

¿Cómo sé si mis microdatos son válidos antes de que Google los indexe?

Usa la Prueba de Resultados Enriquecidos de Google — pega la URL de la página de tu producto y te mostrará si los datos estructurados VideoObject son válidos, qué campos están presentes y cualquier advertencia. Ejecuta esta prueba tras activar la función y antes de esperar resultados en la búsqueda.

¿Qué ocurre si se agota la cuota de la API de YouTube?

La YouTube Data API v3 tiene una cuota diaria (10.000 unidades por proyecto de forma predeterminada). Si se agota la cuota, la API devuelve un error. Con el registro de depuración de API activado, verás estos errores en Back Office > Parámetros avanzados > Registros. Dado que los microdatos se almacenan en caché durante 7 días, el consumo de cuota es mucho menor que una llamada a la API por cada visualización de página: es una llamada por vídeo cada 7 días.

Funciones relacionadas​