コミュニケーションSDK
HubSpotのウェブ チャット ウィジェットを使用すると、自社のウェブサイト上で顧客やリードとチャットできます。チャットウィジェットSDKを使用してチャットウィジェットの動作をカスタマイズすることで、1人ひとりの訪問者に合わせた最適な顧客体験を提供できます。
使用例:チャットウィジェットSDKを使用して、HubSpotのチャットウィジェットがウェブサイト上に表示されるタイミングや形式をカスタマイズできます。
主に次のような処理に活用できます。
はじめに
本APIはwindow.HubSpotConversations
オブジェクトに実装されています。使用可能な全てのメソッドは、このオブジェクトを介して利用します。このオブジェクトはページ上のHubSpotスクリプトローダー(通称HubSpotトラッキングコード)によって自動的に作成されますが、即座に利用可能にならない場合もあります。初期化の完了までの間、APIへのアクセスを遅延させるには、window.hsConversationsOnReady
ヘルパーを使用できます。以下に簡単な例を紹介します。
hsConversationsSettings
このオブジェクトを使用して、ウィジェットの初期化が行われる前に、設定オプションを提供できます。このオブジェクトの使用は任意です。
フィールド名 | データ型 | 既定値 | 説明 |
---|---|---|---|
|
ブール | true | ウィジェットを暗黙的に読み込むか、またはwidget.load メソッドが呼び出されるまで読み込みを待機するかを指定します。 |
inlineEmbedSelector |
文字列 | "" | ページ内でのウィジェットの埋め込み箇所。セレクター(#some-idなど)を指定すると、該当するDOMノード内にウィジェットがインラインで埋め込まれます。また、widget.remove を使用して取り除くまでの間、開いた状態が維持されます。 |
enableWidgetCookieBanner |
列挙 | false | ページ上の全てのチャットフローに関するCookieバナーの動作を制御します。false - チャットフローの設定を適用します(既定)。true - ウィジェットが読み込まれた際のCookieバナーを有効にします。ON_WIDGET_LOAD - trueと同じ。ウィジェットが読み込まれた際のCookieバナーを有効にします。ON_EXIT_INTENT - ユーザーがチャット終了の意図を示した際のCookieバナーを有効にします。なお、このフィールドは従来、 Boolean でした。現在は、当初のBoolean 値と新たなenum 値の両方に対応しています。 |
disableAttachment |
ブール | false | チャットウィジェット内で添付ファイルのアップロードボタンを非表示にするかどうかを指定します。 |
インライン埋め込みスタイル
window.hsConversationsOnReady
具体的な場所を指定してウィジェットを埋め込むと複数のDOM要素が追加されるため、貴社のカスタマイズ要件(高さ、幅、境界線など)に合わせてスタイルを設定できます。この構造は、inlineEmbedSelector
オプションを使用した場合にのみ適用されることにご留意ください
<div id="hubspot-conversations-inline-parent">
<iframe id="hubspot-conversations-inline-iframe" />
</div>
例えば、このチャットウィジェットは既定で次のように表示されます。
このように窮屈なレイアウトは望ましくない場合、次のようなスタイルを組み込んでウィジェットをカスタマイズできます。
#hubspot-conversations-inline-iframe {
width: 300px;
height: 500px;
border:none;
}
これにより、ユーザーエクスペリエンスが大幅に向上します。
HubSpotConversations.widget
widgetオブジェクトには、ページ上のチャットウィジェットを操作するための数多くのメソッドが実装されています。
widget.load
ページに初めてウィジェットを読み込みます。ウィジェットが読み込み済みの場合、このメソッドに対する以降の呼び出しはno-op(操作なし)命令になり、何も行われません。
このメソッドが必要になるのは、loadImmediately
フラグをfalse
に設定した場合に限られます。それ以外の場合、ウィジェットは自動的に読み込まれます。
注: widget.load
の呼び出し頻度は1秒につき1回です。
パラメーター:
フィールド名 | データ型 | 既定値 | 説明 |
---|---|---|---|
widgetOpen |
ブール | false | ウィジェットを開いた状態で読み込むかどうかを指定します。 |
widget.refresh
現在のページURLを基に、ウィジェットの情報を再度読み込んでレンダリングし直します。
単一ページのアプリにチャットウィジェットを設置している場合、このメソッドはルート変更に基づくウィジェットの再読み込みに役立ちます。これにより、ページルートごとに異なるチャットフローを設定できます。チャットフローがないルートに対してwidget.refresh
が呼び出され、ユーザーがコミュニケーションを利用していない場合は、ウィジェットは取り除かれます。
注:widget.refresh
の呼び出し頻度は1秒につき1回です。
パラメーター:
フィールド名 | データ型 | 既定値 | 説明 |
---|---|---|---|
openToNewThread |
ブール | false | 新しいスレッドを作成するかどうかを指定します。 |
openToNewThread
フィールドの使用例については、特定のチャットフローを開く(英語)を参照してください。
例:
widget.close
ウィジェットを閉じます。ウィジェットがすでに閉じられているか、現在読み込まれていない場合は、no-op(操作なし)命令になり、何も行われません。
例:
widget.remove
ページからウィジェットを取り除きます。ページ上にウィジェットが存在しない場合は、no-op(操作なし)命令になり、何も行われません。ウィジェットを再度表示するには、ページ全体を読み込み直す必要があります。または、widget.load
を呼び出すことも可能です。
例:
clear
チャットウィジェットでは、サイト訪問やページの再読み込みが繰り返されても状態を維持できるように、複数のCookieが作成されます。このようなCookieはウィジェットのホスティング先ページのドメインを対象に、以下の機能を有効にするために使用されます。
- 過去のコミュニケーションを参照する
- ページ読み込みが繰り返されてもチャットウィジェットを開いた状態に維持する
- ページ読み込みが繰り返されても歓迎メッセージを開いた状態に維持する
clear
メソッドを使用することで、これらのCookieを削除し、以降の読み込み時にウィジェットを既定の状態に戻すことができます。
このメソッドにより、以下のCookieが消去されます。
messagesUtk
hs-messages-is-open
hs-messages-hide-welcome-message
このようなCookieの詳細については、このナレッジベースの記事を参照してください。
例:
さらに、{resetWidget:true}
をclear()
関数に渡すことで、チャット関連の全てのCookieを消去し、ページからウィジェットを取り除いた上で、チャットウィジェットの新しいインスタンスを作成できます。
例:
Event specification
チャットウィジェットからは、ライフサイクル全体にわたって各種のイベントが送信されます。このイベントを検知し、応答することができます。
サポートされるイベント
conversationStarted
新しいコミュニケーションが正常に開始されると、送信されます。
イベントのペイロード
フィールド名 | データ型 | 説明 |
---|---|---|
conversation |
コミュニケーション(英語) | 開始されたコミュニケーションの詳細 |
例:
conversationClosed
新しいコミュニケーションが正常にクローズされると送信されます。
注:このイベントは、コミュニケーションの受信トレイからコミュニケーションがクローズされると発生します。ユーザーによってチャットウィジェットが最小化されたり閉じられたりすることとは関係ありません。
イベントのペイロード
フィールド名 | データ型 | 説明 |
---|---|---|
conversation |
コミュニケーション(英語) | クローズされたコミュニケーションの詳細 |
例:
unreadConversationCountChanged
ウィジェット内の未読メッセージを含むコミュニケーションの数が変化(増減)すると送信されます。
イベントのペイロード
フィールド名 | データ型 | 説明 |
---|---|---|
unreadCount |
数値 | ウィジェットでの未読メッセージを含む新しいコミュニケーションの合計数 |
例:
contactAssociated
訪問者がCRM内のコンタクトと関連付けられると、送信されます。
イベントのペイロード
フィールド名 | データ型 | 説明 |
---|---|---|
message |
文字列 | 訪問者がコンタクトと関連付けられたことに関する確認メッセージ |
例:
貴重なご意見をありがとうございました。