最終更新日: 2025年9月11日
アプリ イベント データをHubSpotに送信するには、まず、開発者プロジェクトを使用してイベントタイプを作成します。イベントタイプとは、送信するイベント オカレンス データの構造、プロパティー、検証ルールを定義するJSONスキーマのことです。このスキーマは、イベント名、表示ラベル、ターゲットCRMオブジェクト、イベントプロパティーからなります。また、イベントタイプにはCRMレコードのタイムラインをレンダリングするための表示テンプレートの定義も含めます。
このドキュメントで説明するアプリイベントは、開発者プロジェクトを使用してアプリマーケットプレイス向けに開発されたアプリを対象としています。他のタイプの連携を対象にカスタム イベント レポートを作成するには、代わりにカスタムイベントを使用してください。

​
前提条件

アプリ イベント タイプの定義をプロジェクトに含めるには、次の条件を満たす必要があります。
  • HubSpot CLIバージョン7.5.4以降を使用していること。使用しているCLIのバージョンを確認するには、hs --versionを実行します。また、バージョンを更新するには、npm i -g @hubspot/cli@nextを実行します。
  • アプリ イベント コンポーネントを追加してプロジェクトを更新できるように、あらかじめプロジェクトをデプロイすること。

​
プロジェクトファイルを設定する

以前に作成した、タイムラインイベントを使用する公開アプリがある場合は、開発者プラットフォームに公開アプリを移行する方法について詳細をご確認ください。
1

アプリの設定とプロジェクトの構造

プロジェクトで新しいアプリ イベント タイプの定義を作成するには、アプリの設定hsmeta.jsonファイルを更新して、requiredScopesフィールドにtimelineスコープを含めます。こうしなければ、アプリ イベント データはCRMレコードのタイムラインに表示されません。イベントデータが正常に送信されように、インストーラーがこのスコープを付与する必要があります。
"requiredScopes": [
  "timeline"
],
アプリに組み込まれている機能によっては、他のスコープも追加しなければならない場合があります。
次に、プロジェクトのapp/ディレクトリー内にapp-eventsディレクトリーを追加します。app-events/ディレクトリー内に、アプリ イベント タイプを定義するJSON設定ファイルを追加します。このファイルには任意の名前を付けることができますが、ファイル名の末尾は*-hsmeta.jsonにする必要があります。アプリごとに、それぞれ固有の*-hsmeta.jsonファイルを持つ最大750個のイベントタイプを含めることができます。
project-folder/
└── src/
    └── app/
        ├── app-hsmeta.json
        └── app-events/
            └── my-event-type-hsmeta.json
2

イベント タイプ スキーマを設定する

イベントタイプの*-hsmeta.jsonファイルで、イベント タイプ スキーマを設定します。このスキーマで、イベントタイプ属性（名前、CRMレコードのタイムライン表示テンプレート、イベントデータを関連付けるCRMオブジェクトタイプなど）を設定します。これらのフィールドの中には作成後に更新できるものもありますが、nameフィールドとobjectTypeフィールドは、イベントタイプの作成後に変更することはできません。例えば、顧客のログインイベントを追跡する場合は、以下のイベント タイプ スキーマを使用できます。
{
 "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個のプロパティーを設定できます。アプリイベントのリファレンスドキュメントで、要件や制限を含め、プロパティーの詳細についてご確認ください。
3

HubSpotに変更内容をアップロードする

HubSpotにプロジェクトをアップロードするには、hs project uploadコマンドを使用します。
hs project upload
ビルドフェーズの際に、HubSpotがイベントタイプを検証します。スキーマ検証エラーがある場合は、CLIから、何を修正すべきかを示すエラーが返されます。既定では、ビルドが成功すると、HubSpotによってプロジェクトが自動的にデプロイされます。プロジェクト設定でこの機能をオフにしている場合は、hs project deployを使用して手動でデプロイできます。デプロイが完了すると、アプリ イベント タイプが有効になり、これを使用してイベント オカレンス データを受信できるようになります。

​
fullyQualifiedNameを取得する

当該イベントタイプに対応するイベント オカレンス データを送信するには、アプリイベントAPIを使用してfullyQualifiedNameを取得する必要があります。この名前はイベントタイプを識別するものであり、アプリイベントAPIの全ての操作では、この名前を含める必要があります。 eventTypeNameを取得するには、POSTリクエストをhttps://api.hubapi.com/integrators/timeline/v4/types/projectsに送信します。リクエスト本文には、以下のフィールドを含めます。
  • projectNameフィールド。プロジェクトのhsproject.jsonファイルに含まれるname値に設定する必要があります。
  • developerSymbolフィールド。イベントタイプの*-hsmeta.json設定ファイルに含まれるuid値に設定する必要があります。
{
  "projectName": "my-marketplace-app",
  "developerSymbol": "customer_login_event"
}
レスポンスでは、プロジェクト名、イベントタイプ名、fullyQualifiedNameが返されます。 
{
  "developerQualifiedSymbol": {
    "projectName": "marketplace",
    "developerSymbol": "customer_login_event"
  },
  "fullyQualifiedName": "ae000000_integrators-timeline-event-type-id-0000000"
}
fullyQualifiedName値は変更されないため、実装にハードコードしても問題ありません。APIでは、この値を取得できる1日あたりの回数に制限が適用されるため、プログラムによってこのAPIを使用することはできません。

​
イベントタイプを管理する

イベントタイプを作成後に更新するには、プロジェクト内のイベント タイプ スキーマを更新してから、プロジェクトを再度アップロードしてアプリをビルドし、デプロイすればよいだけです。 イベントタイプを使用する必要がなくなった場合は、プロジェクトから削除できます。ただし、イベントタイプを削除する前に、次の点にご注意ください。
  • イベントタイプは完全に削除されます。この削除操作を元に戻すことはできません。
  • イベントタイプを削除すると、アプリをインストールした全てのアカウントから、イベントタイプとそのタイプの全てのイベントオカレンスが削除されます。
  • イベントタイプを削除すると、そのイベントタイプに依存する他のHubSpotツール（レポートやワークフローなど）が機能しなくなります。 イベントタイプを削除するには、プロジェクトからイベントタイプ設定ファイル*-hsmeta.jsonを削除した上で、プロジェクトをアップロードしてデプロイします。

​
既存のタイムライン イベント タイプを移行する

タイムラインイベントを使用する既存の公開アプリがある場合は、CLIを使用して、その公開アプリを開発者プラットフォームに移行できます。
アプリを移行する前に、以下の点をご確認ください。
  • 公開アプリ移行ガイドで、開発者プラットフォームベータ版に関する現在の考慮事項と制限について確認します。
  • 既存のタイムライン イベント タイプ（v1／v3）を開発者プラットフォームに移行した後、7日以内に既存のv1／v3タイムラインイベントAPIリクエスト（当該イベントタイプのイベントオカレンス／インスタンスAPIリクエストの両方を含む）を新しいv4エンドポイントに合わせて変更する必要があります。7日が経過すると、v1／v3イベント オカレンス エンドポイントに対する既存の呼び出しは401エラーを返します。
アプリを移行するには、次の手順に従います。
  • ターミナルで、hs app migrateを実行し、ターミナルプロンプトに従ってアプリとタイムラインイベントを移行します。
  • 移行プロセスが完了すると、アプリは開発者プロジェクト内で有効になり、ローカル プロジェクト ディレクトリーが自動的に作成されます。
  • HubSpotでプロジェクトを開くには、ローカル プロジェクト ディレクトリーに移動して、hs project openを実行します。
生成される設定ファイル（*-hsmeta.json）には、null値のフィールドが含まれている場合があります。これらのフィールドは移行によるアーティファクトであり、削除しても問題ありません。

​
次のステップ

イベントタイプを作成した後は、APIを使用してイベント オカレンス データを送信する方法をご確認ください。 また、引き続きアプリイベントの作成とカスタマイズを行うには、アプリイベントのリファレンスドキュメントをご確認ください。