Review Generationを利用しているすべてのエンティティには、標準のカスタマイズできないレビューコレクションページが提供されます。レビュー収集エクスペリエンスの外観や操作性、および追加で収集するデータを完全に制御したい場合は、レビュー送信APIを使用してカスタムコレクションページを作成します。この記事では、APIの仕組みと、ページを作成する際に考慮すべきオプションについて説明します。

レビュアーによるコレクションページへのアクセス方法

• 招待あり（Via invitation）：企業が顧客にリンク付きの招待を直接送信。
• 招待なし（Without an invitation）：企業が標準の一般公開されたコレクションページを公開し、顧客が自分でアクセス。

一般的なコレクションページの構成

• エンティティごとに1つのページ（One page per entity）：最も一般的な構成です。レビューを収集する各エンティティに対して、一意のコレクションページを1つ用意します。例えば、100種類の商品を扱う企業では、商品ごとに1つのページを用意します。
• エンティティセレクターを備えた1つのページ（One page with an entity selector）：1つのページで複数のエンティティに対応し、レビュアーがレビュー対象のエンティティを選択します。ページでは、APIリクエストに選択したエンティティが含まれます。例えば、企業は製品カテゴリ全体に対して1つのページを用意し、特定の商品を選択するためのセレクターを配置できます。
• 複数のエンティティを収集する1つのページ（One page collecting multiple entities）：1つのページで、同じセッション内に複数のエンティティのレビューを収集します。例えば、「自動車保険 - 補償（Auto Insurance - Coverage）」と「自動車保険 - サービス（Auto Insurance - Service）」という別々のエンティティを持つ企業では、顧客は1つのフォームから両方のレビューを投稿できます。

実装を計画する

構築を開始する前に、次の点を検討してください。

• コレクションページが必要なエンティティと、エンティティタイプに応じてフォームテンプレートを1つにするか、複数にするか。
• サポートするエクスペリエンスを、レビューの作成のみにするか、更新や削除もサポートするか
• 標準のレビューフィールドに加えて、追加の属性を収集する予定があるかどうか

デザインはすべて自由に決められます。唯一の要件は、ページからReview Submissionエンドポイントにリクエストを送信してレビューを送信できること、および必要に応じてレビューを更新または削除できることです。

レビュー要件

ページで収集したレビューは、Yextレビューオブジェクトに準拠している必要があります。レビューには、1～5の星評価、レビュー本文、および投稿者情報を含める必要があります。レビューオブジェクトでは、サブ評価や、レビュアーの追加属性用のカスタムフィールドはサポートされていません。ただし、送信されたレビューにはレビューラベルを追加できます。レビューオブジェクトの詳細については、APIドキュメントを参照してください。

スパムを防止する

カスタムコレクションページを構築する場合は、クライアント側でAPIキーを公開することになります。そのAPIキーを入手したユーザーは、誰でもアカウントに直接レビューを送信できます。現在、Yextでは、これらのリクエストに対するCAPTCHAの組み込みサポートは提供していません。実際のユーザーから送信されたことを確認するには、Google reCAPTCHAやhCaptchaなどのCAPTCHAソリューションを追加し、コレクションページとYext APIの間にプロキシサーバーを配置します。プロキシはCAPTCHAのレスポンスを検証した後、検証済みのリクエストをYextに転送します。

Review Submission APIエンドポイント

APIアクセスを設定する

デベロッパーコンソールでアプリを作成し、作成・更新・削除の操作が可能なReview Submission Content Delivery APIへのアクセス権を付与してください。このAPIキーはクライアント側に公開されるため、アプリの権限をこの許可のみに制限してください。

レビューを作成する

ページ上で必要なフィールド（通常はフォーム）に入力されたデータを収集し、ユーザーが送信したらReview Submission: Createエンドポイントに送信します。

APIレスポンスを処理する

Createエンドポイントではレビューは同期的に作成されないため、レビューIDをすぐに返すことはできません。リクエストが成功すると、HTTP 202 Acceptedレスポンスとともに、リクエストで指定したinvitationUid、または指定しなかった場合は新しく生成されたUUIDを値とするapiIdentifierが返されます。この値は作成されたレビューと1対1に対応しており、後でレビューを更新または削除する際に必要になります。メールアドレスが無効であるなど、リクエストに検証エラーがある場合は、HTTP 400エラーが返されます。このエラーをページ上でユーザーに表示できます。

レビューの更新と削除をサポートする

エンドユーザーが自分のレビューを更新または削除できるようにサポートします。一般的なシナリオは、次の2つです。

• ユーザーが送信直後に誤りを修正したい場合や、考えを変えた場合です。
• 企業がレビューに返信し、その解決内容を受けて、エンドユーザーが元のレビューを更新または削除する場合です。投稿からかなり時間が経過した後になることもあります。

これら二つのシナリオには、それぞれ異なるアプローチが必要となります。

即時更新

Review Submission: Createで送信したレビューはReview: GetやReview: Listですぐには取得できないため、即時更新をサポートするには、レビューの内容と返されたapiIdentifierをクライアント側に保存します。ユーザーが送信直後に更新または削除を実行した場合は、その保存した値を再利用できます。

即時でない更新

ユーザーがページを離れた後の編集をサポートするには、保存されているクライアント側のデータに頼るのではなく、後でStreams APIを使用してレビューを取得してください。Streams APIリクエストをapiIdentifierフィールドでフィルタリングして一致するレビューを取得し、そのデータを使用して編集エクスペリエンスを表示しますStreams APIで返されるには、問題のレビューがライブステータスである必要があることに注意してください。レビューがまだQUARANTINEDの場合、Streams APIによって返されません。

次の2つの例は、この方法が使用される場面を示しています。

• レビューへの返信をレビュアーに通知する（Notifying a reviewer of a response）：REVIEW_COMMENT_UPDATED webhookイベントを監視します。企業がファーストパーティレビューに返信したら、apiIdentifierをクエリパラメーターとして含むコレクションページへのリンクを、レビュアーにメールで送信します。レビュアーがリンクをクリックすると、ページはapiIdentifierを使用してレビューを取得し、編集エクスペリエンスを表示します。
• 元の招待リンクから戻る（Returning through the original invitation link）：レビューを投稿した後にユーザーが元の招待メール内のリンクを再度クリックすると、ページは同じinvitationUidをクエリパラメーターとして受け取ります。レビューの作成時に招待が使用された場合は常に、apiIdentifierはinvitationUidと同じ値になるため、その値を使用してレビューを取得します。一致するレビューが存在する場合は編集エクスペリエンスを表示し、存在しない場合は標準の作成エクスペリエンスを表示します。

レビューのapiIdentifierは、連番のレビューIDではなく、生成されたUUIDです。この方式は、既知の値を増減させることで他のレビューにアクセスされることを防げるため、この用途では連番IDよりも安全です。

Streams APIを使用してレビューを取得

Streams APIは、クライアント側からレビューを取得するのに適した、低レイテンシでカスタマイズ可能なAPIです。Yextでは、このユースケース向けに事前構成済みのアプリが提供されており、ID がreviewsStreamsEndpoints_reviewsのStreamsエンドポイントが作成されるため、インデックスを手動で設定する必要はありません。リクエストの例：