Documentazione per sviluppatori — Recensioni

Le Recensioni sono modelli strutturati per la raccolta, la moderazione e la visualizzazione di feedback pubblici in FaceFlow.

Consentono ai team tecnici di gestire contenuti sensibili per la reputazione come output governato del sito web piuttosto che come testimonianze non gestite e libere.

Responsabilità principali

Un modello di Recensione è responsabile di:

• modelli di recensione configurabili
• campi di valutazione strutturati
• acquisizione degli invii pubblici
• politica di moderazione e verifica
• output di visualizzazione incorporabile
• controllo della pubblicazione

Questo rende le Recensioni adatte alle sezioni del sito web basate sulla fiducia che necessitano sia di visibilità pubblica sia di controllo operativo.

Modello principale della Recensione

Un modello di Recensione solitamente combina:

• campi di identità principali della recensione
• campi di valutazione
• dimensioni di valutazione personalizzate opzionali
• impostazioni di moderazione
• comportamento di verifica
• impostazioni di presentazione e output

Nella pratica, il livello Recensioni definisce sia quali feedback possono essere raccolti sia quali feedback approvati possono essere pubblicati nuovamente sul sito web.

Conceptually:

{
  "name": "customer-success-reviews",
  "fields": [
    { "name": "author_name", "type": "text", "required": true },
    { "name": "rating", "type": "rating", "required": true },
    { "name": "review_title", "type": "text", "required": true },
    { "name": "review_content", "type": "textarea", "required": true }
  ],
  "settings": {
    "moderation": "required",
    "verification": "optional"
  }
}

Flusso di invio e pubblicazione

A grandi linee:

1. un modello di Recensione viene definito centralmente
2. viene incorporato in una Pagina tramite un Componente
3. i visitatori inviano feedback
4. vengono applicate regole di moderazione e di verifica
5. le voci approvate vengono visualizzate nuovamente nel sito

Conceptually:

review widget render
  -> visitor submission
  -> pending review state
  -> moderation / verification
  -> approved review published

Per questo motivo le Recensioni dovrebbero essere trattate come contenuto pubblico governato, non solo come un altro modulo di input.

Struttura delle valutazioni

I modelli di Recensione possono supportare:

• valutazione complessiva
• titolo della recensione
• contenuto della recensione
• dimensioni di valutazione personalizzate per feedback più strutturati

Example:

overall_rating
service_rating
communication_rating
value_rating

Usare dimensioni aggiuntive solo quando migliorano la fiducia e l'interpretazione.

Esempio di modello di Recensione

Un revisore tecnico dovrebbe essere in grado di ispezionare chiaramente la struttura del modello:

{
  "name": "service-review",
  "fields": [
    { "name": "author_name", "type": "text", "required": true },
    { "name": "rating", "type": "rating", "required": true },
    { "name": "review_title", "type": "text", "required": true },
    { "name": "review_content", "type": "textarea", "required": true }
  ],
  "settings": {
    "moderation": "required",
    "verification": "optional"
  }
}

Questo aiuta i team a verificare cosa viene raccolto, cosa è obbligatorio e quanto carico di moderazione il modello è probabile che generi.

Moderazione e Verifica

La moderazione e la verifica sono centrali nel design delle Recensioni.

I team tecnici dovrebbero decidere:

• se le voci richiedono approvazione
• se è necessaria una verifica aggiuntiva
• chi è responsabile delle decisioni di pubblicazione
• come dovrebbe essere gestito il contenuto sensibile alla reputazione

Maggiore è il rischio per la reputazione, più forti dovrebbero generalmente essere i controlli.

Incorporamento delle Recensioni

Le Recensioni vengono tipicamente incorporate nelle sezioni della pagina tramite Componenti.

Un comune marker di incorporamento è:

<div data-review-embed="service-review"></div>

Esempio di sezione:

<section class="customer-proof">
  <header>
    <h2>What customers say</h2>
  </header>
  <div data-review-embed="customer-success-reviews"></div>
</section>

Questo mantiene la raccolta e la visualizzazione delle recensioni riutilizzabili, consentendo alla Pagina di posizionare i contenuti di fiducia dove hanno il massimo impatto.

Incorporamenti fissi vs incorporamenti basati su campo

Esistono due modelli comuni di incorporamento.

Usare un id del modello di Recensione gestito e fisso quando il template dovrebbe sempre renderizzare uno specifico modello di Recensione:

<div data-review-embed="customer-success-reviews"></div>

Usare un incorporamento basato su campo quando un Componente espone un campo reviewSelect e gli autori dovrebbero scegliere il modello di Recensione gestito al momento della creazione:

<div data-review-embed="{serviceReview}"></div>

Regola decisionale:

• incorporamento fisso -> un flusso di fiducia stabile di proprietà del template
• incorporamento basato su campo -> Componente riutilizzabile con flusso di recensione selezionabile dall'autore

Modello di integrazione

Il percorso di runtime più pulito è:

Review model
-> Component embed via reviewSelect or explicit data-review-embed marker
-> Page composition
-> public submission, moderation, and approved display output

Questo mantiene la logica del flusso di lavoro sensibile alla reputazione centralizzata invece di disperderla in markup di pagina monouso.

Linee guida operative

Un buon design delle Recensioni di solito favorisce:

• un modello di Recensione per contesto aziendale
• responsabilità chiara della moderazione
• dimensioni di valutazione strutturate solo dove aggiungono valore reale
• un'esperienza di invio sufficientemente breve per preservare la qualità
• un modello di pubblicazione che supporti la fiducia anziché il rumore

Se un modello di Recensione diventa troppo ampio, la qualità e la moderazione di solito diventano più difficili da gestire.

Indicazioni per il contratto di valutazione

Mantenere il modello di valutazione proporzionato al flusso pubblico.

Modelli tipici:

• sezione di fiducia semplice -> valutazione complessiva + titolo + corpo della recensione
• flusso di lavoro qualità del servizio -> valutazione complessiva più un piccolo numero di dimensioni come servizio, comunicazione o valore

Se un flusso pubblico breve richiede troppe valutazioni, la qualità degli invii e il tasso di completamento generalmente diminuiscono.

Linee guida tecniche

• separare i modelli di Recensione per contesto aziendale
• allineare la politica di moderazione e verifica alla sensibilità sulla reputazione
• mantenere la raccolta delle recensioni pubbliche abbastanza breve da preservare la qualità degli invii
• considerare il contenuto delle recensioni pubblicate come output governato
• considerare raccolta, moderazione e visualizzazione delle recensioni come un unico flusso di lavoro

Pratiche da evitare

Evitare:

• un unico modello di Recensione enorme usato per contesti aziendali non correlati
• troppe dimensioni di valutazione per un flusso pubblico breve
• pubblicare senza una chiara responsabilità di moderazione
• trattare le Recensioni come testimonianze non gestite incollate nei Componenti
• progettare il flusso di input senza rivedere il modello di visualizzazione e approvazione

Esempio di pattern di costruzione

Review model:
  customer-success-reviews

Component:
  review-strip

Embed:
  <div data-review-embed="customer-success-reviews"></div>

Questo schema mantiene i contenuti di fiducia riutilizzabili e governati.

Correlati

• Panoramica del prodotto Reviews
• Guida alle Recensioni
• Componenti
• Pagine
• Utenti