アプリイベントのリファレンス（ベータ版）

最終更新日: 2025年9月11日

以下でイベントタイプのスキーマ、イベントタイムライン表示テンプレート、イベントオカレンスのフィールドなど、アプリイベントの使用に関する参照情報を紹介します。

プロジェクトの構成

プロジェクトのコンテキストで、イベントタイプの定義をapp/内のapp-eventsディレクトリーに配置します。app-eventsディレクトリーには、各イベントタイプのJSONスキーマ定義ファイル（*-hsmeta.json）が含まれている必要があります。

project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json

イベントタイプの定義をプロジェクトに含めるための要件を以下に示します。

アプリがOAuth認証を使用しており、アプリマーケットプレイスでの配布用に設定されている必要があります。また、アプリのrequiredScopesにtimelineが含まれている必要があります。アプリの設定についての詳細をご確認ください。
アプリイベントコンポーネントを含めるには、その前にプロジェクトが正常にデプロイされている必要があります。

イベントタイプスキーマ

イベントタイプスキーマで使用できる設定オプションを以下に示します（*-hsmeta.json）。以下の属性の一部は、イベントタイプが作成された後に変更することはできません。

各アプリで使用できるイベントタイプは750個に制限されています。

{
 "uid": "customer_login_event",
 "type": "app-event",
 "config": {
   "name": "Customer login",
   "headerTemplate": "{{customerName}} logged in.",
   "detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
   "objectType": "CONTACT",
   "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]
 }
}

*でマークされたフィールドは必須です。

フィールド	型	説明
`uid`*	文字列	イベントタイプの内部固有ID。
`type`*	文字列	コンポーネントのタイプ。`app-event`でなければなりません。
`name`*	文字列	HubSpotに表示されるラベル（最大50文字）。この値を作成後に更新することはできません。
`objectType`*	文字列	イベントオカレンスを関連付けることができるCRMオブジェクトタイプの完全修飾名。この値を作成後に変更することはできません。`COMPANY`、`CONTACT`、`CUSTOM_OBJECT`、`DEAL`、`TICKET`、`APP_OBJECT`のいずれかを指定できます。
`headerTemplate`	文字列	CRMタイムラインアクティビティーカードのヘッダーの表示テンプレート。使用できる文字数は最大1,000文字です。
`detailTemplate`	文字列	CRMタイムラインアクティビティーカードの本文の表示テンプレート。使用できる文字数は最大10,000文字です。
`properties`	配列	イベントオカレンスデータを格納する、イベントタイプ用に定義されたプロパティー。イベントタイプごとに最大500個のプロパティーを設定できます。イベントプロパティーの詳細については、以下をご確認ください。

イベントプロパティー

イベントスキーマを定義するときには、properties配列を使用して、イベントオカレンスデータの送信先フィールドを定義します。イベントタイプごとに最大500個のプロパティーを設定できます。

 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string"
     },
     {
       "name": "loginLocation",
       "label": "Login location",
       "type": "enumeration",
       "options": [
         {
           "value": "mobileApp",
           "label": "Mobile app"
         },
         {
           "value": "website",
           "label": "Website"
         }
       ]
     }
   ]

*でマークされたフィールドは必須です。

フィールド	型	説明
`name`*	文字列	プロパティーの内部名。小文字で1～500文字にする必要があります。プロパティーはイベントタイプで重複しない名前にする必要がありますこの値は正規表現`"[A-Za-z0-9_\\-.]+"`と一致させることはできません。また`hs_`で始まる値にはできません。
`label`*	文字列	HubSpotに表示されるラベル。小文字で1～500文字にする必要があります。
`type`*	文字列	プロパティーで取得されるデータのタイプ。`STRING`、`NUMBER`、`DATE`、`ENUMERATION`のいずれかを指定できます。
`options`	配列	`ENUMERATION`タイプのプロパティーの場合、このフィールドは使用可能なオプションを示します。1つ以上のオプションを含める必要があります。各オプションは、以下を含むオブジェクトです。 `name`：HubSpotに表示されるオプションのラベル。 `value`：イベントオカレンスによって提供される内部値 `name`と`label`はイベントタイプ内で重複しないものである必要があります。
`objectPropertyName`	文字列	このフィールドが含まれている場合、イベントデータがHubSpotに送信される時点で更新されるCRMオブジェクトのプロパティーの名前です。このプロパティーの値によって、そのプロパティーの既存の値が上書きされます。CRMレコードのプロパティーにデータを付加する方法については、以下をご覧ください。

プロパティーへのデータの付加

場合によっては、アプリイベントオカレンスデータに基づいてCRMレコードのプロパティー値を変更することがあります。例えば、コンタクトの姓名を、オカレンス（例：フォーム送信）によって設定された新しい値に更新することがあります。イベントオカレンスによってCRMレコードプロパティーを更新するには、イベントプロパティーをイベントタイプスキーマ内のCRMプロパティーにリンクします。特定のイベントプロパティーの定義フィールドに、objectPropertyNameフィールドを含め、リンクするCRMプロパティーを指定します。プロパティーがリンクされると、HubSpotは常にtimestampフィールドに基づく最新のオカレンスの値を使用して、CRMレコードのプロパティー値を更新します。例えば以下のイベントタイプスキーマは、イベントプロパティーcustomerNameをカスタムコンタクトプロパティーcustom_property_nameにリンクします。イベントオカレンスデータにcustomerNameの値が含まれている場合、関連付けられているCRMレコードのcustom_property_nameが更新されます。

 "properties": [
     {
       "name": "customerName",
       "label": "Customer Name",
       "type": "string",
       "objectPropertyName": "custom_property_name"
     }
   ]

表示テンプレート

イベントタイプスキーマにはheaderTemplateフィールドとdetailTemplateフィールドを含めることができます。これらのフィールドにより、イベントオカレンスがCRMレコードタイムラインにどのように表示されるかを設定できます。

headerTemplate：アクティビティーカードの上部に、イベントに関する1行の説明（最大1,000文字）として表示する。
detailTemplate：アクティビティカードの本文に、イベントの詳細（最大10,000文字）として表示する。

表示テンプレートは、MarkdownとHandlebarsテンプレートを使用して作成されています。これらのテンプレートは、イベントオカレンスデータを次のように表示できます。

どちらのテンプレートでも、構文{{propertyName}}を使用して、イベントオカレンスによって渡されるpropertyデータにアクセスできます。
detailTemplateでは、構文{{extraData.fieldName}}を使用して、イベントオカレンスによって渡されるextraData値にもアクセスできます。ドット表記（例：{{extraData.person1.preferredName}}）を使用して、extraDataの任意の属性ティアにアクセスできます。

extraDataオブジェクトには有効なJSONのみを含めることができます。JSONの形式が正しくない場合、オカレンスは却下され、エラーレスポンスが返されます。

例えば以下のテンプレートでは、customerNameプロパティーとloginLocationプロパティーのデータと、イベントオカレンスにより送信されたextraDataのsurveyDataフィールドが使用されています。コンタクトタイムラインに表示テンプレートの例がどのように表示されるかを示すスクリーンショット。

コンタクトタイムラインに表示テンプレートの例がどのように表示されるかを示すスクリーンショット。

"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",

テンプレートはMarkdownとHandlebarsを使用して作成されるため、Handlebarsヘルパーを利用してコンテンツをより動的にできます。例えば次のdetailTemplateには、イベントオカレンスデータのextraDataにsurveyDataフィールドが含まれているかどうかに基づいて、コンテンツを条件付きで表示する#ifヘルパーが含まれています。

extraDataにsurveyDataが含まれている場合は、ログイン後のアンケートの回答が表示されます。
イベントオカレンスにsurveyDataがない場合は、No additional information.が表示されます。

コンタクトタイムラインに以下のサンプルコードががどのように表示されるかを示すスクリーンショット。

"detailTemplate": "{{#if extraData.surveyData}}#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}{{else}}No additional information."

iframeの使用

イベントオカレンスデータにtimelineIFrameフィールドが含まれている場合、タイムラインアクティビティーカードには、ユーザーがリンク先のコンテンツをiframeで表示できるハイパーリンクが含まれます。 timelineIFrameフィールドによってタイムラインアクティビティーカードに含まれるリンクのスクリーンショット

timelineIFrameフィールドによってタイムラインアクティビティーカードに含まれるリンクのスクリーンショット

"timelineIFrame": {
    "linkLabel": "Click me",
    "headerLabel": "This is an iframe",
    "url": "https://hubspot.mintlify.io/en-us/apps/developer-platform/build-apps/overview",
    "width": 300,
    "height": 300
  }

フィールド	型	説明
`linkLabel`	文字列	クリックするとiframeが表示されるハイパーリンクテキスト。
`headerLabel`	文字列	iframeコンテンツを表示するモーダルウィンドウのラベル。
`url`	文字列	iframeコンテンツのURL。
`width`	整数	iframeモーダルの幅。
`height`	整数	iframeモーダルの高さ。

イベントオカレンス

特定のイベントタイプのイベントオカレンスを送信するには、以下のエンドポイントに対するPOSTリクエストを送信します。アプリイベントAPIには、1件のイベントオカレンスを送信するためのエンドポイントと、複数のイベントオカレンスを一括送信するためのエンドポイントが含まれています。どちらのエンドポイントでも、イベントオカレンスデータを既存のイベントタイプスキーマに照らして検証する必要があります。これはリクエスト本文のeventTypeNameで指定します。

1件のイベントオカレンスを送信するには、/integrators/timeline/v4/eventsに対するPOSTリクエストを送信します。リクエスト本文に、イベントタイプの定義済みスキーマに従ってイベントオカレンスデータを含めます。

{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

リクエスト本文に、定義されているイベントタイプスキーマに基づくデータを含めます。リクエスト本文にeventTypeNameを含める必要があります。これは、APIを使用して取得できます。

  {
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "8675309",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  },
  "id": "login-1529a3gda23",
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer":"Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer":"Extremely likely"
      }
    ]
  }
}

*でマークされたフィールドは必須です。

フィールド	型	説明
`eventTypeName`*	文字列	イベントタイプの完全修飾名。APIを使用してイベントを識別するときに使用します。この値はHubSpotによって自動設定され、イベントタイプの作成後に、APIを使用して取得できます。この値を作成後に変更することはできません。
`objectId`*	文字列	イベントオカレンスに関連付けるCRMレコードのID。このフィールドはあらゆるタイプのCRMレコードに使用でき、識別子として推奨されます。CRMレコードの関連付けについて詳細をご確認ください。
`email`	文字列	コンタクトの関連付けの場合、関連付けるコンタクトのEメールアドレスを指定できます。CRMレコードの関連付けについて詳細をご確認ください。
`utk`	文字列	コンタクトの関連付けの場合、関連付ける既存のコンタクトのユーザートークンを指定できます。CRMレコードの関連付けについて詳細をご確認ください。
`domain`	文字列	会社の関連付けの場合、関連付ける既存の会社のウェブサイトのドメインを指定できます。CRMレコードの関連付けについて詳細をご確認ください。
`timestamp`	文字列	イベントオカレンスの時刻（ISO 8601形式）を設定します。指定しない場合、既定でイベントオカレンスデータの送信時刻のタイムスタンプに設定されます。
`properties`	オブジェクト	イベントタイプで定義したプロパティーのプロパティー名と値のキーと値のペア。
`extraData`	配列	このフィールドが含まれている場合、タイムライン表示に関する追加情報を示します。有効なJSONである必要があります。表示テンプレートの追加データの詳細をご確認ください。
`timelineIFrame`	オブジェクト	このフィールドが含まれている場合、ユーザーがリンク先のコンテンツをiframeで表示できるハイパーリンクがタイムラインカードに組み込まれます。iframeの使用についての詳細をご確認ください。
`id`	文字列	イベントオカレンスの固有ID。イベントタイプ内で重複しないようにする必要があります。指定しない場合、HubSpotによりランダムなUUIDが生成されます。複数のイベントのIDが同一である場合、最初のイベントのIDが受け入れられ、その他は全て拒否されます。

検証に失敗したオカレンスがある場合でも、正常に検証されたオカレンスは引き続き受け入れられ、保持されます。レスポンスに含まれるエラーメッセージには、修正が必要な内容に関する情報が記述されます。イベントオカレンスデータの送信時に表示されるエラーメッセージの例のスクリーンショット

イベントオカレンスデータの送信時に表示されるエラーメッセージの例のスクリーンショット

CRMレコードの関連付け

各イベントオカレンスは、イベントタイプスキーマで定義されたCRMオブジェクトタイプを持つCRMレコードに関連付けられている必要があります。アプリイベントAPIには、イベントオカレンスデータをCRMレコードに関連付けるための複数のフィールドがあります。サポートされている全てのCRMオブジェクトでは、objectIdフィールドを使用することをお勧めします。ただし、場合によっては他のフィールドを使用することがあります。

utk/email：コンタクトのIDが不明な場合は、識別にutkフィールドとemailフィールドのいずれかまたは両方を使用します。両方の識別子を指定すると、コンタクトを作成および更新することもできます。以下に例を示します。
- utkが既存のコンタクトに一致してもemailが一致しない場合、HubSpotは新しいEメールアドレスでコンタクトを更新します。
- objectIdが指定されていない場合、イベントオカレンスはutk/emailに一致する既存のコンタクトに関連付けられ、一致するコンタクトが見つからない場合はHubSpotによって新しいコンタクトが作成されます。
- utkのみでは新しいコンタクトレコードを作成できないことにご注意ください。適切な関連付けを確保するために、常にutkとemailを含める必要があります。
domain：会社の関連付けの場合、objectIdを指定する必要があります。また、会社のdomainプロパティーを更新するためにdomainを含めることもできます。

アプリを作成

機能を追加

アプリマーケットプレイスに公開

アプリイベントのリファレンス（ベータ版）

プロジェクトの構成

イベントタイプスキーマ

イベントプロパティー

プロパティーへのデータの付加

表示テンプレート

iframeの使用

イベントオカレンス

CRMレコードの関連付け

アプリを作成

機能を追加

アプリマーケットプレイスに公開

​プロジェクトの構成

​イベント タイプ スキーマ

​イベントプロパティー

​プロパティーへのデータの付加

​表示テンプレート

​iframeの使用

​イベントオカレンス

​CRMレコードの関連付け

プロジェクトの構成

イベントタイプスキーマ

イベントプロパティー

プロパティーへのデータの付加

表示テンプレート

iframeの使用

イベントオカレンス

CRMレコードの関連付け