La generazione di recensioni di Yext consente alle aziende di inviare inviti via email e SMS ai propri clienti per richiedere una recensione utilizzando l'URL di bilanciamento delle recensioni. Questo URL indirizza gli utenti a siti di recensioni di terze parti e/o alla tua pagina di raccolte delle recensioni di prima mano, a seconda della distribuzione impostata per l'algoritmo di bilanciamento delle recensioni. Puoi scoprire di più sull'algoritmo di bilanciamento delle recensioni nella guida Inizia con le recensioni. 

Puoi utilizzare l'API degli inviti a lasciare una recensione per integrare un sistema esterno e gestire gli inviti in modo programmato.

Modelli di integrazione

La maggior parte delle integrazioni degli inviti a lasciare una recensione utilizza uno dei due modelli.

Push: il tuo sistema esterno notifica la tua applicazione non appena si verifica un evento scatenante, dopodiché l'applicazione crea l'invito. Gli eventi scatenanti più comuni includono:

• Un cliente riceve un prodotto e il sistema di evasione degli ordini segnala che la consegna è stata completata.
• Un cliente completa un acquisto in una sede fisica, e il sistema del punto vendita invia un segnale per indicare che la transazione è completata.
• Un paziente completa una visita e il sistema di programmazione segnala che lo stato dell'appuntamento è stato aggiornato.

Pull: la tua applicazione recupera periodicamente i dati che generano gli inviti invece di ricevere una notifica in tempo reale. Le integrazioni pull sono comuni quando il sistema esterno non offre assistenza per i webhook del relativo fattore scatenante, o quando i dati di invito vengono esportati in una sede FTP secondo una programmazione.

Endpoint dell'API degli inviti a lasciare una recensione

Campi di invito

Un invito include i seguenti campi principali. Nel corpo della richiesta sono richiesti campi aggiuntivi: consulta la documentazione API per un quadro completo.

*Campo obbligatorio.

Prima di creare la tua integrazione, verifica che la tua applicazione possa fornire tutti i campi necessari.

Configura l'accesso API

Crea un'app

Crea un'app nella Console per gli sviluppatori e concedi l'accesso all'API degli inviti a lasciare una recensione. L'accesso in lettura è sufficiente per gli endpoint Get/List. Tuttavia, per creare, aggiornare o eliminare inviti, è richiesto l'accesso in scrittura. Verrà generata una chiave API per consentire alla tua app di accedere agli endpoint Review Invitations. Non è consigliabile esporre questa chiave API sulle pagine lato client, quindi assicurati di non utilizzare questa app per richieste lato client.

Crea un invito

Una richiesta all'endpoint Review Invitations: Create invia un invito al contatto che specifichi. Il sistema di generazione di recensioni invierà un SMS se fornisci un numero di telefono o un'email se fornisci un indirizzo email.

La risposta include due campi che ti serviranno per richieste future:

• invitationUid: un identificatore unico per l'invito.
• feedbackUrl: l'URL completo incluso nell'invito, con invitationUid aggiunto come parametro di query. Quando il destinatario invia una recensione da questo URL, includi l'invitationUid nella richiesta di creazione della recensione in modo che il sistema possa attribuire la recensione all'invito.

Includi ulteriori dettagli nell'invito

L'API supporta due modi di trasmettere un contesto aggiuntivo con un invito, che potrai poi utilizzare nella recensione risultante.

Etichette di recensione: inserisci i valori nel campo reviewLabelNames. Quando viene creata una recensione con il corrispondente invitationUid, questi valori vengono applicati alla recensione come etichette di recensione. Ad esempio, inserendo "Punto vendita" in reviewLabelNames si applica l'etichetta "Punto vendita" alla recensione risultante.

Parametri URL aggiuntivi: inserisci un oggetto JSON di coppie chiave-valore nel campo additionalURLParameters. Queste vengono aggiunte come parametri di query all'URL del feedback, così la tua Pagina della collezione può leggerli e usarli come necessario, incluso l'invio dei dati a un sistema di attribuzione esterno anziché applicarli come etichetta.

Invia inviti da un sistema esterno

Se la tua azienda utilizza il proprio nome utente per l'invio di email o SMS, puoi creare un registro degli inviti in Yext senza che Yext provveda all'invio, inserendo sendInvitationFromYext = FALSE nel corpo della richiesta. Questo è utile quando:

• vuoi che Yext rimanga la fonte affidabile per gli inviti inviati, anche se il tuo sistema li consegna;
• vuoi accettare recensioni solo da clienti che hanno ricevuto un invito, il che richiede la configurazione aggiuntiva descritta di seguito.

Richiedi un UID di invito per l'invio.

Per impostazione predefinita, una Pagina della collezione pubblica consente a chiunque abbia l'URL di lasciare una recensione, cosa che molte aziende desiderano. Per limitare gli invii solo ai clienti invitati, attiva Inviti obbligatori per le recensioni di prima mano nelle impostazioni dell'account. Una volta abilitato, ogni richiesta all'endpoint Review Submission: Create deve includere un invitationUid valido, altrimenti la recensione viene rifiutata.

Se stai eseguendo inviti da un sistema esterno e hai bisogno di questa impostazione, invia tu stesso l'URL di feedback restituito feedbackURL ai tuoi clienti dopo aver creato il registro degli inviti con sendInvitationFromYext = FALSE.

Reindirizza gli inviti a una Pagina della collezione personalizzata

Per impostazione predefinita, l'URL di bilanciamento delle recensioni indirizza i destinatari alla Pagina della collezione standard di Yext. Per reindirizzare gli inviti di prima parte a una Pagina della collezione personalizzata:

1. Vai a Recensioni > Generazione > Impostazioni.
2. Attiva la Sostituzione della pagina di raccolta delle recensioni di prima mano.
3. Seleziona un campo personalizzato per inserire i tuoi URL personalizzati oppure creane uno se non ne hai già uno.
4. Inserisci i dati in quel campo personalizzato per ogni entità che desideri reindirizzare.

Dopo aver completato questi passaggi, il campo Pagina delle recensioni di prima mano viene automaticamente riempito con il valore del campo personalizzato. L'URL di bilanciamento delle recensioni in sé non cambia; applica comunque le impostazioni dell'algoritmo di bilanciamento per decidere a quale publisher indirizzare e utilizza il tuo URL personalizzato quando indirizza a una recensione di prima mano.

Formatta gli inviti con modelli

I modelli di invito controllano come appare un invito al destinatario. Yext offre assistenza sia per i modelli di email che di SMS, che puoi personalizzare dalla piattaforma. Consulta i Modelli per la generazione di recensioni per i passaggi di configurazione. Se non specifichi un ID del modello quando crei un invito, Yext utilizza il modello predefinito del tuo account.

Conformati alla normativa CAN-SPAM

La normativa CAN-SPAM richiede che le email commerciali includano l'indirizzo postale fisico del mittente. Per inviare inviti attraverso il sistema email di Yext's, aggiungi un nome del brand e un indirizzo nelle impostazioni dell'account di generazione di recensioni. Yext include automaticamente queste informazioni nel piè di pagina delle email di invito.

Aggiorna o elimina un invito

Utilizza l'endpoint Update per annullare un invito che non è ancora stato inviato o per apportare altre modifiche prima della consegna. Usa l'endpoint Delete per rimuovere permanentemente un registro di invito. L'eliminazione di un invito non influisce sullo stato di consegna di un invito già inviato.

Testa la tua integrazione

Testa la tua integrazione con un account non di produzione o su un account Sandbox prima di implementarla. Per i test automatizzati, come ad esempio un controllo notturno per verificare che la pipeline di dati invii correttamente gli inviti, crea un invito di prova e poi eliminalo utilizzando l'endpoint Delete.