> ## 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に送信できます。アプリ イベント データはCRMレコードに関連付けられるため、HubSpotのオートメーションツール、アナリティクスツール、レポートツールで使用できます。

アプリイベントの仕組みについては、以下のセクションで詳しく説明します。アプリイベントをプロジェクトに組み込むには、まず、次のようにします。

* [イベントタイプを作成する](/apps/developer-platform/add-features/app-events/create-and-manage-event-types)
* [イベント オカレンス データを送信する](/apps/developer-platform/add-features/app-events/send-event-occurrences)
* [アプリイベントのリファレンスドキュメント](/apps/developer-platform/add-features/app-events/reference)を確認する

<Warning>
  このドキュメントで説明するアプリイベントは、開発者プロジェクトを使用して[アプリマーケットプレイス](https://ecosystem.hubspot.com/marketplace/apps)向けに開発されたアプリを対象としています。他のタイプの連携を対象にカスタム イベント レポートを作成するには、代わりに[カスタムイベント](/api-reference/events-manage-event-definitions-v3/guide)を使用してください。
</Warning>

## アプリイベントの仕組み

イベントとは、特定の時点で発生した事象を捕捉するデータポイントを指します。イベントは多くの場合、フォームの送信、SMSメッセージの送信、ページの閲覧といったユーザーのアクションに関係するものです。CRMレコードはエンティティーの現在の状態を明らかにすることを目的としていますが、イベントはそれとは異なり、アクティビティーのパターン、経時的な行動の変化や、その他の傾向について理解を深めるために使用できます。

<Tip>
  次のようなデータについては、アプリイベントが非常に役立ちます。

  * 繰り返し発生するアクションまたはアクティビティーを表すデータ。
  * 経時的な変化や量を分析する必要があるデータ。
  * 作成後に更新する必要がないデータ。
</Tip>

大まかには、アプリイベントは以下の要素からなります。

* **イベントタイプの定義**: イベントの構造、プロパティー、検証ルールを定義するJSONスキーマ。このスキーマは、イベント名、表示ラベル、ターゲットCRMオブジェクト、イベントプロパティーからなります。また、イベントタイプにはCRMレコードのタイムラインをレンダリングするための表示テンプレートの定義も含めます。イベントタイプは、開発者プロジェクトを使用して定義します。
* **イベントオカレンス**: 実際のデータを格納し、イベント タイプ スキーマに照らし合わせて検証される、個々のイベントインスタンス。イベント オカレンス データはアプリイベントAPIを介して送信されます。このデータには、イベントタイプ識別子、プロパティー値、タイムスタンプとその他のメタデータ、ならびにCRMレコードの関連付けに関するCRMオブジェクト参照データが含まれます。

<Note>
  **タイムラインイベントとアプリイベントの違い**

  HubSpotでは以前、CRMオブジェクトのタイムラインにイベントデータを表示できるように、タイムラインイベントをリリースしていました。アプリイベントは、拡大されたサポート対象オブジェクト全体でタイムラインイベントと同じ機能を果たせるだけでなく、HubSpotの他のツールでも利用できます。アプリイベントでも、カスタムイベントを使用できるようになったとともに、固有のインデックスページが設定され、イベントアクティビティーを一元的に把握できるようになりました。

  既存のタイムラインイベント連携も引き続き機能し、アプリイベントと同じ場所に表示されます。ただし、新しいイベントタイプを作成する場合や、既存のタイプに変更を加える場合には、開発者プロジェクトでアプリイベントとして作成／再作成する必要があります。
</Note>

## サポート対象のオブジェクトとツール

イベントタイプを定義する際は、イベントデータをそのソース（ウェブサイトにログインしたコンタクトなど）に結び付けられるように、イベントタイプを特定のCRMオブジェクトと関連付けて設定します。これにより、イベントオカレンスが該当するタイプのCRMレコードに関連付けられるようになります。アプリイベントには、以下のCRMオブジェクトを関連付けることができます。

* コンタクト
* 会社
* 取引
* チケット
* カスタムオブジェクト
* アプリオブジェクト

アプリイベントは、以下のHubSpotツールで使用できます。

* **イベント管理インターフェース**: アカウントで［データ管理］\*\*\*\*＞［カスタムイベント］\*\*\*\*に移動すると、カスタム イベント ダッシュボードでカスタム イベント データと併せてアプリ イベント データを確認し、分析できます。
* **CRMレコードのタイムライン**: イベントオカレンスに関連付けられているCRMレコードのタイムラインで、アプリ イベント アクティビティーを時系列で確認できます。
* **レポートツール**: 分析と可視化を目的に、アプリ イベント データを使用してカスタムレポート、カスタマー ジャーニー アナリティクス、データセットを作成できます。
* **リードスコア、リスト、ワークフロー**: 動的リスト、リードスコアリング、ワークフローのトリガーを目的に、イベントを使用してCRMデータベースをセグメント化できます。

## ベストプラクティス

イベントタイプを作成する際のベストプラクティスは以下のとおりです。

* [イベントタイプ](/apps/developer-platform/add-features/app-events/reference#event-type-schema)と[プロパティー](/apps/developer-platform/add-features/app-events/reference#event-properties)は、ワークフロー、リスト、レポート、カスタム イベント ダッシュボードでフィルターとして表示されるため、明確で分かりやすい名前にします。
* データに一致し、正確な適切なフィルタリングおよび分析を可能にする、適切なプロパティータイプ（文字列、数値、日時など）を選択します。
* セグメンテーション、レポート作成、自動化トリガーに役立つプロパティー（取引金額、ユーザーロール、アクションカテゴリーなど）を含めます。
* レポート作成やワークフローのユースケースを念頭に、ユーザーがイベントデータを絞り込んでグループ化する方法を考慮してイベントタイプを設計します。
* イベント構造に依存する既存のワークフローやレポートが中断される可能性があるため、既存のイベント タイプ スキーマには破損につながるような変更を加えないようにします。

高品質のイベントデータを維持するには、次のようにします。

* プログラムによるイベント オカレンス データ リクエストをレビューして、イベント タイプ スキーマに照らし合わせて適切に検証されることを確認します。
* イベントのプロパティー値（特に日付、数値、カテゴリーデータ）には一貫した書式設定を使用します。
* イベントオカレンスが[有効なCRMレコードID](/apps/developer-platform/add-features/app-events/send-event-occurrences#crm-record-association)に関連付けられるようにします。
* イベント送信の成功率と[エラーレスポンス](/apps/developer-platform/add-features/app-events/reference#occurrence-send-errors)をモニタリングします。
* CRMレコードのタイムラインとカスタム イベント ダッシュボードで、イベントデータが正確であることを定期的に確認します。

イベント送信のパフォーマンスを最適化するには、次の方法があります。

* 可能な場合は、1つのAPIリクエストで[複数のイベントオカレンスを一括処理](/apps/developer-platform/add-features/app-events/send-event-occurrences#sending-event-occurrences)します（バッチあたり最大500件）。
* イベントオカレンスのペイロードの無駄をなくすために、必要なプロパティーデータのみを含めます。
* 失敗したイベント送信に対してエクスポネンシャルバックオフ方式の再試行ロジックを実装します。

## 制限事項

アプリイベントを計画および作成する際は、次の制限事項にご注意ください。

### バージョンの要件

* アプリイベントは、最新バージョンの開発者プロジェクトプラットフォーム（`2025.2`）でのみ作成できます。
* 既存のイベントタイプについては、引き続き[v1](/api-reference/legacy/crm-timeline-v1/get-integrations-v1-application-id-timeline-event-event-typeid-event-id)および[v3のタイムラインイベントAPI](/api-reference/crm-timeline-v3/guide)を使用できます。ただし、`v1`および`v3`のAPIを使用して新しいイベントタイプを作成することはできません。

### イベントタイプに関する制約

* イベントオカレンスは、定義されたイベントタイプのスキーマに準拠している必要があります。そうでない場合は拒否されます。
* 一部の[イベントタイプのフィールド](/apps/developer-platform/add-features/app-events/reference#event-type-schema)は、イベントタイプが作成された後に更新することはできません（`name`、`objectType`など）。
* 新しいイベントタイプは、審査プロセスを経てからでないと有効化できません。

### データの制限

* 個々のプロパティーは最大510KBに制限され、イベントの合計サイズには1MBの上限が適用されます。
* アプリイベントはアプリマーケットプレイスのプロバイダーを対象としており、OAuth認証を使用するように設定されているアプリでのみ機能します。内部システムでは、代わりに[カスタムイベント](/api-reference/events-manage-event-definitions-v3/guide.mdx)を使用する必要があります。

## 使用の開始

アプリイベントの使用を開始するには、次のことを行う必要があります。

* 開発者プロジェクトを使用して、イベントデータの構造を定義する[イベントタイプを作成](/apps/developer-platform/add-features/app-events/create-and-manage-event-types)します。
* [アプリイベントAPI]()を使用して、[イベント オカレンス データをアプリに送信](/apps/developer-platform/add-features/app-events/send-event-occurrences#send-a-single-occurrence)します。
* HubSpotのレポートツール、オートメーションツール、またはアナリティクスツールで、必要に応じてデータを活用します。