Ogni entità iscritta alla generazione di recensioni riceve una pagina di raccolte recensioni standard, non personalizzabile. Se desideri avere il pieno controllo sull'aspetto, l'esperienza utente e i dati aggiuntivi raccolti durante la tua esperienza di raccolta, crea una pagina di raccolta personalizzata utilizzando l'API per l'invio delle recensioni. Questo articolo illustra il funzionamento dell'API e le opzioni da considerare durante la creazione delle pagine.
Come i recensori accedono alle pagine delle raccolte
- Tramite invito: un'azienda invia un invito con un link direttamente a un cliente.
- Senza un invito: un'azienda pubblica una pagina di raccolte standard e pubblicamente accessibile che i clienti possono consultare autonomamente.
Strutture comuni delle pagine di raccolta
- Una pagina per entità: la struttura più comune, con un'unica pagina di raccolte per ogni entità per cui si desiderano recensioni. Un'azienda con 100 prodotti, ad esempio, avrebbe una pagina per ogni prodotto.
- Una pagina con un selettore di entità: una singola pagina gestisce più entità e il recensore seleziona quale entità recensire. La pagina include l'entità selezionata nella sua richiesta API. Un'azienda potrebbe utilizzare una pagina per un'intera categoria di prodotto, con un selettore per il prodotto specifico.
- Una pagina che raccoglie più entità: una singola pagina raccoglie recensioni per più di un'entità nella stessa sessione. Ad esempio, un'azienda con entità separate "Assicurazione Auto - Copertura" e "Assicurazione Auto - Servizio" potrebbe permettere a un cliente di lasciare una recensione per entrambe da un unico modulo.
Pianifica la tua implementazione
Prima di iniziare a sviluppare, considera:
- quali entità necessitano di una pagina di raccolta e se sia necessario un unico modello di modulo o più modelli a seconda del tipo di entità;
- per quali esperienze vuoi fornire assistenza: se solo la creazione di recensioni, oppure anche l'aggiornamento e l'eliminazione;
- se intendi raccogliere attributi aggiuntivi oltre ai campi di recensione standard.
Il design è interamente a tua discrezione. L'unico requisito è che la tua pagina possa effettuare richieste agli endpoint di invio delle recensioni per inviare una recensione e, facoltativamente, per aggiornarla o eliminarla.
Requisiti per le recensioni
Reviews raccolte tramite la tua pagina devono conformarsi all'oggetto della recensione di Yext: una valutazione in stelle da 1 a 5, testo della recensione e informazioni sull'autore. L'oggetto della recensione non supporta valutazioni secondarie né campi personalizzati per attributi aggiuntivi relativi al recensore, ma è possibile associare etichette di recensione a una recensione inviata. Consulta la documentazione API per il riferimento completo all'oggetto di recensione.
Previeni lo spam
Creare una pagina di raccolte personalizzata significa esporre una chiave API lato client, che permette a chiunque la trovi di inviare recensioni direttamente al tuo account. Attualmente Yext non offre assistenza CAPTCHA integrata per queste richieste. Se desideri verificare che gli invii provengano da utenti reali, aggiungi una soluzione CAPTCHA, come Google reCAPTCHA o hCaptcha, con un server proxy tra la tua pagina di raccolte e l'API di Yext. Il proxy convalida la risposta CAPTCHA, quindi inoltra le richieste verificate a Yext.
Endpoint API per l'invio delle recensioni
| Endpoint | Descrizione | URL |
|---|---|---|
| Review Submission: Create | Crea una nuova recensione di prima mano | POST https://cdn.yextapis.com/v2/accounts/{accountId}/reviewSubmission |
| Review Submission: Update | Aggiorna una recensione di prima mano esistente | PUT https://cdn.yextapis.com/v2/accounts/{accountId}/reviewSubmission/{apiIdentifier} |
| Review Submission: Delete | Imposta lo stato di una recensione di prima mano esistente su RIMOSSA
|
DELETE https://cdn.yextapis.com/v2/accounts/{accountId}/reviewsSubmission/{apiIdentifier} |
Configura l'accesso API
Crea un'app nella Console per gli sviluppatori e concedile l'accesso all'API di distribuzione dei contenuti per l'invio delle recensioni, che include le funzioni di creazione, aggiornamento ed eliminazione. Poiché questa chiave API è esposta sul lato client, assegna all'app solo questa autorizzazione.
Crea una recensione
Raccogli i campi obbligatori sulla tua pagina, in genere tramite un modulo, e inviali all'endpoint "Review Submission: Create" quando l'utente effettua l'invio.
Gestisci la risposta dell'API
L'endpoint Create non crea la recensione in modo sincrono, quindi non può restituire immediatamente un ID recensione. Una richiesta andata a buon fine restituisce una risposta "202 Accettata" insieme a un apiIdentifier che può essere l'invitationUid specificato nella richiesta oppure, se non ne hai specificato uno, un UUID appena generato. Questo valore corrisponde esattamente alla recensione risultante ed è necessario per aggiornarla o eliminarla in seguito. Una richiesta con problemi di convalida, come un indirizzo email non valido, restituisce un errore 400 che la tua pagina può mostrare all'utente.
Assistenza per l'aggiornamento e la cancellazione delle recensioni
Consenti agli utenti finali di aggiornare o eliminare le proprie recensioni. Due scenari si presentano più spesso:
- L'utente vuole correggere un errore o cambiare idea immediatamente dopo l'invio.
- L'azienda risponde a una recensione e la soluzione proposta invita l'utente finale ad aggiornare o eliminare la recensione originale, a volte anche molto tempo dopo l'invio.
Questi due scenari richiedono approcci diversi.
Aggiornamenti immediati
Poiché una recensione inviata tramite Review Submission: Create non è disponibile immediatamente tramite Review: Get o Review: List, è possibile ottenere aggiornamenti immediati memorizzando il contenuto della recensione e l'apiIdentifier restituito sul lato client. Qualsiasi richiesta di aggiornamento o eliminazione che l'utente attiva subito dopo l'invio può riutilizzare quel valore memorizzato.
Aggiornamenti non immediati
Per fornire assistenza alle modifiche dopo che l'utente ha lasciato la pagina, recupera la recensione in un secondo momento utilizzando l'API Streams anziché fare affidamento sui dati memorizzati lato client. Filtra la richiesta API di Streams sul campo apiIdentifier per recuperare la recensione corrispondente, quindi mostra un'esperienza di modifica con quei dati. La recensione in questione dovrà mostrare lo stato LIVE per essere restituita da Streams API. Se la recensione è ancora QUARANTINED, non verrà restituita da Streams API.
Due esempi illustrano quando si presenta questa situazione:
-
Avvisare un recensore di una risposta: monitora gli eventi webhook
REVIEW_COMMENT_UPDATED. Quando un'azienda risponde a una recensione di prima mano, invia un'email al recensore con un link alla pagina di raccolte con l'apiIdentifiercome parametro di query. Quando il recensore apre il link, la pagina recupera la recensione tramiteapiIdentifiere visualizza l'esperienza di modifica. -
Ritorno tramite il link originale dell'invito: se un utente fa clic di nuovo sulla propria email di invito originale dopo aver già lasciato una recensione, la pagina riceve lo stesso
invitationUidcome parametro di query. PoichéapiIdentifierè uguale ainvitationUid, ogni volta che è stato utilizzato un invito per creare la recensione, recupera la recensione utilizzando tale valore. Se esiste una recensione corrispondente, visualizza la procedura di modifica; in caso contrario, visualizza la procedura standard di creazione.
L'apiIdentifier di una recensione è un UUID generato, non un ID di recensione incrementale, il che è più sicuro a questo scopo: un ID incrementale permetterebbe a chiunque di incrementare o decrementare un valore noto per accedere ad altre recensioni.
Recupera le recensioni tramite l'API Streams
L'API Streams è un'API a bassa latenza e personalizzabile, adatta a recuperare recensioni dal lato client. Yext fornisce un'app preconfigurata per questo caso d'uso che crea un Endpoint Streams con l'ID reviewsStreamsEndpoints_reviews, quindi non è necessario configurare manualmente l'indicizzazione. Una richiesta di esempio si presenta così: