最終更新日: 2025年10月10日
アプリイベントを使用すると、外部システムで拡充されたアクティビティーデータを直接HubSpotに送信できます。アプリ イベント データはCRMレコードに関連付けられるため、HubSpotのオートメーションツール、アナリティクスツール、レポートツールで使用できます。
アプリイベントの仕組みについては、以下のセクションで詳しく説明します。アプリイベントをプロジェクトに組み込むには、まず、次のようにします。
このドキュメントで説明するアプリイベントは、開発者プロジェクトを使用してアプリマーケットプレイス向けに開発されたアプリを対象としています。他のタイプの連携を対象にカスタム イベント レポートを作成するには、代わりにカスタムイベントを使用してください。
アプリイベントの仕組み
イベントとは、特定の時点で発生した事象を捕捉するデータポイントを指します。イベントは多くの場合、フォームの送信、SMSメッセージの送信、ページの閲覧といったユーザーのアクションに関係するものです。CRMレコードはエンティティーの現在の状態を明らかにすることを目的としていますが、イベントはそれとは異なり、アクティビティーのパターン、経時的な行動の変化や、その他の傾向について理解を深めるために使用できます。次のようなデータについては、アプリイベントが非常に役立ちます。
- 繰り返し発生するアクションまたはアクティビティーを表すデータ。
- 経時的な変化や量を分析する必要があるデータ。
- 作成後に更新する必要がないデータ。
- イベントタイプの定義: イベントの構造、プロパティー、検証ルールを定義するJSONスキーマ。このスキーマは、イベント名、表示ラベル、ターゲットCRMオブジェクト、イベントプロパティーからなります。また、イベントタイプにはCRMレコードのタイムラインをレンダリングするための表示テンプレートの定義も含めます。イベントタイプは、開発者プロジェクトを使用して定義します。
- イベントオカレンス: 実際のデータを格納し、イベント タイプ スキーマに照らし合わせて検証される、個々のイベントインスタンス。イベント オカレンス データはアプリイベントAPIを介して送信されます。このデータには、イベントタイプ識別子、プロパティー値、タイムスタンプとその他のメタデータ、ならびにCRMレコードの関連付けに関するCRMオブジェクト参照データが含まれます。
タイムラインイベントとアプリイベントの違いHubSpotでは以前、CRMオブジェクトのタイムラインにイベントデータを表示できるように、タイムラインイベントをリリースしていました。アプリイベントは、拡大されたサポート対象オブジェクト全体でタイムラインイベントと同じ機能を果たせるだけでなく、HubSpotの他のツールでも利用できます。アプリイベントでも、カスタムイベントを使用できるようになったとともに、固有のインデックスページが設定され、イベントアクティビティーを一元的に把握できるようになりました。既存のタイムラインイベント連携も引き続き機能し、アプリイベントと同じ場所に表示されます。ただし、新しいイベントタイプを作成する場合や、既存のタイプに変更を加える場合には、開発者プロジェクトでアプリイベントとして作成／再作成する必要があります。
サポート対象のオブジェクトとツール
イベントタイプを定義する際は、イベントデータをそのソース（ウェブサイトにログインしたコンタクトなど）に結び付けられるように、イベントタイプを特定のCRMオブジェクトと関連付けて設定します。これにより、イベントオカレンスが該当するタイプのCRMレコードに関連付けられるようになります。アプリイベントには、以下のCRMオブジェクトを関連付けることができます。- コンタクト
- 会社
- 取引
- チケット
- カスタムオブジェクト
- アプリオブジェクト
- イベント管理インターフェース: アカウントで［データ管理］****＞［カスタムイベント］****に移動すると、カスタム イベント ダッシュボードでカスタム イベント データと併せてアプリ イベント データを確認し、分析できます。
- CRMレコードのタイムライン: イベントオカレンスに関連付けられているCRMレコードのタイムラインで、アプリ イベント アクティビティーを時系列で確認できます。
- レポートツール: 分析と可視化を目的に、アプリ イベント データを使用してカスタムレポート、カスタマー ジャーニー アナリティクス、データセットを作成できます。
- リードスコア、リスト、ワークフロー: 動的リスト、リードスコアリング、ワークフローのトリガーを目的に、イベントを使用してCRMデータベースをセグメント化できます。
ベストプラクティス
イベントタイプを作成する際のベストプラクティスは以下のとおりです。- イベントタイプとプロパティーは、ワークフロー、リスト、レポート、カスタム イベント ダッシュボードでフィルターとして表示されるため、明確で分かりやすい名前にします。
- データに一致し、正確な適切なフィルタリングおよび分析を可能にする、適切なプロパティータイプ（文字列、数値、日時など）を選択します。
- セグメンテーション、レポート作成、自動化トリガーに役立つプロパティー（取引金額、ユーザーロール、アクションカテゴリーなど）を含めます。
- レポート作成やワークフローのユースケースを念頭に、ユーザーがイベントデータを絞り込んでグループ化する方法を考慮してイベントタイプを設計します。
- イベント構造に依存する既存のワークフローやレポートが中断される可能性があるため、既存のイベント タイプ スキーマには破損につながるような変更を加えないようにします。
- プログラムによるイベント オカレンス データ リクエストをレビューして、イベント タイプ スキーマに照らし合わせて適切に検証されることを確認します。
- イベントのプロパティー値（特に日付、数値、カテゴリーデータ）には一貫した書式設定を使用します。
- イベントオカレンスが有効なCRMレコードIDに関連付けられるようにします。
- イベント送信の成功率とエラーレスポンスをモニタリングします。
- CRMレコードのタイムラインとカスタム イベント ダッシュボードで、イベントデータが正確であることを定期的に確認します。
- 可能な場合は、1つのAPIリクエストで複数のイベントオカレンスを一括処理します（バッチあたり最大500件）。
- イベントオカレンスのペイロードの無駄をなくすために、必要なプロパティーデータのみを含めます。
- 失敗したイベント送信に対してエクスポネンシャルバックオフ方式の再試行ロジックを実装します。
制限事項
アプリイベントを計画および作成する際は、次の制限事項にご注意ください。バージョンの要件
- アプリイベントは、最新バージョンの開発者プロジェクトプラットフォーム（
2025.2）でのみ作成できます。 - 既存のイベントタイプについては、引き続きv1およびv3のタイムラインイベントAPIを使用できます。ただし、
v1およびv3のAPIを使用して新しいイベントタイプを作成することはできません。
イベントタイプに関する制約
- イベントオカレンスは、定義されたイベントタイプのスキーマに準拠している必要があります。そうでない場合は拒否されます。
- 一部のイベントタイプのフィールドは、イベントタイプが作成された後に更新することはできません（
name、objectTypeなど）。 - 新しいイベントタイプは、審査プロセスを経てからでないと有効化できません。
データの制限
- 個々のプロパティーは最大510KBに制限され、イベントの合計サイズには1MBの上限が適用されます。
- アプリイベントはアプリマーケットプレイスのプロバイダーを対象としており、OAuth認証を使用するように設定されているアプリでのみ機能します。内部システムでは、代わりにカスタムイベントを使用する必要があります。
使用の開始
アプリイベントの使用を開始するには、次のことを行う必要があります。- 開発者プロジェクトを使用して、イベントデータの構造を定義するイベントタイプを作成します。
- アプリイベントAPIを使用して、イベント オカレンス データをアプリに送信します。
- HubSpotのレポートツール、オートメーションツール、またはアナリティクスツールで、必要に応じてデータを活用します。