訪問者の識別

概要エンドポイント
APPLICABLE PRODUCTS
  • Marketing Hub
    • Professional or Enterprise
  • Sales Hub
    • Professional or Enterprise
  • Service Hub
    • Professional or Enterprise
  • CMS Hub
    • Professional or Enterprise
訪問者の識別APIを使用して、外部認証システムを通じて認証されたウェブサイトへの訪問者を識別できます。
 
このAPIから返された識別トークンは、チャットウィジットで認証済みの訪問者が登録済みのコンタクトとして扱われるように、その訪問者に関する情報をチャットウィジットに渡すために利用できます。これにより、受信トレイに届くEメールに対応する担当者は相手が誰なのかを把握し、その対応に自信が持てるようになり、訪問者はさまざまなデバイス上で過去のスレッド履歴を参照できるようになります。以下の例をご参照ください。

注：

  • 訪問者の識別APIは、訪問者が誰なのかをHubSpotに伝えることを目的としており、貴社のプラットフォームでのユーザー認証に使用することは推奨されません。
  • 訪問者の識別APIを使用するには、ProfessionalまたはEnterpriseのサブスクリプションが必要となります。アカウントで必要なサブスクリプションが登録されていない場合は、APIから403エラー応答が返されます。

連携フローの例

訪問者の識別機能との連携を使用するには、認証システムを備えた既存のWebアプリケーションが必要です。 

開始する前に、非公開アプリがセットアップされていること、また、対象となる「Professional」または「Enterprise」のサブスクリプションが、連携しようとしているアカウントで使用されていることを確認してください。
 
以下に、考えられる連携フローの例を示します。
考えられるユーザー識別フロー
顧客がシステムにログインして認証されたら、次の手順に従って、ライブチャットで顧客を識別します。

1. フロントエンドで、ウィンドウ上のhsConversationsSettingsオブジェクトのloadImmediatelyをfalseに設定します。このように設定しないと、識別情報が渡される前にチャットウィジェットが読み込まれる場合があります。詳細については、以下のチャットウィジェットSDK入門をご確認ください。

  • hsConversationsSettingsプロパティーをisConversationsAPIReady関数の外部で設定します。
  • また、呼び出しの前にhsConversationsSettingsを設定しておく必要があります。設定しない場合、ウィジェットの読み込みを妨げる競合状態が発生する可能性があります。
window.hsConversationsSettings = { loadImmediately: false };

2. 訪問者の識別APIに認証済み訪問者のEメールアドレスを渡して、トークンを生成します。この操作は、Webアプリケーションのバックエンドで行う必要があります。リクエストの例については、「エンドポイント」タブを参照してください。

curl --request POST \ --url 'https://api.hubspot.com/conversations/v3/visitor-identification/tokens/create \ --data '{ "email": "gob@bluth.com", "firstName": "Gob", "lastName": "Bluth" }'
以下の条件が満たされた場合、チャットが開始されると、取得した名と姓がコンタクトレコードに設定されます。
  • 訪問者の識別APIによって作成された新しいコンタクト
  • 氏名がまだ登録されていない既存のコンタクト

この機能は、外部システムには氏名の情報がすでに登録されているが、HubSpotにはまだ登録されていない認証済みの訪問者に対してパーソナライズされたメッセージを作成する際に有効です。パラメーターの指定は任意で、必須ではありません。

3. ステップ2で生成したトークンを使用して、ウィンドウ上のhsConversationsSettingsオブジェクトで次のプロパティーを設定します。

window.hsConversationsSettings = { identificationEmail: "visitor-email@example.com", identificationToken: "<TOKEN FROM STEP 1>" };

4. ウィジェットを読み込みます。

window.HubSpotConversations.widget.load();

認証済み訪問者に対してページが読み込まれるたびに、ウィンドウ上のhsConversationsSettingsオブジェクトでトークンとEメールを設定する必要があります。これらのパラメーターが設定されなくなると、以降のページの読み込み時に、コンテキストは自動的に保持されません。トークンは一時的なもので、12時間後に期限切れになります。トークンが少なくとも12時間に1回更新される場合、トークンをキャッシュして、ページを読み込むたびにトークンを再取得しなくて済むようにできます。 

連携を確認する

訪問者の識別機能との連携が完了したら、連携が想定通りに機能していることを確認します。以下に示すように、実装に応じて2通りの方法で確認できます。具体的な要件に合わせて、以下の例を調整する必要がある場合があります。

  • 1つ以上の公開ページ上および認証システムの背後にチャットウィジェットを追加している場合：
    • チャットウィジェットで訪問者を識別しないページに移動し、コミュニケーションを開始します。
    • HubSpotで受信トレイを開き、受信したチャットが「不明な訪問者」に属していることを確認します。そうでない場合は、非公開のブラウザーウィンドウで次の手順を試してみてください。
      • チャットウィジェットで訪問者の識別APIを使用して訪問者を識別するページに移動し、コミュニケーションを開始します。
      • HubSpotで受信トレイを開き、ログインに使用したコンタクトにチャットが属性として正しく結び付けられていることを確認します。正しい関連付けが確認された場合、コンタクトの名前の横に、このコンタクトが訪問者の識別APIで正常に識別されたことを示すバッジが表示されます。

        visitor_identity_badge
  • 認証システムの背後にあるページにのみチャットウィジェットを追加しており、複数のテスト ユーザー アカウントにアクセスできる場合:
    • 最初のテストユーザーとしてHubSpotにログインし、チャットウィジェットが読み込まれるページに移動して、コミュニケーションを開始します。
    • HubSpotからログアウトし、2番目のテストユーザーとして再度ログインします。チャットウィジェットが読み込まれるページに移動し、コミュニケーションを開始します。
    • HubSpotで受信トレイを開き、最初のテストアカウントと2番目のテストアカウントからそれぞれチャットが送信されていて、両方のレコードでコンタクト名の横にバッジが表示されていることを確認します。

注：訪問者の識別APIによって認証されたユーザーの場合、HubSpotはmessagesUtk Cookieを設定しません。また、すでにEメールが登録されているため、Eメールキャプチャーの質問もスキップされます。このようなチャットでは、messagesUtk CookieとEメールキャプチャーは適用されないため、訪問者の識別APIを介して認識されたユーザーにはチャットフローに関連する設定は表示されません。

チャットウィジェットSDK入門

このAPIは、window.HubSpotConversationsオブジェクトとして実装されています。使用可能な全てのメソッドには、このオブジェクトを介してアクセスできます。このオブジェクトはページ上のHubSpotスクリプトローダーによって自動的に作成されますが、直ちに利用可能にならない場合もあります。以下のように、初期化が完了するまで、APIへのアクセスを遅らせるには、window.hsConversationsOnReadyヘルパーを使用できます。

<script type="text/javascript"> function onConversationsAPIReady() { console.log(`HubSpot Conversations API: ${window.HubSpotConversations}`); } /* configure window.hsConversationsSettings if needed. */ window.hsConversationsSettings = {}; /* If external API methods are already available, use them. */ if (window.HubSpotConversations) { onConversationsAPIReady(); } else { /* Otherwise, callbacks can be added to the hsConversationsOnReady on the window object. These callbacks will be called once the external API has been initialized. */ window.hsConversationsOnReady = [onConversationsAPIReady]; } </script>

SDKリファレンス

window.hsConversationsOnReady配列

ウィジットが利用可能になった時点で実行されるコードを指定できるようにするwindowオブジェクトの定義が可能な任意のフィールドです。APIが初期化されると、この配列の有無が確認され、存在する場合は配列に含まれる一連の関数が逐次実行されます。

if (window.HubSpotConversations) { console.log('The api is ready already'); } else { window.hsConversationsOnReady = [ () => { console.log('Now the api is ready'); }, ]; }

hsConversationsSettingsオブジェクト

このオブジェクトを使用すると、設定オプションを指定してからウィジェットを初期化できます。訪問者の識別機能を使用するには、以下のフィールドを設定する必要があります。

Use this table to describe parameters / fields
パラメーターデータ型説明 既定値
loadImmediately
ブール

ウィジェットを暗黙的に読み込むか、またはwidget.loadメソッドが呼び出されるまで読み込みを待機するかを指定します。

 true
identificationToken
文字列

訪問者の識別APIと連携するために使用されます。訪問者の識別API上のトークン生成エンドポイントによって提供されるトークンで、この訪問者が認証済みであることを証明するものとして使用されます。

 ""
identificationEmail
文字列

ウィジェットを読み込む、識別済みの訪問者のEメールアドレス。

 ""
window.hsConversationsSettings = { loadImmediately: false, identificationEmail: "visitor-email@example.com", identificationToken: "<TOKEN FROM STEP 1>" };

コミュニケーションSDKの詳細をご確認ください。

参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。