Každý subjekt přihlášený k odběru generování recenzí získá standardní, nepřizpůsobitelnou stránku pro sběr recenzí. Pokud chcete mít plnou kontrolu nad vzhledem, dojmem a dalšími údaji shromažďovanými v rámci procesu sběru recenzí, vytvořte si vlastní stránku pro sběr recenzí pomocí rozhraní API pro odesílání recenzí. Tento článek popisuje, jak API funguje a jaké možnosti byste měli zvážit při vytváření stránek.
Přístup recenzentů ke stránkám pro sběr
- Prostřednictvím pozvánky: firma zašle zákazníkovi přímo pozvánku s odkazem.
- Bez pozvánky: firma zveřejní standardní, veřejně přístupnou stránku pro sběr, ke které mají zákazníci přístup sami.
Běžné struktury stránek pro sběr
- Jedna stránka na subjekt: nejčastější struktura s unikátní stránkou pro sběr u každého subjektu, pro který chcete recenze. Například firma se 100 produkty by měla jednu stránku na produkt.
- Jedna stránka s výběrem subjektů: jedna stránka slouží více subjektům a recenzent vybere, který subjekt chce recenzovat. Stránka zahrnuje vybraný subjekt ve svém požadavku API. Firma může použít jednu stránku pro celou kategorii produktů s výběrem konkrétního produktu.
- Jedna stránka shromažďující více subjektů: jedna stránka shromažďuje recenze pro více než jeden subjekt v rámci stejné relace. Například firma se samostatnými subjekty „Pojištění automobilů – krytí“ a „Pojištění automobilů – servis“ může umožnit jednomu zákazníkovi recenzovat obě z jediného formuláře.
Naplánování implementace
Než začnete budovat, zvažte:
- Které subjekty vyžadují stránku pro sběr a zda potřebujete jednu šablonu formuláře nebo několik v závislosti na typu subjektu.
- Která prostředí chcete podporovat: pouze vytváření recenzí nebo také aktualizaci a odstranění.
- Zda plánujete shromažďovat další atributy nad rámec standardních polí recenzí.
Design je zcela na vás. Jediným požadavkem je, aby vaše stránka mohla odesílat požadavky na koncové body pro odeslání recenze a volitelně recenzi aktualizovat nebo smazat.
Požadavky na recenze
Recenze shromážděné prostřednictvím vaší stránky musí odpovídat objektu recenze Yext: hodnocení 1–5 hvězdiček, text recenze a informace o autorovi. Objekt recenze nepodporuje dílčí hodnocení ani vlastní pole pro další atributy recenzenta, ale k odeslané recenzi můžete připojit štítky recenze. Úplnou referenci objektu recenze naleznete v dokumentaci k API.
Prevence spamu
Vytvoření vlastní stránky pro sběr recenzí znamená zveřejnění klíče API na straně klienta, což komukoli, kdo jej najde, umožní odesílat recenze přímo do vašeho účtu. Yext v současné době nenabízí pro tyto žádosti integrovanou podporu CAPTCHA. Pokud chcete ověřit, že příspěvky pocházejí od skutečných uživatelů, přidejte řešení CAPTCHA, jako je Google reCAPTCHA nebo hCaptcha, s proxy serverem mezi vaší stránkou pro sběr recenzí a rozhraním Yext API. Proxy ověří odpověď CAPTCHA a pak přepošle ověřené požadavky do Yext.
Koncové body API pro odesílání recenzí
| Koncový bod | Popis | URL |
|---|---|---|
| Review Submission: Create | Vytvoří novou vlastní recenzi | POST https://cdn.yextapis.com/v2/accounts/{accountId}/reviewSubmission |
| Review Submission: Update | Aktualizuje existující vlastní recenzi | PUT https://cdn.yextapis.com/v2/accounts/{accountId}/reviewSubmission/{apiIdentifier} |
| Review Submission: Delete | Nastaví stav existující vlastní recenze na REMOVED
|
DELETE https://cdn.yextapis.com/v2/accounts/{accountId}/reviewsSubmission/{apiIdentifier} |
Nastavení přístupu k rozhraní API
Vytvořte aplikaci v konzoli pro vývojáře a udělte jí přístup k API pro doručování obsahu odesílání recenzí, které zahrnuje vytváření, aktualizaci a odstraňování. Jelikož je tento klíč API vystaven na straně klienta, omezte rozsah oprávnění aplikace pouze na toto oprávnění.
Vytvoření recenze
Shromážděte požadovaná pole na své stránce, obvykle prostřednictvím formuláře, a odešlete je do koncového bodu Review Submission: Create, jakmile je uživatel odešle.
Zpracování odpovědi API
Koncový bod Create nevytvoří recenzi synchronně, takže nemůže ihned vrátit ID recenze. Úspěšný požadavek vrátí odpověď 202 Accepted spolu s apiIdentifier, což je buď invitationUid, které jste v požadavku zadali, nebo nově vygenerované UUID, pokud jste žádné nezadali. Tato hodnota se mapuje v poměru 1:1 na výslednou recenzi a je vyžadována pro její pozdější aktualizaci nebo odstranění. Požadavek s problémy při ověřování, jako je neplatná e-mailová adresa, vrací chybu 400, kterou může vaše stránka uživateli zobrazit.
Podpora aktualizace a odstraňování recenzí
Umožněte koncovým uživatelům aktualizovat nebo odstraňovat jejich vlastní recenze. Nejčastěji se objevují dva scénáře:
- Uživatel chce opravit chybu nebo změnit své rozhodnutí ihned po odeslání.
- Firma odpoví na recenzi a vyřešení vyzve koncového uživatele k aktualizaci nebo odstranění původní recenze, někdy i dlouho po jejím odeslání.
Tyto dva scénáře vyžadují odlišné přístupy.
Okamžité aktualizace
Protože recenze odeslaná přes Review Submission: Create není ihned dostupná přes Review: Get nebo Review: List, podporujte okamžité aktualizace uložením obsahu recenze a vráceného apiIdentifier na straně klienta. Jakýkoli požadavek na aktualizaci nebo odstranění, který uživatel spustí ihned po odeslání, může tuto uloženou hodnotu znovu použít.
Odložené aktualizace
Pokud chcete zajistit podporu úprav provedených po opuštění stránky uživatelem, načtěte recenzi později pomocí rozhraní Streams API, místo abyste se spoléhali na data uložená na straně klienta. Filtrujte svůj požadavek na rozhraní Streams API podle pole apiIdentifier, abyste získali odpovídající recenzi, a pak na základě těchto dat zobrazte rozhraní pro úpravy. Upozorňujeme, že daná recenze musí mít stav LIVE, aby ji rozhraní Streams API vrátilo. Pokud je recenze stále ve stavu QUARANTINED, rozhraní Streams API ji nevrátí.
Následující dva příklady ilustrují, kdy k tomu dochází:
-
Upozornění recenzenta na odpověď: sledujte události webhooku
REVIEW_COMMENT_UPDATED. Když firma odpoví na vlastní recenzi, pošlete recenzentovi e-mailem odkaz zpět na stránku pro sběr recenzí s parametrem dotazuapiIdentifier. Po kliknutí na odkaz stránka načte recenzi podleapiIdentifiera vykreslí se prostředí pro úpravy. -
Návrat přes původní odkaz s pozvánkou: pokud uživatel po zanechání recenze znovu klikne na původní e-mail s pozvánkou, stránka obdrží stejné
invitationUidjako parametr dotazu. Jelikož seapiIdentifierrovnáinvitationUidvždy, když byla k vytvoření recenze použita pozvánka, načtěte recenzi pomocí této hodnoty. Pokud existuje odpovídající recenze, vykreslete prostředí pro úpravy; pokud ne, vykreslete standardní prostředí pro vytváření.
apiIdentifier recenze je generovaný UUID, nikoli inkrementální ID recenze, což je pro tento účel bezpečnější: inkrementální ID by totiž komukoli umožnilo zvýšit nebo snížit známou hodnotu a získat tak přístup k jiným recenzím.
Načítání recenzí přes Streams API
Streams API je rozhraní API s nízkou latencí a možností přizpůsobení, které je vhodné pro načítání recenzí na straně klienta. Yext pro tento případ užití poskytuje předkonfigurovanou aplikaci, která vytvoří koncový bod Streams s ID reviewsStreamsEndpoints_reviews, takže nemusíte indexování konfigurovat ručně. Vzorový požadavek vypadá takto: