タイムラインイベント

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開発者アカウントでイベントテンプレートを管理することもできます。

アプリの設定から［タイムラインイベント］に進み、［イベントタイプを作成］ボタンを使用してアプリ用の新しいイベントテンプレートを作成します。以前に作成したイベントテンプレートがある場合は、ここに表示されます。

新しいイベントテンプレートの下書きから始めます。イベントのオブジェクトタイプ、さらに詳細テンプレートとヘッダーテンプレートを設定したら、［作成］をクリックします。

イベントテンプレートの作成または編集を行う際には、使用するトークンを［データ］タブで設定します。

イベントテンプレートを定義したら、トークンも定義してみてください。イベント テンプレート トークンを使用することにより、カスタムデータをイベントに添付してタイムラインに表示できます。コンタクトでは、カスタムデータをリストのセグメンテーションや自動化に使用できます。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呼び出しで全ての要素を定義できます。 

イベントを作成する

トークンとテンプレートを備えたイベントテンプレートを設定できました。次は、顧客のコンタクト、会社、取引、およびチケットのイベントを作成します。ここまでで作成したcontactsイベントテンプレートを、以降の例でも使用します。イベントテンプレートの設定にwebinarNameとwebinarIdのトークンが含まれていない場合は、イベントを作成する際にエラーが発生します。イベントを作成するための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以下

タイムラインイベントに使用するアイコンを設定するには、［タイムラインイベント］に進みます。プレースホルダー画像または既存のアイコンをクリックして、設定または変更します。

設定したアイコンは、アプリに関連する全てのタイムラインイベントの横に表示されます。

関連ドキュメント

CRMについて

CRMカード