タイムラインイベント
CRM拡張機能を使用すると、HubSpotのコンタクト/会社/取引オブジェクトについて外部のシステムからの情報を表示できます。そのためにはカスタム タイムライン イベントを作成し、タイムライン イベント エンドポイントを活用します。
使用例:自社とのやり取りやコンテンツに基づいて、コンタクトのセグメンテーションを強化したいとします。そのためには、さらに多くの情報が必要です。コンタクトとのやり取りに関してより詳細なコンテキスト情報を示すカスタムイベント(最近のウェビナーへの登録のみで欠席したコンタクト、コンタクトが登録を完了したフローなど)を、アプリで作成することが考えられます。
タイムライン イベント テンプレートの削除に関する注意事項
テンプレートを削除すると、テンプレートを使用していた既存のイベントが、アプリが接続されているアカウントから完全に削除されます。そのタイプのイベントは新規に作成できなくなりますが、リストやレポートでは従来から存在しているタイプのイベントデータは確認できます。この変更がHubSpotに反映されるまでに数時間かかる場合があります。
タイムラインイベントの設定
タイムラインイベントの例を以下に示します。
1. イベントテンプレートの作成
イベントを作成するには、事前にイベントテンプレートを作成しておく必要があります。イベントテンプレートでは、HubSpotの中のコンタクト、会社、または取引オブジェクトのタイムラインにアプリが追加するアクションを記述します。アクションの例としては、動画表示、ウェビナー登録、アンケート記入などがあります。アプリごとに、最大750件のイベントテンプレートを作成できます。
既定では、イベントテンプレートはコンタクトに対して作成されますが、objectType
フィールドを使用することによって会社や取引について作成することもできます。詳細は、タイムライン イベント テンプレートの作成に関する説明を参照してください。
イベントテンプレートごとに、トークンとテンプレートの固有のセットがあります。コンタクトに対して作成されたイベントは、新しいコンタクトリストまたはワークフローを作成する際の条件として使用できます。例:動画名にXYZが含まれる動画にいいね!を付けたコンタクトすべてのリストを作成する(イベントトークン「video name」が設定されたイベントテンプレート「Video Like」を作成)
APIによるイベントテンプレートの作成
この例では、新しいイベントテンプレート「Example Webinar Registration」を作成します。認証には開発者APIキーを使用します。
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "Example event template",
"objectType": "contacts"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'
<<appId>>
は自分のアプリIDに置き換えてください。アプリIDは、開発者アカウントの自分のアプリのページまたはアプリ詳細ページで確認できます。また、<<developerHapikey>>
も自分の開発者APIキーに置き換える必要があります。APIキーは、[アプリ]>[HubSpot APIキーを取得]の順に進むことで確認できます。
ここでheaderTemplateとdetailTemplateのプロパティーも指定できます(下記の「テンプレートの定義」を参照)。
このPOST
リクエストは、保存されているイベントテンプレート定義全体を返します。レスポンス内にあるid
プロパティーに注目してください。これがイベントテンプレートIDで、今後このイベントテンプレートまたはトークンを更新する際に必要になります。
次のGETコマンドを使用すれば、アプリで定義されているすべてのイベントテンプレートを確認できます。この場合も、イベントテンプレートIDが返されます。
curl -X GET 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'
UIでのイベントテンプレートの作成
APIによるタイムライン イベント テンプレートの作成および管理に加えて、HubSpot開発者アカウントでイベントテンプレートを管理することもできます。
アプリの設定から[タイムラインイベント]に進み、[イベントタイプを作成]ボタンを使用してアプリ用の新しいイベントテンプレートを作成します。以前に作成したイベントテンプレートがある場合は、ここに表示されます。
新しいイベントテンプレートの下書きから始めます。イベントのオブジェクトタイプ、さらに詳細テンプレートとヘッダーテンプレートを設定したら、[作成]をクリックします。
イベントテンプレートの作成または編集を行う際には、使用するトークンを[データ]タブで設定します。
2. イベントトークンの定義
イベントテンプレートを定義したら、トークンも定義してみてください。イベント テンプレート トークンを使用することにより、カスタムデータをイベントに添付できます。カスタムデータは、タイムラインに表示したり、リストセグメンテーションに使用したりできます。1つのタイムライン イベント テンプレートにつき最大500件のトークンを作成できます。
APIによるイベントトークンの作成
ステップ1で作成したイベントテンプレートIDを使用して、コンタクトが登録しているウェビナーを特定するためのトークンを追加します。
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "webinarName",
"label": "Webinar Name",
"type": "string"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>'
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "webinarId",
"label": "Webinar Id",
"type": "string"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>'
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "webinarType",
"label": "Webinar Type",
"type": "enumeration",
"options": [
{
"value": "regular",
"label": "Regular"
},
{
"value": "ama",
"label": "Ask me anything"
}
]
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>'
同様に、GET
からはイベントテンプレートに定義されているすべてのトークンが返されます。
curl -X GET -H "Content-Type: application/json" 'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens?hapikey=<<developerHapikey>>'
対応しているトークンのタイプ:
string
number
enumeration
— 選択肢のセット。前述のwebinarTypeの例をご覧ください。date
— 日付には必ずミリ秒単位のUnix時刻を使用します。
注:イベントトークンにlogまたはlookupという名前を付けることはできません。これらのトークンは、Handlebars.js(アプリ内イベントのレンダリングに使用されるライブラリー)によるヘルパーとして予約済みです。詳細は、Handlebars.jsのドキュメント(こちら)を参照してください。
3. ヘッダーテンプレートおよび詳細テンプレートの定義
ヘッダーテンプレートと詳細テンプレートは、タイムラインイベントの表示方法を定義します。MarkdownドキュメントをHandlebarsテンプレートで指定できます。ヘッダーテンプレートはイベントについての1行の説明文で、詳細テンプレートはイベントに関する具体的な情報です。以下に例を示します。
イベントトークンは、データとしてテンプレートに渡されます。この例では、テンプレートの中でを使用することによって
webinarName
トークンを参照できます。
イベントのextraData
(後述の「extraDataについて」を参照)は、詳細テンプレートの中でのみ参照できます。
APIによるヘッダーテンプレートおよび詳細テンプレートの定義
ヘッダーテンプレートと詳細テンプレートは、イベント テンプレート エンドポイント経由でイベントテンプレートに定義できます。例えば、「Example Webinar Registration」の例では、PUT
を使用して変更を加えることにより、テンプレートを追加できます。
curl -X PUT -H "Content-Type: application/json" -d '
{
"id": "<<eventTemplateId>>",
"name": "Example Name Change",
"headerTemplate": "Registered for [{{webinarName}}](https://mywebinarsystem/webinar/{webinarId})",
"detailTemplate": "Registration occurred at {{#formatDate timestamp}}{{/formatDate}}"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>?hapikey=<<developerHapikey>>'
#formatDate
ディレクティブの使用にも注目してください。ユーザーにとって分かりやすい日付形式にするために定義しています。
このようにコンタクトに関するイベントを作成すると(後述のイベントの作成を参照)、コンタクトのタイムラインに次のように表示されます。
[詳細を表示]をクリックすると、詳細テンプレートが表示されます。
イベントの横に表示されるアイコンを設定するには、後述のカスタムアイコンの設定を参照してください。
ここでの「Example App Name」というテキストはアプリの名前です。CRMタイムライン内では、アプリ単位でイベントを絞り込むことができます。
4. 1回の呼び出しでイベントテンプレートのすべての要素を定義する
ここまではイベントテンプレートの各要素を紹介してきましたが、1回のPOST
呼び出しですべての要素を定義できます。
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "Another Webinar Registration",
"objectType": "contacts",
"headerTemplate": "Registered for [{{webinarName}}](https://mywebinarsystem/webinar/{webinarId})",
"detailTemplate": "Registration occurred at {{#formatDate timestamp}}{{/formatDate}}",
"tokens": [
{
"name": "webinarName",
"label": "Webinar Name",
"type": "string"
},
{
"name": "webinarId",
"label": "Webinar Id",
"type": "string"
},
{
"name": "webinarType",
"label": "Webinar Type",
"type": "enumeration",
"options": [
{
"value": "regular",
"label": "Regular"
},
{
"value": "ama",
"label": "Ask me anything"
}
]
}
]
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates?hapikey=<<developerAPIkey>>'
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <<OAuth2AccessToken>>" \
-d '
{
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
}' \
'https://api.hubapi.com/crm/v3/timeline/events'
これにより、a.test.contact@email.com
のタイムライン上にイベントが生成されます(前述の「テンプレートの定義」のテンプレートがある前提で)。
開発者APIキーは開発者アカウントからの設定専用であるため、イベントの作成には使用できません。イベントを作成するためには、HubSpotアカウントから貴社のアプリにOAuth(英語)経由でアクセス権限を付与してもらう必要があります。アクセストークン(英語)を入手したら、アクセストークンを使用してアカウントのコンタクトにイベントを追加できます。
イベントタイムスタンプの設定
イベントがオブジェクト内のタイムラインに現れる位置は、イベントのタイムスタンプによって決まります。イベントタイムスタンプには、既定でPOSTコマンドの送信時刻が設定されます。イベント時刻は、タイムスタンププロパティーのリクエスト本文に明示することによりカスタマイズできます。
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <<OAuth2AccessToken>>" \
-d '
{
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"timestamp": "2020-03-18T15:30:32Z",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
}' \
'https://api.hubapi.com/crm/v3/timeline/events'
特定のアクションが発生した正確な時刻が分かっている場合は、明示することが適切です。この例の場合、このウェビナー登録のタイムスタンプが分かっていればPOST内で指定してください。
タイムスタンプは、ミリ秒単位のエポック時間、またはISO 8601形式です。
6. イベントをCRMオブジェクトに関連付ける
イベントを作成するには、顧客のアカウント内のコンタクト、会社、または取引に対し、イベントを関連付けなければなりません。
前述の例では、objectTypeにコンタクトを指定し、Eメールを使用してイベントをコンタクトに関連付けました。HubSpot上ではコンタクトのEメールアドレスは重複しないため、指定されたEメールのコンタクトがすでに存在する場合、そのコンタクトが更新されることになります。しかし、既存のコンタクトがない場合は新しいコンタクトが作成されます。既定では、指定したEメール コンタクト プロパティーのみがこの新しいコンタクトに格納されます。コンタクトプロパティーに追加データを追加する方法については、後述のコンタクトプロパティーに対するイベントデータの付加に関する説明を参照してください。このサンプルデータでは、(前述の例と同様に)Eメールを使用します。
// {
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
}
既存のコンタクトの場合、イベントの関連付けにコンタクトのvid
を使用することもできます。その場合、リクエストJSONの中でobjectId
を使用します。これは既存のコンタクトのvidでなければならない点に注意してください。objectId
を使用してコンタクトを新規に作成することはできないためです。この例では、EメールではなくobjectId
を使用しています。
// {
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
}
ユーザートークンまたは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メールアドレスとユーザートークンを組み合わせています。
// {
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"utk": "89b5afb740d41f4cd6651ac5237edf09"
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
}
コンタクトだけでなく、会社や取引についてのイベントテンプレートも作成できます。その場合、イベントテンプレートにobjectId
を指定して、会社または取引にイベントを関連付ける必要があります。会社の場合、objectId
にイベントを関連付ける会社のcompanyId
を設定する必要があります。また、取引の場合、objectId
に取引オブジェクトのdealId
を設定します。
前述の例の場合、イベントテンプレートがCOMPANY
objectType
に設定されているとすると、このイベントはcompanyId
528253914の会社オブジェクトに関連付けられることになります。
// {
"eventTemplateId": "<<eventTemplateId>>",
"objectId": "3001",
"tokens": {
"dealProperty": "Custom property for deal"
}
}
7. タイムライン拡張機能
タイムライン拡張機能を使用すると、iFrameを使用して外部システムからデータを表示することが可能になり、イベントにはモーダルウィンドウを表示するリンクが表示されます。リンクをクリックすると、iFrameのコンテンツが表示されます。iFrameの詳細はtimelineIFrameフィールドに指定します。このオブジェクトには、次のフィールドがあります。
linkLabel
- IFrameを表示するリンクの表示に使用するテキスト。headerLabel
- IFrameコンテンツを表示するモーダルウィンドウのラベル。url
- IFrameコンテンツのURI。width
- モーダルウィンドウの幅。height
- モーダルウィンドウの高さ。
例えば、イベントに次のデータを使用した場合:
// {
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "A Test Webinar",
"webinarId": "001001",
"webinarType": "regular"
},
"timelineIFrame": {
"linkLabel":"View external data",
"headerLabel":"Example iframe",
"url":"https://www.example.com",
"width":800,
"height":300
}
}
「View external data」リンクを含む、次のイベントが作成されます。
このリンクをクリックするとモーダルウィンドウが表示され、url
に設定されているページが表示されます。
8. CRMオブジェクトのプロパティーに対するイベントデータの付加
イベントを追加するコンタクト、会社、取引のプロパティーに、変更が必要になるケースは少なくありません。特に、イベントを追加することでコンタクトが作成される場合が該当します。Eメールアドレスとイベントだけのコンタクトを作成しないためにも、コンタクトの姓名のプロパティーを更新する必要があるはずです。
カスタム イベント トークンをコンタクト、会社、または取引のプロパティーにマッピングすることにより、イベントからの関連オブジェクトのデータを付加することができます。
カスタム イベント テンプレートを更新するための次のPUT
の中で、objectPropertyName
フィールドに注目してください。
curl -X PUT -H "Content-Type: application/json" -d '
{
"label" : "Updated Webinar Name",
"objectPropertyName": "zz_webinar_name"
}' \
'https://api.hubapi.com/crm/v3/timeline/<<appId>>/event-templates/<<eventTemplateId>>/tokens/<<tokenName>>?hapikey=<<developerHapikey>>'
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
のプロパティーが設定されます。
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <<OAuth2AccessToken>>" \
-d '
{
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "Test Webinar will update contact property",
"companyName": "TestCo",
"webinarId": "001001",
"webinarType": "regular"
}
}' \
'https://api.hubapi.com/crm/v3/timeline/events'
注:イベントトークンがカスタムプロパティーに付加される際に該当するカスタムプロパティーがHubSpotアカウント上に存在しない場合、イベントには値が設定されますが、対応するオブジェクト側では無視されます。
9. extraData
について
イベント テンプレート トークンによって使用される「トークンと値」の単純な構造が適さない詳細なデータを、イベントに追加することが必要になるかもしれません。あるいは連携のイベントに、リストまたは階層状の内訳が必要になる場合も考えられます。こうした状況で役立つのがextraData
です。
extraData
属性をイベントのJSON本文に追加することができます。このextraData
の値として、任意の有効なJSONを指定できます。例:
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <<OAuth2AccessToken>>" \
-d '
{
"eventTemplateId": "<<eventTemplateId>>",
"email": "a.test.contact@email.com",
"tokens": {
"webinarName": "Test Webinar will update contact property",
"companyName": "TestCo",
"webinarId": "001001",
"webinarType": "regular"
},
"extraData": {
"pollData": [
{
"question": "How excited are you for this webinar?",
"answer":"Quite!"
},
{
"question": "How frequently do you use our product?",
"answer":"Daily"
}
],
"coWorkers": [
{
"name": "Joe Coworker",
"email":"joe.coworker@testco.com"
},
{
"name": "Jane Coworker",
"email":"jane.coworker@testco.com"
}
]
}
}' \
'https://api.hubapi.com/crm/v3/timeline/events'
詳細テンプレートでのextraData
の使用例:
//
Registration occurred at {{#formatDate timestamp}}{{/formatDate}}
#### アンケートの質問
{{#each extraData.pollData}}
**{{question}}**: {{answer}}
{{/each}}
#### 同僚
{{#each extraData.coWorkers}}
* {{name}}
{{/each}}
タイムラインイベントには次のように表示されます。
注:extraData
属性は、イベントの詳細テンプレート内でのみ参照できます。ヘッダーテンプレートやリストセグメンテーションの中では使用できません。
10. カスタムアイコンの設定
タイムライン上の項目に視覚的な効果を付けるために、必要に応じてカスタムアイコンを追加できます。
アイコンには、次のような画像ファイルを使用してください。
- ほぼ正方形に近い形
- 背景を透過にする
- コンテンツをアイコンの中央に配置する
- 30×30ピクセルまで縮小可能
- ファイルサイズが5MB以下
タイムラインイベントに使用するアイコンを設定するには、[タイムラインイベント]に進みます。プレースホルダー画像または既存のアイコンをクリックして、設定または変更します。
設定したアイコンは、アプリに関連するすべてのタイムラインイベントの横に表示されます。
関連ドキュメント
CRMカード(英語)