Erstellen Sie benutzerdefinierte Seiten für das Sammeln von Bewertungen

Jede Entität, die die Generierung von Bewertungen abonniert hat, erhält eine standardmäßige, nicht anpassbare Seite zum Sammeln von Bewertungen. Wenn Sie die volle Kontrolle über das Aussehen, die Bedienung und die zusätzlich erfassten Daten Ihres Sammelerlebnisses haben möchten, erstellen Sie eine benutzerdefinierte Seite zum Sammeln von Bewertungen mithilfe der Review Submission API. Dieser Artikel beschreibt die Funktionsweise der API und die Optionen, die Sie beim Erstellen Ihrer Seiten berücksichtigen sollten.

Wie Personen, die eine Bewertung schreiben möchten, auf Sammelseiten zugreifen

• Per Einladung: Ein Unternehmen sendet eine Einladung mit einem Link direkt an Kund*innen.
• Ohne Einladung: Ein Unternehmen veröffentlicht eine standardisierte, öffentlich zugängliche Seite zum Sammeln von Bewertungen, auf die Kund*innen selbstständig zugreifen können.

Gängige Strukturen für Sammelseiten

• Eine Seite pro Entität: die gängigste Struktur, mit einer eindeutigen Seite zum Sammeln von Bewertungen für jede Entität, für die Sie Bewertungen erhalten möchten. Ein Unternehmen mit 100 Produkten hätte beispielsweise für jedes Produkt eine eigene Seite.
• Eine Seite mit Entitätsauswahl: Eine einzelne Seite dient mehreren Entitäten, und die Person, die eine Bewertung abgeben möchte, wählt die entsprechende Entität aus. Die Seite enthält die ausgewählte Entität in ihrer API-Anfrage. Ein Unternehmen kann beispielsweise eine Seite für eine gesamte Produktkategorie verwenden, mit einer Auswahlmöglichkeit für das jeweilige Produkt.
• Eine Seite sammelt für mehrere Entitäten: Eine einzelne Seite sammelt in derselben Sitzung Bewertungen für mehr als eine Entität. Ein Unternehmen mit den separaten Entitäten „Autoversicherung – Versicherungsschutz“ und „Autoversicherung – Service“ könnte einer Kundin beispielsweise die Möglichkeit geben, über ein einziges Formular für beide einer Bewertung abzugeben.

Planen Sie Ihre Implementierung

Bevor Sie beginnen, sollten Sie Folgendes beachten:

• Welche Entitäten benötigen eine Seite zum Sammeln von Bewertungen? Sollten Sie, je nach Entitätstyp, eine oder mehrere Formularvorlagen verwenden?
• Was möchten Sie unterstützen: nur das Erstellen von Bewertungen oder auch die Aktualisierung und das Löschen?
• Planen Sie, über die Standardbewertungsfelder hinaus noch weitere Attribute zu sammeln?

Das Design liegt ganz bei Ihnen. Die einzige Voraussetzung ist, dass Ihre Seite Anfragen an die Endpunkte für die Bewertungseinreichung senden kann, um eine Bewertung abzugeben und optional eine Bewertung zu aktualisieren oder zu löschen.

Bewertungsanforderungen

Bewertungen, die über Ihre Seite gesammelt werden, müssen dem Yext-Bewertungsobjekt entsprechen: eine Sternebewertung mit 1 bis 5 Sternen, ein Bewertungstext und Informationen darüber, wer die Bewertung verfasst hat. Das Bewertungsobjekt unterstützt keine Unterbewertungen oder benutzerdefinierten Felder für zusätzliche Attribute zur Person, aber Sie können Bewertungslabels an eine eingereichte Bewertung anhängen. Siehe die API-Dokumentation für die vollständige Bewertungsobjekt-Referenz.

Spam verhindern

Das Erstellen einer benutzerdefinierten Seite zum Sammeln von Bewertungen bedeutet, dass ein API-Schlüssel auf Kundenseite offengelegt wird, wodurch jede Person, die ihn findet, Bewertungen direkt an Ihr Konto übermitteln kann. Yext bietet derzeit keine integrierte CAPTCHA-Unterstützung für diese Anfragen. Wenn Sie überprüfen möchten, ob die Einsendungen von echten Nutzer*innen stammen, fügen Sie eine CAPTCHA-Lösung wie Google reCAPTCHA oder hCaptcha mit einem Proxy-Server zwischen Ihrer Bewertungsseite und der Yext-API hinzu. Der Proxy validiert die CAPTCHA-Antwort und leitet dann verifizierte Anfragen an Yext weiter.

API-Endpunkte zum Übermitteln von Bewertungen

API-Zugriff einrichten

Erstellen Sie eine App in der Entwicklerkonsole und gewähren Sie ihr Zugriff auf die API zur Inhaltsübermittlung von Bewertungen, die das Erstellen, Aktualisieren und Löschen abdeckt. Da dieser API-Schlüssel auf Kundenseite verfügbar ist, beschränken Sie die App auf diese Berechtigung.

Eine Bewertung erstellen

Erfassen Sie die erforderlichen Felder auf Ihrer Seite, typischerweise über ein Formular, und übermitteln Sie diese an den Endpunkt „Übermitteln von Bewertungen: Erstellen“.

Bearbeitung der API-Antwort

Der Erstellen-Endpunkt erstellt die Bewertung nicht synchron, daher kann er nicht sofort eine Bewertungs-ID zurückgeben. Bei einer erfolgreichen Anfrage wird eine 202 Accepted-Antwort zusammen mit einem apiIdentifier zurückgegeben, entweder mit der invitationUid, die Sie in der Anfrage angegeben haben, oder einer neu generierten UUID, falls Sie keine angegeben haben. Dieser Wert wird 1:1 der resultierenden Bewertung zugeordnet und ist erforderlich, um diese später zu aktualisieren oder zu löschen. Eine Anfrage mit Validierungsproblemen, wie einer ungültigen E-Mail-Adresse, liefert einen 400-Fehler, den Ihre Seite den Nutzer*innen anzeigen kann.

Unterstützung beim Aktualisieren und Löschen von Bewertungen

Unterstützung, die es Endnutzer*innen ermöglicht, ihre eigenen Bewertungen zu aktualisieren oder zu löschen. Zwei Szenarien treten am häufigsten auf:

• Die Person möchte einen Fehler korrigieren oder ihre Meinung unmittelbar nach dem Absenden ändern.
• Das Unternehmen antwortet auf eine Bewertung, was dazu führt, dass die Person die ursprüngliche Bewertung aktualisieren oder löschen möchte, manchmal auch lange nach der Abgabe.

Diese beiden Szenarien erfordern unterschiedliche Ansätze.

Sofortige Aktualisierungen

Da eine über Übermitteln von Bewertungen: Erstellen eingereichte Bewertung nicht sofort über Bewertung: Abrufen oder Bewertung: Liste verfügbar ist, unterstützen Sie sofortige Aktualisierungen, indem Sie den Bewertungsinhalt und die zurückgegebene apiIdentifier auf Kundenseite speichern. Jede Anfrage zum Aktualisieren oder Löschen, die Nutzer*innen unmittelbar nach dem Absenden auslösen, kann diesen gespeicherten Wert wiederverwenden.

Nicht sofortige Aktualisierungen

Um Bearbeitungen nach dem Verlassen der Seite zu unterstützen, rufen Sie die Bewertung später über die Streams-API ab, anstatt sich auf gespeicherte Daten auf Kundenseite zu verlassen. Filtern Sie Ihre Streams-API-Anfrage anhand des Felds apiIdentifier, um die passende Bewertung abzurufen, und stellen Sie anschließend eine Oberfläche zum Bearbeiten mit diesen Daten bereit. Bitte beachten Sie, dass die betreffende Bewertung den Status LIVE haben muss, um von der Streams-API zurückgegeben zu werden. Wenn die Bewertung noch IN QUARANTÄNE ist, wird sie von der Streams-API nicht zurückgegeben.

Zwei Beispiele veranschaulichen, wann dies vorkommt:

• Die Person, die eine Bewertung geschrieben hat, wird über eine Antwort benachrichtigt: Achten Sie auf REVIEW_COMMENT_UPDATED-Webhook-Events. Wenn ein Unternehmen auf eine Bewertung aus erster Hand antwortet, senden Sie der Person, die diese verfasst hat, per E-Mail einen Link zur Bewertungsseite, mit dem apiIdentifier als Anfrageparameter. Wenn sie darauf klickt, ruft die Seite die Bewertung anhand des apiIdentifier ab und stellt die Oberfläche zum Bearbeiten bereit.
• Rückkehr über den ursprünglichen Einladungslink: Wenn ein eine Person nach dem Abgeben einer Bewertung erneut auf seine ursprüngliche E-Mail-Einladung klickt, erhält die Seite dieselbe invitationUid als Anfrageparameter. Da apiIdentifier immer dann der invitationUid entspricht, wenn eine Einladung zur Erstellung der Bewertung verwendet wurde, rufen Sie die Bewertung mit diesem Wert ab. Wenn eine passende Bewertung existiert, wird die Oberfläche zum Bearbeiten angezeigt; andernfalls wird die Standardoberfläche zum Erstellen angezeigt.

Der apiIdentifier einer Bewertung ist eine generierte UUID und keine inkrementelle Review-ID, was für diesen Zweck sicherer ist: Eine inkrementelle ID würde es jedem erlauben, einen bekannten Wert zu erhöhen oder zu verringern, um auf andere Bewertungen zuzugreifen.

Bewertungen über die Streams-API abrufen

Die Streams-API ist eine latenzarme, anpassbare API, die sich eignet, um auf Kundenseite Bewertungen abzurufen. Yext bietet eine vorkonfigurierte App für diesen Anwendungsfall, die einen Streams-Endpunkt mit der ID reviewsStreamsEndpoints_reviews erstellt, sodass Sie die Indizierung nicht manuell konfigurieren müssen. Eine Musteranfrage sieht so aus: