日本語 Čeština Deutsch English (United States) Español (España) Français (France) Italiano

APIを使用してレビュー招待を管理する

この項目の対象者

  • エンタープライズ・アカウント、パートナー・アカウント、スモールビジネス・アカウントのお客様。
  • すべての地域のアカウント。

Yext Review Generationでは、Review Balancing URLを使用してレビューを依頼するメールやSMSの招待を顧客に送信できます。このURLは、Review Balancingアルゴリズムで設定した配信方法に応じて、ユーザーをサードパーティのレビューサイトや、自社のレビュー収集ページに誘導します。Review Balancingアルゴリズムの詳細については、「レビューの利用開始（Get Started with Reviews）」ガイドを参照してください。

Review Invitations APIを使用すると、外部システムと連携し、プログラムから招待を管理できます。

統合パターン

レビュー招待（Review Invitations）との統合では、通常、次の2つのパターンのいずれかを使用します。

プッシュ（Push）：トリガーが発生すると、外部システムからアプリケーションに通知が送信され、その後、アプリケーションが招待を作成します。一般的なプッシュトリガーには、次のようなものがあります。

  • 顧客が商品を受け取り、フルフィルメントシステムが配送完了を通知します。
  • 顧客が実店舗で購入を完了し、POSシステムが取引の完了を通知します。
  • 患者が診察を終え、スケジューリングシステムが予約ステータスの更新を通知します。

プル（Pull）：リアルタイム通知を受け取る代わりに、アプリケーションが定期的に招待トリガーデータを取得します。関連するトリガーに対して外部システムがWebhookをサポートしていない場合や、招待データがスケジュールに従ってFTPロケーションへエクスポートされる場合は、プル統合が一般的です。

 

Review Invitations APIエンドポイント

エンドポイント 説明 URL
Review Invitations: Create 新しいレビュー招待を作成します POSThttps://api.yextapis.com/v2/accounts/{accountId}/reviewInvites
Review Invitations: Get/List 既存のレビュー招待を取得します GET https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites
Review Invitations: Update 既存のレビュー招待を更新します PUT https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid}
Review Invitations: Delete 既存のレビュー招待を削除します DELETE https://api.yextapis.com/v2/accounts/{accountId}/reviewInvites/{uid}

 

招待フィールド

招待には、次のコアフィールドが含まれます。追加のフィールドはリクエスト本文で指定する必要があります。完全なリファレンスについては、APIドキュメントを参照してください。

フィールド 説明
エンティティID* レビューを依頼する対象のエンティティ。
名（First Name）* レビューを依頼する相手の名。
姓（Last Name）* レビューを依頼する相手の姓。
敬称（Title） レビューを依頼する相手の敬称（Mr.、Mrs.、Missなど）。
連絡先（Contact）* レビューを依頼する相手のメールアドレスまたは電話番号。
テンプレートID（Template ID） 招待の書式設定に使用するテンプレート。
トランザクションID（Transaction ID） 招待に関連付けられているトランザクションのID。
レビューラベル名（Review Label Names） 作成されるレビューに付与するレビューラベルの名前。
追加URLパラメーター（Additional URL Parameters） Review Balancing URLに追加するキーと値のペアで構成されるJSONオブジェクト。

*必須フィールド。

統合を構築する前に、アプリケーションが必要なすべてのフィールドを指定できることを確認してください。

APIアクセスを設定する

アプリを作成する

Developer Consoleでアプリを作成し、Review Invitations APIへのアクセス権を付与します。Get/Listエンドポイントには、読み取りアクセス権で十分です。ただし、招待の作成、更新、または削除を行うには、書き込みアクセス権が必要です。Review InvitationsエンドポイントにアクセスするためのAPIキーが、アプリ用に生成されます。このAPIキーをクライアントサイドのページに公開しないようにしてください。そのため、このアプリをクライアントサイドのリクエストには使用しないでください。

招待を作成する

Review Invitations: Createエンドポイントへのリクエストにより、指定した連絡先に招待が送信されます。電話番号を指定した場合はReview GenerationシステムからSMSが送信され、メールアドレスを指定した場合はメールが送信されます。

レスポンスには、後続のリクエストで必要になる次の2つのフィールドが含まれます。

  • invitationUid：招待の一意の識別子。
  • feedbackUrl：招待に含まれる完全なURL。クエリパラメーターとしてinvitationUIDが追加されています。受信者がこのURLからレビューを送信する際は、レビュー作成リクエストにInvitationUIDを含めてください。これにより、システムはレビューを招待に関連付けることができます。

 

招待に追加の詳細を含める

APIでは、招待とともに追加のコンテキストを渡すための2つの方法がサポートされています。渡した情報は、作成されるレビューで使用できます。

レビューラベル（Review labels）：reviewLabelNamesフィールドに値を渡します。一致するinvitationUidを使用してレビューが作成されると、それらの値がレビューラベルとしてレビューに適用されます。たとえば、reviewLabelNamesに「In-Store」を渡すと、作成されたレビューに「In-Store」ラベルが適用されます。

追加URLパラメーター（Additional URL parameters）：additionalURLParametersフィールドにキーと値のペアで構成されるJSONオブジェクトを渡します。これらはクエリパラメーターとしてフィードバックURLに追加されるため、コレクションページで読み取って必要に応じて使用できます。たとえば、ラベルとして適用する代わりに、データを外部アトリビューションシステムに送信できます。

 

外部システムから招待を送信する

ビジネスでメールまたはSMSの配信を独自に行っている場合は、リクエスト本文でsendInvitationFromYext = FALSEを渡すことで、Yextから招待を送信せずにYext内に招待レコードを作成できます。これは、次のような場合に便利です。

  • 独自のシステムで招待を送信する場合でも、招待の信頼できる情報源としてYextを維持したい場合。
  • 招待を受け取った顧客からのレビューのみを受け付けるために、後述する追加の設定を使用する場合。

 

送信時に招待UIDを必須にする

デフォルトでは、公開されているコレクションページでは、URLを知っている人であれば誰でもレビューを投稿できます。この動作を希望するビジネスは少なくありません。招待を受け取った顧客だけがレビューを投稿できるようにするには、アカウント設定で[ファーストパーティレビューに招待を必須（Require Invitations for First-Party Reviews）]を有効にしてください。有効にすると、Review Submission: Createエンドポイントへのすべてのリクエストに、有効なinvitationUidを含める必要があります。含まれていない場合、レビューは拒否されます。

外部システムから招待を送信し、この設定も必要な場合は、sendInvitationFromYext = FALSEを指定して招待レコードを作成した後、返されたfeedbackURLを顧客に送信してください。

 

招待をカスタムコレクションページにリダイレクトする

デフォルトでは、Review Balancing URLによって受信者はYextの標準コレクションページに誘導されます。代わりにファーストパーティの招待をカスタムコレクションページにリダイレクトするには、次の操作を行います。

  1. [レビュー > 生成 > 設定] の順に移動します。
  2. [ファーストパーティレビューコレクションページの上書き（First Party Review Collection Page Override）]を有効にします。
  3. カスタムURLを保存するためのカスタムフィールドを選択します。まだない場合は作成します。
  4. リダイレクトする各エンティティについて、そのカスタムフィールドに値を設定します。

これらの手順を完了すると、[ファーストパーティレビューページ（First Party Review Page）]フィールドに、カスタムフィールドの値が設定されます。Review Balancing URL自体は変更されません。引き続きReview Balancingアルゴリズムの設定に基づいて誘導先のパブリッシャーを決定し、ファーストパーティレビューに誘導する場合はカスタムURLを使用します。

テンプレートを使用して招待を書式設定する

招待テンプレートでは、受信者に表示される招待の形式を制御できます。Yextでは、メールテンプレートとSMSテンプレートの両方がサポートされており、プラットフォームからカスタマイズできます。設定手順については、「Review Generationテンプレート（Review Generation Templates）」を参照してください。招待の作成時にテンプレートIDを指定しない場合は、Yextによってアカウントのデフォルトテンプレートが使用されます。

CAN-SPAM法への準拠

CAN-SPAM法では、商用メールに送信者の住所を記載することが義務付けられています。Yextのメールシステムを使用して招待を送信するには、Review Generationアカウント設定にブランド名と住所を追加します。Yextでは、この情報が招待メールのフッターに自動的に追加されます。

招待を更新または削除する

送信前の招待をキャンセルしたり、配信前にその他の変更を加えたりするには、Updateエンドポイントを使用します。招待レコードを完全に削除するには、Deleteエンドポイントを使用します。招待を削除しても、すでに送信された招待の配信ステータスには影響しません。

統合をテストする

本番環境へ展開する前に、本番環境以外のアカウントまたはサンドボックスアカウントで統合をテストします。毎晩実行されるチェックなどの自動テストでは、データパイプラインが招待を正しく送信していることを確認するために、テスト用の招待を作成し、その後Deleteエンドポイントを使用して削除します。