タイムラインイベント
CRM拡張機能を使用すると、HubSpotのコンタクト/会社/取引オブジェクトについて外部のシステムからの情報を表示できます。そのためにはカスタム タイムライン イベントを作成し、タイムライン イベント エンドポイントを使用します。ユーザーによるデータ編集を可能にしたいが、既定のCRMオブジェクトの中にニーズに合うものがない場合は、カスタムオブジェクトの使用を検討してください。
例えば、自社とのやり取りやコンテンツに基づいて、コンタクトのセグメンテーションを強化したいとします。そのためには、さらに多くの情報が必要です。コンタクトとのやり取りに関して詳細なコンテキスト情報を示すカスタムイベント(最近のウェビナーへの登録のみで欠席したコンタクト、コンタクトが登録を完了したフローなど)を、アプリで作成することが考えられます。
イベントテンプレートを作成する
イベントを作成するには、事前にイベントテンプレートを作成しておく必要があります。イベントテンプレートでは、HubSpotの中のコンタクト、会社、または取引オブジェクトのタイムラインにアプリが追加するアクションを記述します。アクションの例としては、動画表示、ウェビナー登録、アンケート記入などがあります。アプリごとに、最大750件のイベントテンプレートを作成できます。
既定では、イベントテンプレートはコンタクトに対して作成されますが、objectType
フィールドを使用することによって会社や取引について作成することもできます。詳細は、タイムライン イベント テンプレートの作成に関する説明を参照してください。
イベントテンプレートごとに、トークンとテンプレートの固有のセットがあります。コンタクトに対して作成されたイベントを、新しいコンタクトリストまたはワークフローを作成する際の条件として使用できます。例えば、「動画名にXYZが含まれる動画にいいね!を付けた全てのコンタクトのリストを作成する」というように設定できます。この場合、イベントテンプレートは「Video Like」という名前が付けられ、「video name」というイベントトークンを持っています。
APIを使用してイベントテンプレートを作成する
この例では、新しいイベントテンプレート「Example Webinar Registration」を作成します。認証には開発者APIキーを使用します。これは、アプリ開発者アカウントで確認できます。
<<appId>>
は自分のアプリIDに置き換えてください。アプリIDは、開発者アカウントの[マイアプリ]またはアプリの詳細ページで確認できます。また、<<developerHapikey>>
も自分の開発者APIキーに置き換える必要があります。APIキーは、[アプリ]>[HubSpot APIキーを取得]の順に進むことで確認できます。
ここでheaderTemplate
とdetailTemplate
のプロパティーも指定できます(下記の「テンプレートの定義」を参照)。
このPOST
リクエストは、保存されているイベントテンプレート定義全体を返します。レスポンス内にあるid
プロパティーに注目してください。これがイベントテンプレートIDで、今後このイベントテンプレートまたはトークンを更新する際に必要になります。
次のGETコマンドを使用すれば、アプリで定義されている全てのイベントテンプレートを確認できます。この場合も、イベントテンプレートIDが返されます。
HubSpotでイベントテンプレートを作成する
APIによるタイムライン イベント テンプレートの作成および管理に加えて、HubSpot開発者アカウントでイベントテンプレートを管理することもできます。
アプリの設定から[タイムラインイベント]に進み、[イベントタイプを作成]ボタンを使用してアプリ用の新しいイベントテンプレートを作成します。以前に作成したイベントテンプレートがある場合は、ここに表示されます。
新しいイベントテンプレートの下書きから始めます。イベントのオブジェクトタイプ、さらに詳細テンプレートとヘッダーテンプレートを設定したら、[作成]をクリックします。
イベントテンプレートの作成または編集を行う際には、使用するトークンを[データ]タブで設定します。
注:テンプレートを削除すると、テンプレートを使用していた既存のイベントが、アプリが接続されているアカウントから完全に削除されます。そのタイプのイベントは新規に作成できなくなりますが、リストやレポートでは従来から存在しているタイプのイベントデータは確認できます。この変更がHubSpotに反映されるまでに数時間かかる場合があります。
イベントテンプレートを定義したら、トークンも定義してみてください。イベント テンプレート トークンを使用することにより、カスタムデータをイベントに添付してタイムラインに表示できます。コンタクトでは、カスタムデータをリストのセグメンテーションや自動化に使用できます。1つのタイムライン イベント テンプレートにつき最大500件のトークンを作成できます。
APIを使用してイベントトークンを作成する
ステップ1で作成したイベントテンプレートIDを使用して、コンタクトが登録しているウェビナーを特定するためのトークンを追加します。
同様に、GET
からはイベントテンプレートに定義されている全てのトークンが返されます。
サポートされているトークンの種類は次のとおりです。
string
number
enumeration
- 選択肢のセット。前述のwebinarTypeの例をご覧ください。date
- 日付には必ずミリ秒単位のUnix時刻を使用します。
注:イベントトークンにlogまたはlookupという名前を付けることはできません。これらのトークンは、Handlebars.js(アプリ内イベントのレンダリングに使用されるライブラリー)によるヘルパーとして予約済みです。詳細は、Handlebars.jsのドキュメント(こちら)を参照してください。
ヘッダーテンプレートおよび詳細テンプレートを定義する
ヘッダーテンプレートと詳細テンプレートは、タイムラインイベントの表示方法を定義します。MarkdownドキュメントをHandlebarsテンプレートで指定できます。ヘッダーテンプレートはイベントについての1行の説明文で、詳細テンプレートはイベントに関する具体的な情報です。以下に例を示します。
イベントトークンは、データとしてテンプレートに渡されます。この例では、テンプレートの中でを使用することによって
webinarName
トークンを参照できます。
イベントのextraData
(後述の「extraDataについて」を参照)は、詳細テンプレートの中でのみ参照できます。
APIを使用してヘッダーテンプレートおよび詳細テンプレートを定義する
ヘッダーテンプレートと詳細テンプレートは、イベント テンプレート エンドポイント経由でイベントテンプレートに定義できます。例えば、「Example Webinar Registration」の例では、PUT
を使用して変更を加えることにより、テンプレートを追加できます。
#formatDate
ディレクティブの使用にも注目してください。ユーザーにとって分かりやすい日付形式にするために定義しています。
このようにコンタクトに関するイベントを作成すると(後述のイベントの作成を参照)、コンタクトのタイムラインに次のように表示されます。
[詳細を表示]をクリックすると、詳細テンプレートが表示されます。
イベントの横に表示されるアイコンを設定するには、後述のカスタムアイコンの設定を参照してください。
ここでの「Example App Name」というテキストはアプリの名前です。CRMタイムライン内では、アプリ単位でイベントを絞り込むことができます。
1回の呼び出しでイベントテンプレートの全ての要素を定義する
ここまではイベントテンプレートの各要素を紹介してきましたが、1回のPOST
呼び出しで全ての要素を定義できます。
これにより、a.test.contact@email.com
のタイムライン上にイベントが生成されます(前述の「テンプレートの定義」のテンプレートがある前提で)。
イベントタイムスタンプを設定する
イベントがオブジェクト内のタイムラインに現れる位置は、イベントのタイムスタンプによって決まります。イベントタイムスタンプには、既定でPOSTコマンドの送信時刻が設定されます。イベント時刻は、タイムスタンププロパティーのリクエスト本文に明示することによりカスタマイズできます。
特定のアクションが発生した正確な時刻が分かっている場合は、明示することが適切です。この例の場合、このウェビナー登録のタイムスタンプが分かっていればPOST内で指定してください。
タイムスタンプは、ミリ秒単位のエポック時間、またはISO 8601形式です。
イベントをCRMオブジェクトに関連付ける
イベントを作成するには、顧客のアカウント内のコンタクト、会社、または取引に対し、イベントを関連付けなければなりません。
前述の例では、objectTypeにコンタクトを指定し、Eメールを使用してイベントをコンタクトに関連付けました。HubSpot上ではコンタクトのEメールアドレスは重複しないため、指定されたEメールのコンタクトがすでに存在する場合、そのコンタクトが更新されることになります。既存のコンタクトがない場合は、新しいコンタクトが作成されます。既定では、指定したEメール コンタクト プロパティーのみがこの新しいコンタクトに格納されます。コンタクトプロパティーにデータを追加する方法については、コンタクトプロパティーに対するイベントデータの付加に関する説明を参照してください。
既存のコンタクトの場合、イベントの関連付けにコンタクトのvid
を使用することもできます。その場合、リクエストJSONの中でobjectId
を使用します。objectId
を使用してコンタクトを新規に作成することはできないため、既存のコンタクトのvidを含める必要があります。この例では、EメールではなくobjectId
を使用しています。
ユーザートークンまたはutk
により、イベントをコンタクトに関連付けることもできます。ユーザートークンは、HubSpotトラッキングコードでの訪問者のトラッキングに使用され、hubspotutk
のCookie内に格納されます。utk
パラメーターは、ユーザートークンによってイベントをコンタクトに関連付ける際に使用します。注:匿名の訪問者にはユーザートークンを使用してイベントを関連付けることができません。したがってイベントの関連付けにutk
のみが使用されていて、かつ提供されているユーザートークンがまだコンタクトに関連付けられていない場合は、新しいコンタクトが作成されず、イベントはHubSpot上で確認できなくなります。しかし、新しいコンタクトが別の手段(通常はhutkを含むフォーム送信(英語)、またはトラッキングコードAPIのidentifyメソッド(英語))によってユーザートークンに関連付けられていた場合は、イベントがタイムラインに表示されます。そのため、utk
に加えてemail
を含めることにより、イベントを新しいコンタクトまたは既存のコンタクトに関連付けることを強くお勧めします。
コンタクトのイベントテンプレートの場合、イベントに複数の識別パラメーターを指定できるため、email
、objectId
、utk
のパラメーターを組み合わせて含めることができます。複数のパラメーターを含めた場合、イベントに関連付けるコンタクトの判定ではobjectId(vid)が最も優先され、次にutk
、そして最後にemail
が使用されます。したがって、既存のオブジェクトのvid
をobjectId
に、またemail
パラメーターに新しいEメールアドレスを指定することによって、既存のオブジェクトのEメールアドレスを更新することができます。この例では、Eメールアドレスとユーザートークンを組み合わせています。
コンタクトだけでなく、会社や取引についてのイベントテンプレートも作成できます。その場合、イベントテンプレートにobjectId
を指定して、会社または取引にイベントを関連付ける必要があります。会社の場合、objectId
にイベントを関連付ける会社のcompanyId
を設定する必要があります。また、取引の場合、objectId
に取引オブジェクトのdealId
を設定します。
前述の例の場合、イベントテンプレートがCOMPANY
objectType
に設定されているとすると、このイベントはcompanyId
528253914の会社オブジェクトに関連付けられることになります。
タイムラインを拡張する
タイムライン拡張機能を使用すると、iFrameを使用して外部システムからデータを表示することが可能になり、イベントにはモーダルウィンドウを表示するリンクが表示されます。リンクをクリックすると、iFrameのコンテンツが表示されます。iFrameの詳細はtimelineIFrameフィールドに指定します。このオブジェクトには、次のフィールドがあります。
linkLabel
- IFrameを表示するリンクの表示に使用するテキスト。headerLabel
- IFrameコンテンツを表示するモーダルウィンドウのラベル。url
- IFrameコンテンツのURI。width
- モーダルウィンドウの幅。height
- モーダルウィンドウの高さ。
例えば、イベントに次のデータを使用した場合:
「View external data」リンクを含む、次のイベントが作成されます。
このリンクをクリックするとモーダルウィンドウが表示され、url
に設定されているページが表示されます。
CRMオブジェクトのプロパティーに対してイベントデータを付加する
イベントを追加するコンタクト、会社、取引のプロパティーに、変更が必要になるケースは少なくありません。特に、イベントを追加することでコンタクトが作成される場合が該当します。Eメールアドレスとイベントだけのコンタクトを作成しないためにも、コンタクトの姓名のプロパティーを更新する必要があるはずです。
カスタム イベント トークンをコンタクト、会社、または取引のプロパティーにマッピングすることにより、イベントからの関連オブジェクトのデータを付加することができます。
カスタム イベント テンプレートを更新するための次のPUT
の中で、objectPropertyName
フィールドに注目してください。
objectPropertyName
を使用して、このカスタム イベント トークンをcontact
オブジェクトのzz_webinar_name
プロパティーにマッピングしています。つまり、webinarName
トークンを指定した新しいイベントを作成すると、関連するcontact
のzz_webinar_name
プロパティーも設定されます。この設定は、カスタムまたは事前定義済みのHubSpotプロパティーに対して行うことができます。
例えば、コンタクトのzz_company_name
カスタムプロパティーを参照するcompanyName
トークンを事前に作成しているとします。その場合に次のようなイベントを作成すると、Eメールアドレスがa.test.contact@email.comのコンタクトにzz_company_name
とzz_webinar_name
のプロパティーが設定されます。
注:イベントトークンがカスタムプロパティーに付加される際に該当するカスタムプロパティーがHubSpotアカウント上に存在しない場合、イベントには値が設定されますが、対応するオブジェクト側では無視されます。
extraData
を理解する
イベント テンプレート トークンによって使用される「トークンと値」の単純な構造が適さない詳細なデータを、イベントに追加することが必要になるかもしれません。あるいは連携のイベントに、リストまたは階層状の内訳が必要になる場合も考えられます。こうした状況で役立つのがextraData
です。
extraData
属性をイベントのJSON本文に追加することができます。このextraData
の値として、任意の有効なJSONを指定できます。例:
詳細テンプレートでのextraData
の使用例:
タイムラインイベントには次のように表示されます。
注:extraData
属性は、イベントの詳細テンプレート内でのみ参照できます。ヘッダーテンプレートやリストセグメンテーションの中では使用できません。
カスタムアイコンを設定する
タイムライン上の項目にビジュアル効果を付けるために、必要に応じてカスタムアイコンを追加できます。
アイコンには、次のような画像ファイルを使用してください。
- ほぼ正方形に近い形
- 背景を透過にする
- コンテンツをアイコンの中央に配置する
- 30×30ピクセルまで縮小可能
- ファイルサイズが5MB以下
タイムラインイベントに使用するアイコンを設定するには、[タイムラインイベント]に進みます。プレースホルダー画像または既存のアイコンをクリックして、設定または変更します。
設定したアイコンは、アプリに関連する全てのタイムラインイベントの横に表示されます。
関連ドキュメント
貴重なご意見をありがとうございました。