Microdata e SEO
Genera automaticamente i dati strutturati Schema.org VideoObject per i video dei tuoi prodotti, così i motori di ricerca possono mostrare risultati arricchiti — con miniatura del video, durata e pulsante di riproduzione — direttamente nei risultati di ricerca di Google.
Disponibile dalla v3.0.0
Panoramica
Quando abiliti la generazione dei microdata, il modulo recupera i metadati video dalle API ufficiali di YouTube e Vimeo e li inserisce come markup JSON-LD VideoObject nel <head> di ogni pagina prodotto. Per i video HTML5 ospitati autonomamente, il modulo costruisce il markup a partire dal titolo del video, dall'URL e dalla miniatura archiviati, senza alcuna chiamata API esterna.
Google utilizza questi dati strutturati per creare rich result video: risultati di ricerca arricchiti che mostrano una miniatura del video, il titolo e un indicatore della durata accanto al tuo prodotto. Questi appaiono sia nella ricerca standard sia nella scheda di ricerca video dedicata di Google, aumentando il tasso di clic per i prodotti che dispongono di video.
I metadati di ogni video vengono memorizzati nella cache del database per 7 giorni dopo la prima visita alla pagina. Le visite successive per lo stesso video utilizzano i dati nella cache, quindi le chiamate API sono minime anche nei negozi ad alto traffico. Quando scadono i 7 giorni, il modulo aggiorna silenziosamente i dati al successivo caricamento della pagina.
I microdata di YouTube includono anche numero di visualizzazioni, numero di commenti e tag. I microdata di Vimeo includono conteggio delle riproduzioni e tag. Entrambi i provider popolano il campo interactionStatistic, che fa parte delle proprietà VideoObject consigliate da Google.
Configurazione
- Vai su Moduli > Gestione moduli, trova Product Video e clicca su Configura.
- Apri la scheda SEO & Microdata.
- Abilita l'interruttore principale, inserisci le credenziali API e clicca su Salva.
Abilita
| Campo | Valori | Predefinito | Descrizione |
|---|---|---|---|
| Aggiungi microdata video alla pagina prodotto | Sì / No | No | Interruttore principale. Se attivo, il modulo inserisce il markup JSON-LD VideoObject in ogni pagina prodotto a cui è assegnato un video. |
API YouTube
| Campo | Valori | Predefinito | Descrizione |
|---|---|---|---|
| API Key | Testo | — | La tua chiave YouTube Data API v3. Necessaria per recuperare titoli, descrizioni, miniature, date di caricamento, durate e conteggio visualizzazioni dei video YouTube. |
Per ottenere una chiave API YouTube:
- Vai su console.developers.google.com e accedi.
- Crea un progetto (o selezionane uno esistente).
- Abilita la YouTube Data API v3 in API e servizi.
- Vai su Credenziali, crea una nuova chiave API e copiala.
- Incolla la chiave nel campo API Key e salva.
Senza una chiave API YouTube valida, non verrà generato alcun microdata per i video YouTube — anche se l'interruttore principale è attivo.
API Vimeo
Vimeo richiede tre credenziali separate, ottenute da un'applicazione sviluppatore Vimeo registrata.
| Campo | Valori | Predefinito | Descrizione |
|---|---|---|---|
| Vimeo Client ID | Testo | — | Il Client ID dalla registrazione della tua app Vimeo. |
| Vimeo Client Secret | Testo | — | Il Client Secret dalla registrazione della tua app Vimeo. |
| Vimeo App Token | Testo | — | Il token di accesso personale generato per la tua app Vimeo. |
Per ottenere le credenziali API Vimeo:
- Vai su developer.vimeo.com/apps e accedi.
- Clicca su Create app e compila i dettagli richiesti.
- Una volta creata, copia il Client ID e il Client Secret dalla pagina di dettaglio dell'app.
- Nella sezione Personal access tokens, genera un nuovo token con almeno lo scope
public. - Incolla tutti e tre i valori nei campi corrispondenti e salva.
Tutti e tre i campi Vimeo devono essere compilati insieme. Se manca anche solo uno, non verrà generato alcun microdata Vimeo.
Video HTML5
| Campo | Valori | Predefinito | Descrizione |
|---|---|---|---|
| HTML5 Videos Token | Testo in sola lettura | Generato automaticamente | Un token di sicurezza generato automaticamente dal modulo. Viene utilizzato internamente dal controller front-end per la cattura dei microdata dei video HTML5. Non è necessario copiare o interagire con questo valore. |
Debug
| Campo | Valori | Predefinito | Descrizione |
|---|---|---|---|
| Abilita log di debug API | Sì / No | No | Se attivo, qualsiasi errore API (chiave non valida, errore di rete, video non trovato) viene scritto in Back Office > Parametri avanzati > Log. Abilitalo temporaneamente durante la risoluzione di problemi con i microdata mancanti, poi disattivalo. |
Come Funziona
Video YouTube e Vimeo
Quando un cliente apre una pagina prodotto:
- Il modulo verifica se la generazione dei microdata è abilitata e se il prodotto ha video YouTube o Vimeo assegnati.
- Per ogni video idoneo, controlla la tabella
product_videos_microdatanel database. - Se non esiste una voce nella cache, o se è più vecchia di 7 giorni, il modulo chiama la YouTube Data API v3 (o l'API Vimeo) per recuperare: titolo, descrizione, URL delle miniature, data di caricamento, durata, numero di visualizzazioni e tag.
- I metadati vengono salvati nel database sotto l'ID di quel video.
- Un blocco
<script type="application/ld+json">contenente il markup VideoObject viene iniettato nel<head>della pagina prodotto.
Nelle visite successive, i passaggi 3–4 vengono saltati e vengono utilizzati direttamente i dati nella cache, fino alla scadenza dei 7 giorni.
Quando un prodotto ha più video, il modulo produce un unico blocco JSON-LD usando il tipo ItemList, con ogni video come itemListElement numerato. Questo permette a Google di capire che sono disponibili più video per il prodotto.
Video HTML5 ospitati autonomamente
I video HTML5 non richiedono alcuna API esterna. Il modulo costruisce il VideoObject dai dati già archiviati nel database: il titolo del video, l'URL e il percorso della miniatura. I percorsi relativi vengono convertiti automaticamente in URL assoluti.
Il modulo utilizza anche un meccanismo di cattura lato front-end. La prima volta che un visitatore riproduce un video HTML5, una leggera chiamata AJAX invia la durata effettiva del video (letta dall'elemento media del browser) al controller microdata del modulo, che la memorizza nella cache. Le generazioni successive dei microdata di quel video includeranno la durata reale al posto del segnaposto predefinito PT0S.
I microdata HTML5 vengono generati non appena PV_GENERATE_MICRODATA è abilitato — nessuna chiave API necessaria.
Cosa non è supportato
I provider video personalizzati e i provider che incorporano solo tramite iframe non generano microdata VideoObject. Sono supportati solo i tipi di video YouTube, Vimeo e HTML5.
Esempi d'Uso
Esempio: Aggiunta di microdata SEO per una demo prodotto YouTube
Vendi un elettrodomestico da cucina e hai un video demo YouTube (es. https://www.youtube.com/watch?v=dQw4w9WgXcQ) assegnato al prodotto. Abiliti Aggiungi microdata video, inserisci la tua chiave API YouTube e salvi. Alla visita successiva della pagina prodotto, il modulo recupera da YouTube il titolo, la descrizione, la miniatura e il numero di visualizzazioni del video e genera un blocco VideoObject. Nel giro di qualche giorno, Google Rich Results Test conferma che i dati strutturati sono validi e Google inizia a mostrare la miniatura del video nei risultati di ricerca per il prodotto.
Esempio: Utilizzo dei microdata Vimeo per un brand di moda
Un negozio di abbigliamento ospita i video dei prodotti privatamente su Vimeo. Crei un'app sviluppatore Vimeo, generi un token di accesso personale con scope public e inserisci tutte e tre le credenziali. Dopo il salvataggio, le pagine prodotto con video Vimeo generano il markup VideoObject includendo la miniatura Vimeo, la durata e il conteggio delle riproduzioni. Poiché la cache è per ID video, aggiungere lo stesso video Vimeo a 30 varianti di prodotto produce solo una chiamata API ogni ciclo di 7 giorni.
Esempio: Video HTML5 ospitato autonomamente con cattura della durata
Un negozio ospita video .mp4 di prodotti sul proprio server e non dispone di accesso API. Dopo aver abilitato la generazione dei microdata (nessuna chiave API necessaria per HTML5), ogni pagina prodotto genera immediatamente un VideoObject di base con titolo, miniatura e URL del contenuto. La prima volta che un visitatore reale riproduce il video nel browser, la durata effettiva viene catturata silenziosamente e memorizzata. Tutti i microdata futuri per quel video includono la durata ISO 8601 corretta (es. PT2M35S).
Note Importanti
- Le chiavi API sono necessarie per YouTube e Vimeo. L'interruttore principale da solo non è sufficiente per i video su piattaforme esterne. Senza una chiave valida, quei video non producono microdata.
- I provider personalizzati non sono supportati. Solo i tipi di video YouTube, Vimeo e HTML5 generano il markup VideoObject.
- La cache è per ID video, non per prodotto. Lo stesso video YouTube o Vimeo condiviso tra 50 prodotti genera solo una chiamata API ogni 7 giorni.
- L'indicizzazione di Google non è immediata. Dopo aver abilitato i microdata, usa Rich Results Test di Google per validare il markup, ma attendi diversi giorni o alcune settimane prima che Google inizi a mostrare i rich result nella ricerca.
- La durata del video HTML5 inizia come
PT0S. La durata reale viene catturata solo dopo la prima riproduzione reale nel browser. Se hai bisogno di durate accurate immediatamente, puoi aggiornare manualmente la tabellaproduct_videos_microdata. - Multi-shop: I microdata vengono memorizzati nella cache a livello globale (non per negozio). Lo stesso VideoObject nella cache viene servito a tutti i negozi in una configurazione multi-shop. Se i negozi mostrano video diversi per lo stesso prodotto, condividono la stessa voce di cache.
- I video devono essere accessibili pubblicamente. Se un video YouTube o Vimeo è impostato come privato o non in elenco, l'API potrebbe restituire dati incompleti o un errore, con conseguente assenza di microdata per quel video.
Risoluzione dei Problemi
| Problema | Soluzione |
|---|---|
| Nessun blocco JSON-LD appare nel sorgente della pagina | Verifica che Aggiungi microdata video sia abilitato e che il prodotto abbia almeno un video YouTube, Vimeo o HTML5 assegnato. I provider personalizzati non generano mai microdata. |
| I video YouTube non hanno microdata | Controlla che la chiave YouTube Data API v3 sia corretta e che l'API sia abilitata in Google Cloud Console. Abilita il log di debug API e controlla Back Office > Parametri avanzati > Log per l'errore specifico. |
| I video Vimeo non hanno microdata | Verifica che tutti e tre i campi Vimeo (Client ID, Client Secret, App Token) siano compilati. Un token mancante è la causa più comune. Abilita il log di debug API per vedere la risposta dell'API. |
| Google Rich Results Test mostra campi obbligatori mancanti | L'API ha restituito dati incompleti, di solito perché il video è privato o non in elenco. Rendi il video pubblico su YouTube o Vimeo e attendi la scadenza della cache di 7 giorni. |
| I microdata sono obsoleti dopo l'aggiornamento di un video | La cache di 7 giorni non è ancora scaduta. Per forzare un aggiornamento immediato, elimina la riga corrispondente dalla tabella product_videos_microdata nel database, poi ricarica la pagina prodotto. |
La durata del video HTML5 mostra sempre PT0S | Il controller di cattura front-end non ha ancora ricevuto una riproduzione reale nel browser per quel video. Visita tu stesso la pagina prodotto e riproduci il video per intero; la durata verrà memorizzata al completamento della chiamata AJAX. |
Domande Frequenti
Ho bisogno sia della chiave YouTube che delle credenziali Vimeo se il mio negozio usa entrambi i provider?
Sì. Ogni provider richiede le proprie credenziali. Puoi configurarli in modo indipendente — abilitare i metadati YouTube senza Vimeo (o viceversa) funziona bene per i video di quel provider. I video di un provider senza credenziali semplicemente non producono microdata.
L'abilitazione dei microdata rallenterà le pagine prodotto?
Solo alla primissima visita per ogni video, quando il modulo chiama l'API YouTube o Vimeo. Successivamente, i dati nella cache vengono letti direttamente dal database con una singola query SQL. Le chiamate API hanno un timeout di 2 secondi, quindi nel caso peggiore un nuovo video aggiunge un piccolo ritardo solo al suo primo caricamento.
Il mio prodotto ha tre video di provider diversi — come appaiono i dati strutturati?
Il modulo produce un unico blocco JSON-LD usando il tipo ItemList di Schema.org, con ogni video elencato come itemListElement numerato. Google può leggere questo come un elenco di video correlati per il prodotto. Nell'elenco compaiono solo i provider con credenziali valide (o i video HTML5).
Posso usare questa funzione senza alcun account Google o Vimeo?
Sì, se tutti i video dei tuoi prodotti sono file HTML5 ospitati autonomamente. I microdata HTML5 vengono generati dai dati archiviati localmente — non è necessaria alcuna API esterna. I video YouTube e Vimeo richiedono le rispettive credenziali API per generare i dati strutturati.
Come faccio a sapere se i miei microdata sono validi prima che Google li indicizzi?
Usa Rich Results Test di Google — incolla l'URL della pagina prodotto e ti mostrerà se i dati strutturati VideoObject sono validi, quali campi sono presenti e eventuali avvisi. Eseguilo dopo aver abilitato la funzione e prima di aspettarti risultati nella ricerca.
Cosa succede se la quota dell'API YouTube viene esaurita?
La YouTube Data API v3 ha una quota giornaliera (predefinita: 10.000 unità per progetto). Se la quota si esaurisce, l'API restituisce un errore. Con il log di debug API abilitato, vedrai questi errori in Back Office > Parametri avanzati > Log. Poiché i microdata vengono memorizzati nella cache per 7 giorni, il consumo della quota è molto inferiore a una chiamata API per ogni visualizzazione di pagina — è una chiamata per video ogni 7 giorni.