1. Skeepers
  2. Visibilità Google
  3. Visibilità su Google

Guida all’integrazione dei dati strutturati JSON-LD per i Rich Snippet

Aggiornato

Grazie all’integrazione del nostro widget prodotto, Recensioni Verificate ti permette di integrare nativamente i dati strutturati necessari per la visualizzazione dei Rich Snippets (frammenti arricchiti) nei risultati di ricerca organica.

Tuttavia, hai forse notato temporaneamente una diminuzione del numero di frammenti di recensioni validi nella tua Search Console, o un calo, o addirittura una scomparsa della visualizzazione delle stelline sotto i link delle tue pagine prodotto nei risultati di ricerca (SERP)?

Il nostro widget si basa su uno script JavaScript. Google tratta questa tecnologia in modo specifico e richiede che venga eseguita da un motore di rendering per poter leggere il contenuto.

Può succedere che Google non esegua sistematicamente il JavaScript del nostro widget prodotto e quindi non rilevi i dati strutturati in esso contenuti, il che può impedire la visualizzazione dei Rich Snippets (stelline, numero di recensioni, estratti di recensioni).

Questo comportamento è casuale e non è stato oggetto di alcuna comunicazione ufficiale da parte di Google.

Pertanto, per garantire una visibilità permanente dei dati strutturati, ti consigliamo di implementare manualmente i dati strutturati in formato JSON-LD direttamente nel codice HTML delle tue pagine prodotto.

Questa integrazione si basa sulla nostra API Recensioni Prodotto e questa guida ti accompagna passo dopo passo per arricchire le tue pagine prodotto con dati strutturati in formato JSON-LD conformi ai requisiti di Google.

Come indicato nella documentazione ufficiale di Google, avere dati strutturati corretti e ben formattati all’interno della propria pagina non garantisce al 100% la visualizzazione di risultati arricchiti. Questa visualizzazione è algoritmica e dipende da regole note solo al motore di ricerca.

Prerequisiti

  • Un OAuth2 client_id / client_secret valido (disponibile nel tuo spazio Recensioni Verificate)
  • Un ID di variazione del prodotto (product_variation_id) per ogni prodotto del tuo sito. (Il riferimento del prodotto per il quale ricevi recensioni)

Documentazione completa dell’API

Disattivare i Rich Snippets dal widget prodotto

  1. Dal menu a sinistra, clicca su Diffusione delle recensioni, poi su Integra i miei widget.
  2. Clicca sull’ icona a forma di matita accanto al widget prodotto di tua scelta.
  3. Nelle impostazioni avanzate, disattiva l’opzione di attivazione Rich Snippets.

Panoramica degli API Endpoints

L’endpoint Ratings dell’API ti consente di recuperare la valutazione media e il numero di recensioni di un prodotto.

URL

https://api.skeepers.io/verified-reviews/v1/published/products

Esempio di chiamata API

https://api.skeepers.io/verified-reviews/v1/published/products?product_variation_id=6938012334889
--header 'Authorization: ••••••'

Esempio concreto del risultato ottenuto


[
  {
    "product_variation_id": "6938012334889",
    "ratings": {
      "average": 4.5,
      "count_total": 127,
      ...
    },
    ...
  }
]

Fai clic qui per vedere la documentazione API

API Endpoints delle recensioni (opzionale)

Questo API Endpoint ti consente di recuperare tutte le recensioni di un prodotto.

URL

https://api.skeepers.io/verified-reviews/v1/published/products/reviews?product_variation_id=6938012334889
--header 'Authorization: ••••••'

Esempio concreto del risultato ottenuto

Un elenco di recensioni degli utenti che include autore, contenuto, valutazione e data di pubblicazione.

[
  {
    "review_id": "67d7b591-40a2-7ab4-1925-0b2db7753c90",
    "author_firstname": "John",
    "author_lastname": "Doe",
    "review_date": "2024-06-24T15:12:31Z",
    "review_content": "Great product!",
    "review_rate": 5,
    ...
  },
  ...
]

Fai clic qui per vedere la documentazione API

Guida di integrazione passo dopo passo

Passo 1: Recuperare i Ratings data

È necessario utilizzare il Products endpoint per ottenere la valutazione media e il numero di recensioni di un prodotto.

Esempio di risposta API:

{
    "product_variation_id": "6938012334889",
    "ratings": {
      "average": 4.5,
      "count_total": 127,
      ...
    },
    ...
  }

Passo 2: Creare il codice JSON

È il momento di creare i dati strutturati JSON-LD.

Per farlo, integra questo snippet JSON-LD nel <head> o subito prima del tag di chiusura </body> della tua pagina prodotto:

  1. Genera il blocco seguente:

    <script type="application/ld+json">
{  
  "@context": "https://schema.org",
  "@id": "https://www.example.com/product/6938012334889",
  "@type": "Product",
  "aggregateRating": { 
    "@type": "AggregateRating", 
    "ratingValue": "4.5", 
    "ratingCount": 127, 
    "bestRating": 5, 
    "worstRating": 1
  }
}
</script>Sostituisci:
  2. Sostituisci @id con l’URL canonico del tuo prodotto.
  3. Sostituisci ratingValue e ratingCount con i valori provenienti dall’API.
  4. Lascia tutto il resto invariato!

Passo 3: Aggiungere recensioni individuali (opzionale)

Per andare oltre e mostrare recensioni reali (Google può decidere se mostrarle o meno), puoi anche integrare i dati delle recensioni:

  1. Recupera le recensioni utilizzando il Product Reviews Endpoint
  2. Converti ogni recensione nel formato seguente:

"review": [
  { 
    "@type": "Review",
    "author": { 
      "@type": "Person", 
      "name": "R Sophie", 
      "givenName": "Sophie", 
      "familyName": "R"
    }, 
    "datePublished": "2025-03-14T14:12:00.000Z",
    "reviewBody": "Adoro queste cuffie! Bloccano il rumore di fondo e sono molto leggere.", 
    "reviewRating": { 
      "@type": "Rating", 
      "bestRating": 5, 
      "worstRating": 1, 
      "ratingValue": 5 
    }
  }
]

  • Puoi includere più oggetti all’interno di "review": [ ... ].

  • Google consiglia di includere: reviewRating, datePublished e author.

Esempio completo che include le recensioni:

<script type="application/ld+json">
{  
  "@context": "https://schema.org",
  "@id": "https://www.example.com/product/57713",
  "@type": "Product",
  "aggregateRating": { 
    "@type": "AggregateRating", 
    "ratingValue": "4.5", 
    "ratingCount": 12, 
    "bestRating": 5, 
    "worstRating": 1
  },
  "review": [
    { 
      "@type": "Review",
      "author": { 
        "@type": "Person", 
        "name": "R Sophie", 
        "givenName": "Sophie", 
        "familyName": "R"
      }, 
      "datePublished": "2025-03-14T14:12:00.000Z",
      "reviewBody": "Adoro queste cuffie! Bloccano il rumore di fondo e sono molto leggere.", 
      "reviewRating": { 
        "@type": "Rating",
        "bestRating": 5,
        "worstRating": 1,
        "ratingValue": 5
      }
    }
  ] 
}
</script>

Dove caricare i dati strutturati?

Fortemente consigliato 

Consigliamo vivamente di generare e integrare i dati strutturati lato server, direttamente nell’HTML, prima che la pagina venga inviata al browser.

In questo modo, quando Googlebot o altri crawler dei motori di ricerca accedono alla tua pagina, i dati strutturati sono già presenti nell’HTML grezzo, rendendoli facili e affidabili da indicizzare.

Esempio: Includi il blocco <script type="application/ld+json"> nel template HTML renderizzato dal tuo backend, ad esempio in PHP, Node.js, Python (Django, Flask), Ruby, ecc.

Da evitare 

L’iniezione JavaScript sul tuo sito, poiché Google potrebbe non vedere o indicizzare correttamente questi dati.

Sebbene sia tecnicamente possibile iniettare dati strutturati tramite JavaScript lato frontend (ad esempio con React, Vue o altri framework), questo approccio è meno affidabile perché:

  • Google potrebbe non eseguire completamente il tuo JavaScript, o addirittura non eseguirlo, in base alla velocità di caricamento della pagina e al crawl budget.
  • I dati strutturati caricati in modo asincrono possono essere ignorati o indicizzati in ritardo.
  • Potresti ottenere risultati incoerenti in base ai prodotti o agli aggiornamenti.

Best practice

  • I dati strutturati devono corrispondere al contenuto visibile sulla pagina.
  • Le date devono seguire il formato ISO 8601: "2025-03-14T14:12:00.000Z".
  • Utilizza solo recensioni reali dei clienti (inviate dagli utenti).
  • Aggiorna regolarmente i dati strutturati con nuove recensioni e valutazioni.
  • È consentito un solo tag "Product" per pagina affinché i Rich Snippets funzionino correttamente.

Testare la validazione dei dati

Utilizza lo strumento Google Rich Results Test per verificare che i dati strutturati siano corretti e correttamente rilevati

Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 0 su 0

Articoli correlati

Menu icon In questa pagina