> ## 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.

# イベントオカレンスを送信する（ベータ版）

> HubSpotで、定義したイベント タイプ スキーマを使用してイベント オカレンス データを送信する方法を説明します。

[イベント タイプ スキーマを定義](en-us/apps/developer-platform/build-apps/features/app-events/create-and-manage-event-types)し、[そのfullyQualifiedNameを取得](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname)したら、アプリイベントAPIを使用してイベント オカレンス データを送信できます。イベントデータを送信する際には、事前に作成したスキーマに従う必要があります。スキーマに一致しないリクエストは検証に失敗し、アプリはこのリクエストをキャプチャーしません。

## イベントオカレンスの送信

<Tabs>
  <Tab title="1件のオカレンスを送信する">
    1件のイベントオカレンスを送信するには、`/integrators/timeline/v4/events`に対する`POST`リクエストを送信します。

    リクエスト本文で、イベントタイプの定義済みスキーマの後にイベントデータを含め、`eventTypeName`フィールドに`fullyQualifiedName`値を指定します。

    ```json theme={null}
    {
      "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
      "objectId": "123456",
      "id": "login-1",
      "properties": {
        "customerName": "Mark S.",
        "loginLocation": "mobileApp"
      }
    },
    ```
  </Tab>

  <Tab title="複数のオカレンスを一括送信する">
    複数のイベントオカレンスを一括送信するには、`/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": {}
        }
      ]
    }
    ```
  </Tab>
</Tabs>

<p className="table-key">
  <span style={{ color: 'red' }}>\*</span>でマークされたフィールドは必須です。
</p>

| フィールド                                                | 型      | 説明                                                                                                                                                                                                                                |
| ---------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventTypeName`<span style={{color:"red"}}>\*</span> | 文字列    | イベントタイプの完全修飾名。APIを使用してイベントを識別するときに使用します。この値はHubSpotによって自動設定され、イベントタイプの作成後に、[APIを使用して取得](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname)できます。この値を作成後に変更することはできません。 |
| `objectId`<span style={{color:"red"}}>\*</span>      | 文字列    | イベントオカレンスに関連付けるCRMレコードのID。このフィールドはあらゆるタイプのCRMレコードに使用でき、識別子として推奨されます。[CRMレコードの関連付け](#crm-record-association)について詳細をご確認ください。                                                                                                        |
| `email`                                              | 文字列    | コンタクトの関連付けの場合、関連付けるコンタクトのEメールアドレスを指定できます。[CRMレコードの関連付け](#crm-record-association)について詳細をご確認ください。                                                                                                                                   |
| `utk`                                                | 文字列    | コンタクトの関連付けの場合、関連付ける既存のコンタクトのユーザートークンを指定できます。[CRMレコードの関連付け](#crm-record-association)について詳細をご確認ください。                                                                                                                                |
| `domain`                                             | 文字列    | 会社の`domain`プロパティー値を設定するときに、`objectId`に加えてこのフィールドを含めます。[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`                                          | オブジェクト | [タイムライン表示テンプレート](/apps/developer-platform/add-features/app-events/reference#rendering-templates)で使用できる追加情報。有効なJSON形式である必要があります。                                                                                                   |
| `timelineIFrame`                                     | オブジェクト | このフィールドが含まれている場合、ユーザーがリンク先のコンテンツをiframeで表示できるハイパーリンクがタイムラインカードに組み込まれます。[iframeの使用](/apps/developer-platform/add-features/app-events/reference#using-iframes)についての詳細をご確認ください。                                                      |
| `id`                                                 | 文字列    | イベントオカレンスの固有ID。イベントタイプ内で重複しないようにする必要があります。指定しない場合、HubSpotによりランダムなUUIDが生成されます。複数のイベントのIDが同一である場合、最初のイベントのIDが受け入れられ、その他は全て拒否されます。                                                                                                   |

## CRMレコードの関連付け

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

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

以下に、CRMレコードの関連付けプロパティーの優先順位を示します。最も小さい数値が最も高い優先順位となります。

| フィールド      | 優先順位 | 説明                       |
| ---------- | ---- | ------------------------ |
| `objectId` | 1    | CRMレコードID（推奨）。           |
| `utk`      | 2    | コンタクトのユーザートークン（コンタクトのみ）。 |
| `email`    | 3    | コンタクトのEメールアドレス（コンタクトのみ）。 |
| `domain`   | 4    | 会社ドメイン（会社のみ）。            |

## 追加データの送信

[イベントプロパティー](/apps/developer-platform/add-features/app-events/reference#event-properties)へのデータの送信と[イベントオカレンスによるCRMプロパティーの更新](/apps/developer-platform/add-features/app-events/reference#property-stamping)の他に、`extraData`オブジェクトを使用して[タイムライン表示](/apps/developer-platform/add-features/app-events/reference#rendering-templates)のための追加データを含めることができます。

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

イベントタイプの`detailTemplate`では、`{{extraData.fieldName}}`構文を使用して`extraData`フィールドの値にアクセスできます。`extraData`の全ての属性レベルは、`{{extraData.person1.preferredName}}`などのドット表記形式で指定できます。

例えば以下のテンプレートでは、`customerName`プロパティーと`loginLocation`プロパティーのデータと、[イベントオカレンスにより送信された](#event-occurrences)`extraData`の`surveyData`フィールドが使用されています。

![コンタクトタイムラインに表示テンプレートの例がどのように表示されるかを示すスクリーンショット。](https://www.hubspot.com/hubfs/Knowledge_Base_Images/CRM/Contacts/example-timeline-event-rendering-template.png)

<Tabs>
  <Tab title="イベント オカレンス データ">
    ```json theme={null}
    {
      "eventTemplateId": "5488733",
      "objectId": "769851",
      "tokens": {
        "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"
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="タイムラインテンプレートの設定">
    ```json theme={null}
    "headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
    "detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",
    ```
  </Tab>
</Tabs>