> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# アプリイベントのリファレンス（ベータ版）
> 最新バージョンの開発者プラットフォームのアプリイベントに関する参照情報。
以下でイベントタイプのスキーマ、イベントタイムライン表示テンプレート、イベントオカレンスのフィールドなど、アプリイベントの使用に関する参照情報を紹介します。
## プロジェクトの構成
プロジェクトのコンテキストで、イベントタイプの定義を`app/`内の`app-events`ディレクトリーに配置します。`app-events`ディレクトリーには、各イベントタイプのJSONスキーマ定義ファイル（`*-hsmeta.json`）が含まれている必要があります。
```shell theme={null}
project-folder/
└── src/
└── app/
├── app-hsmeta.json
└── app-events/
└── my-event-type-hsmeta.json
```
イベントタイプの定義をプロジェクトに含めるための要件を以下に示します。
* アプリがOAuth認証を使用しており、アプリマーケットプレイスでの配布用に設定されている必要があります。また、アプリの`requiredScopes`に`timeline`が含まれている必要があります。[アプリの設定](/apps/developer-platform/build-apps/app-configuration)についての詳細をご確認ください。
* アプリ イベント コンポーネントを含めるには、その前にプロジェクトが正常にデプロイされている必要があります。
## イベント タイプ スキーマ
イベント タイプ スキーマで使用できる設定オプションを以下に示します（`*-hsmeta.json`）。以下の属性の一部は、イベントタイプが作成された後に変更することはできません。
各アプリで使用できるイベントタイプは750個に制限されています。
```json theme={null}
{
"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タイムライン アクティビティー カードのヘッダーの[表示テンプレート](#rendering-templates)。使用できる文字数は最大1,000文字です。 |
| `detailTemplate` | 文字列 | CRMタイムライン アクティビティー カードの本文の[表示テンプレート](#rendering-templates)。使用できる文字数は最大10,000文字です。 |
| `properties` | 配列 | イベント オカレンス データを格納する、イベントタイプ用に定義されたプロパティー。イベントタイプごとに最大500個のプロパティーを設定できます。イベントプロパティーの詳細については、以下をご確認ください。 |
### イベントプロパティー
イベントスキーマを定義するときには、`properties`配列を使用して、イベント オカレンス データの送信先フィールドを定義します。イベントタイプごとに最大500個のプロパティーを設定できます。
```json theme={null}
"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`が更新されます。
```json theme={null}
"properties": [
{
"name": "customerName",
"label": "Customer Name",
"type": "string",
"objectPropertyName": "custom_property_name"
}
]
```
### 表示テンプレート
イベント タイプ スキーマには`headerTemplate`フィールドと`detailTemplate`フィールドを含めることができます。これらのフィールドにより、イベントオカレンスがCRMレコードタイムラインにどのように表示されるかを設定できます。
* `headerTemplate`：アクティビティーカードの上部に、イベントに関する1行の説明（最大1,000文字）として表示する。
* `detailTemplate`：アクティビティカードの本文に、イベントの詳細（最大10,000文字）として表示する。
表示テンプレートは、[Markdown](https://www.markdownguide.org/basic-syntax/)と[Handlebars](https://handlebarsjs.com/guide/)テンプレートを使用して作成されています。これらのテンプレートは、イベント オカレンス データを次のように表示できます。
* どちらのテンプレートでも、構文`{{propertyName}}`を使用して、イベントオカレンスによって渡される`property`データにアクセスできます。
* `detailTemplate`では、構文`{{extraData.fieldName}}`を使用して、イベントオカレンスによって渡される`extraData`値にもアクセスできます。ドット表記（例：`{{extraData.person1.preferredName}}`）を使用して、`extraData`の任意の属性ティアにアクセスできます。
`extraData`オブジェクトには有効なJSONのみを含めることができます。JSONの形式が正しくない場合、オカレンスは却下され、エラーレスポンスが返されます。
例えば以下のテンプレートでは、`customerName`プロパティーと`loginLocation`プロパティーのデータと、[イベントオカレンスにより送信された](#event-occurrences)`extraData`の`surveyData`フィールドが使用されています。
```json theme={null}
"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`ヘルパー](https://handlebarsjs.com/guide/builtin-helpers.html#if)が含まれています。
* `extraData`に`surveyData`が含まれている場合は、ログイン後のアンケートの回答が表示されます。
* イベントオカレンスに`surveyData`がない場合は、`No additional information.`が表示されます。
```json theme={null}
"detailTemplate": "{{#if extraData.surveyData}}#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}{{else}}No additional information."
```
### iframeの使用
イベント オカレンス データに`timelineIFrame`フィールドが含まれている場合、タイムライン アクティビティー カードには、ユーザーがリンク先のコンテンツをiframeで表示できるハイパーリンクが含まれます。
```json theme={null}
"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`リクエストを送信します。
リクエスト本文に、イベントタイプの定義済みスキーマに従ってイベント オカレンス データを含めます。
```json theme={null}
{
"eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
"objectId": "123456",
"id": "login-1",
"properties": {
"customerName": "Mark S.",
"loginLocation": "mobileApp"
}
},
```
複数のイベントオカレンスを一括送信するには、`/integrators/timeline/v4/events/batch`に対する`POST`リクエストを送信します。
リクエスト本文の`inputs`配列に、カンマ区切りのイベント オカレンス オブジェクトを最大500個まで含めます。検証に失敗したオカレンスがある場合でも、正常に検証されたオカレンスは引き続き受け入れられ、保持されます。
```json theme={null}
{
"inputs": [
{
"EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
"id": "login_event_100",
"objectId": "769851",
"properties": {
"customerName": "Tim",
"loginLocation": "mobileApp"
},
"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": "ae000000_integrators-timeline-event-type-id-0000000",
"id": "login_event_101",
"objectId": "769851",
"properties": {
"customerName": "Tim",
"loginLocation": "website"
},
"extraData": {}
}
]
}
```
リクエスト本文に、定義されているイベント タイプ スキーマに基づくデータを含めます。リクエスト本文に`eventTypeName`を含める必要があります。これは、[APIを使用して取得](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname)できます。
```json theme={null}
{
"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を使用して取得](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname)できます。この値を作成後に変更することはできません。 |
| `objectId`\* | 文字列 | イベントオカレンスに関連付けるCRMレコードのID。このフィールドはあらゆるタイプのCRMレコードに使用でき、識別子として推奨されます。[CRMレコードの関連付け](#crm-record-association)について詳細をご確認ください。 |
| `email` | 文字列 | コンタクトの関連付けの場合、関連付けるコンタクトのEメールアドレスを指定できます。[CRMレコードの関連付け](#crm-record-association)について詳細をご確認ください。 |
| `utk` | 文字列 | コンタクトの関連付けの場合、関連付ける既存のコンタクトのユーザートークンを指定できます。[CRMレコードの関連付け](#crm-record-association)について詳細をご確認ください。 |
| `domain` | 文字列 | 会社の関連付けの場合、関連付ける既存の会社のウェブサイトのドメインを指定できます。[CRMレコードの関連付け](#crm-record-association)について詳細をご確認ください。 |
| `timestamp` | 文字列 | イベントオカレンスの時刻（[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)形式）を設定します。指定しない場合、既定でイベント オカレンス データの送信時刻のタイムスタンプに設定されます。 |
| `properties` | オブジェクト | イベントタイプで定義した[プロパティー](/apps/developer-platform/add-features/app-events/reference#event-properties)のプロパティー名と値のキーと値のペア。 |
| `extraData` | 配列 | このフィールドが含まれている場合、タイムライン表示に関する追加情報を示します。有効なJSONである必要があります。[表示テンプレートの追加データ](#rendering-templates)の詳細をご確認ください。 |
| `timelineIFrame` | オブジェクト | このフィールドが含まれている場合、ユーザーがリンク先のコンテンツをiframeで表示できるハイパーリンクがタイムラインカードに組み込まれます。[iframeの使用](#using-iframes)についての詳細をご確認ください。 |
| `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`を含めることもできます。