カスタムイベント完了を送信する

サポートされる製品

スコープ要件

カスタムイベントは、イベントの詳細をイベントプロパティーに格納するアカウント定義のイベントです。イベントデータをHubSpotに送信するように追跡コードをカスタマイズできるだけでなく、このAPIを介してイベント完了データを送信することもできます。 APIを使用してカスタムイベントを作成し、カスタムイベントデータを送受信する方法について以下に説明します。

イベントの定義

イベント完了データをHubSpotに送信するには、まず、イベントのメタデータ、CRMオブジェクト、関連付け、プロパティーなど、イベント自体を定義する必要があります。イベントを定義するには、カスタムイベント定義APIを使用するか、Marketing Hub Enterpriseをご利用の場合はHubSpotでイベントを作成することができます。イベントを作成するとHubSpotによってデフォルトのイベントプロパティーのセットが追加され、ユーザーはそこにイベントデータを格納できます。イベントの追加プロパティーを作成することもできます。イベントのプロパティーは、いつでも作成または編集できます。イベントを設定したら、APIを介して、またはHubSpotトラッキングコードをカスタマイズして、イベントにデータを送信できます。

イベントデータを送信する

イベントデータをHubSpotに送信するには、リクエスト本文にイベントデータを指定して、POSTリクエストをhttps://api.hubspot.com/events/v3/sendに送信します。イベントデータを送信する前に、後述の制限を確認してください。制限を超えるとエラーが発生します。

{
  "eventName": "pe1234567_login_event",
  "objectId": "608051",
  "occurredAt": "2024-06-28T12:09:31Z",
  "properties": {
    "hs_city": "Cambridge",
    "hs_country": "United States",
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE",
    "hs_device_type": "PDA;Smartphone",
    "hs_touchpoint_source": "DIRECT_TRAFFIC"
  }
}

パラメーター	タイプ	説明
`eventName`	文字列	イベントの内部名。これを確認するには、既存のイベント定義をクエリーするか、HubSpotアプリ内で確認します。
`objectId`	必須文字列	イベントが関連付けられるCRMレコードのID。コンタクトの場合は、`email`または`utk`フィールドを使用して、EメールアドレスまたはHubSpotユーザートークンでコンタクトを識別することもできます。イベントにカスタム一致IDが定義されていない限り、他の全てのオブジェクトタイプでは`objectId`が必要です。イベントに`customMatchingId`が定義されている場合、HubSpotは設定されたマッピングに基づいて`objectId`を自動的に設定またはオーバーライドします。詳しくはカスタムイベント定義ガイドをご参照ください。
`occurredAt`	文字列	HubSpotではデフォルトで、イベント完了タイムスタンプをリクエストが送信された時間に設定します。イベントの完了時刻を指定するには、`POST`リクエスト本文の`occurredAt`フィールドにタイムスタンプを含めます（ISO 8601形式）。これは、現実のイベントの完了を正確に反映するために、イベントデータの日付をさかのぼって設定する場合に特に役立ちます。
`properties`	オブジェクト	データの送信先となるイベントプロパティー。これには、HubSpotのデフォルトのイベントプロパティーや、イベントに定義した任意のカスタムプロパティーを含めることができます。デフォルトのイベントプロパティーのほとんどは文字列プロパティーですが、イベント定義をクエリーするか、HubSpotのイベントにナビゲートすることで、全てのイベントプロパティーを確認できます。カスタム一致IDがイベントに設定されている場合は、`objectId`を省略できます。HubSpotでは、設定されたマッピングに基づいてイベントの`objectId`を設定することにより、イベントとCRMオブジェクトのリンクを試みます。イベントプロパティーの詳細については後述します。

注：

次のいずれかの制限を超えると、リクエストは失敗します。

プロパティーラベルと内部名は50文字に制限されています。
URLとリファラーのプロパティーは最大1,024文字まで、その他のプロパティーは最大256文字までです。
各イベント完了には、最大で50個のプロパティーのデータを含めることができます。
プロパティーの内部名はアルファベットで始まる必要があり、使用できるのは小文字のa～z、数字の0～9、アンダースコアのみです。
小文字にした後の内部名が同じプロパティーは重複していると見なされ、完了時にはどちらか一方のプロパティーのみが使用されます。HubSpotでは、辞書の順序の昇順で並べ替え、最初の50個のプロパティーのうち、最後に表示されたプロパティーを保持します。
アカウントごとの一意のイベント定義数の上限は500です。
1か月あたりのイベント完了数の上限は3,000万です。

イベントデータを取得する

イベントデータを取得するには、GETリクエストを/events/v3/eventsに送信します。

特定のイベントの全てのイベント完了を返すには、eventTypeパラメーターと内部イベント名（例：pe123456_custom_event）を含めます。イベントアナリティクスAPIを使用して、全てのイベントタイプを取得できます。
特定のオブジェクトのイベント完了を返すには、objectIdパラメーターまたはobjectProperty.<property>パラメーターと一緒にobjectTypeパラメーターを含めます。objectTypeではCRMオブジェクトのタイプ（contactなど）を指定し、その他のパラメーターではオブジェクトの固有のID値（レコードIDまたは固有のIDプロパティー値）を指定します。コンタクトの場合はemailを固有IDプロパティーとして使用できます。

例えば、特定のコンタクトによって完了した全てのイベントを取得する場合、リクエストURLは以下のようになります。 /events/v3/events?objectType=contact&objectId=111111 また、コンタクトのEメールアドレスを使用することもできます。 /events/v3/events?objectType=contacts&objectProperty.email=bilbo@shire.com 特定のイベントプロパティー値を持つイベント完了で結果を絞り込むには、property.<propertyName>パラメーターを含めます。例えば、ホームページのページ訪問イベントを取得する場合、リクエストURLは以下のようになります。 /events/v3/events?eventType=e_visited_page&property.hs_page_title=home

プロパティー値にスペースが含まれる場合は、スペースを%20または+に置き換えます。例えば、property.hs_page_title=home+pageのようにします。

使用可能なパラメーターの詳細については、リファレンスドキュメントをご参照ください。

イベントプロパティー

イベント完了データはイベントプロパティーに格納されます（デフォルトのイベントプロパティーまたはカスタム定義プロパティーのいずれか）。イベントデータを送信するときは、更新するプロパティーのキーと値のペアを持つpropertiesオブジェクトと、保存するプロパティー値を含めます。

"properties": {
    "property1": "string",
    "property2": "string",
    "property3": "string"
  }

送信する値は、イベントプロパティーのタイプによって異なります。デフォルトのイベントプロパティーのほとんどは、単行テキスト（文字列）です。ただし、イベントごとに任意のタイプのカスタムプロパティーを作成できます。プロパティー値の書式を設定するときは、以下の表を確認してください。

プロパティータイプ	説明
`bool`	`true`または`false`のブール値。
`enumeration`	一連のオプションを表す文字列。複数の値を送信する場合は、値をセミコロンで区切ります。このタイプは、HubSpotでのドロップダウン選択、ラジオ選択、および複数チェックボックスのプロパティーに対応しています。
`date`	特定の年月日を表す値。値はUTC時間で表す必要があります。値の形式として、ISO 8601文字列またはミリ秒単位のエポック時間タイムスタンプ（UTC深夜0時）を使用できます。
`datetime`	特定の年月日と時刻を表すタイムスタンプ。値はUTC時間で表す必要があります。値の形式として、ISO 8601文字列またはミリ秒単位のUNIXタイムスタンプを使用できます。
`number`	小数第1位までの数値。このタイプは、HubSpotでの数値および計算プロパティーに対応しています。
`string`	プレーンテキスト文字列。65,536文字までに制限されています。このタイプは、HubSpotでの単行および複数行のテキストプロパティーに対応しています。

イベントの利用可能なプロパティーを表示するには、次の操作を行います。

HubSpotアカウントで、［データ管理］＞［カスタムイベント］に移動します。
テーブル内でCTAの名前をクリックします。
上部にある［プロパティー］タブをクリックします。
プロパティーテーブルで、プロパティーの名前の下に表示されているプロパティーのタイプを確認します。

アトリビューションレポート

クリックされた要素イベントや訪問されたURLイベントなどのJavaScriptイベントには、アトリビューションレポート用にアセットタイプとインタラクションデータが自動的に取り込まれます。手動でトラッキングされるイベントに同じデータを含めるには、イベントプロパティーを使用して、リクエスト本文に手動でデータを含める必要があります。詳しくはカスタムイベントの分析をご参照ください。以下に、アセットタイプとインタラクションソースとして有効な値の説明とリクエストの例を記載します。

アセットタイプ

特定のアセットタイプをカスタム行動イベントのリクエストに結び付けるには、リクエスト本文にhs_page_content_typeプロパティーを含めます。以下に例を示します。

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

hs_asset_typeプロパティーを使用することもできます。hs_page_content_typeとhs_asset_typeの両方が1つのリクエストに含まれている場合、hs_page_content_typeがhs_asset_typeの値よりも優先されます。

ランディングページやブログ記事などのHubSpotの標準コンテンツタイプは、次の値で表すことができます。

値	説明
`STANDARD_PAGE`	ウェブサイトページでのインタラクション。
`LANDING_PAGE`	ランディングページでのインタラクション。
`BLOG_POST`	ブログ記事でのインタラクション。
`KNOWLEDGE_ARTICLE`	ナレッジベース記事でのインタラクション。

その他全てのタイプのアセットには、次の値を使用します。

値	説明
`AD`	Facebook広告やGoogle 広告などの広告でのインタラクション。
`CALL`	コールでのインタラクション。
`CONTACT_IMPORT`	コンタクトインポートを介したインタラクション。
`CONVERSATION`	HubSpotコミュニケーションに関連するインタラクション。
`CUSTOM_BEHAVIORAL_EVENT_NAME`	カスタムイベントの内部名（例：`pe123456_manually_tracked_event`）。
`EMAIL`	Eメールでのインタラクション。
`EXTERNAL_PAGE`	外部ページでのインタラクション。
`INTEGRATIONS`	連携を介したインタラクション。
`MARKETING_EVENT`	マーケティングイベントでのインタラクション。
`MEDIA_BRIDGE`	メディアブリッジを介したインタラクション。
`MEETING`	ミーティングでのインタラクション。
`SALES_EMAIL`	1対1のセールスEメールでのインタラクション。
`SEQUENCE`	シーケンスでのインタラクション。
`SOCIAL_POST`	ソーシャルメディア投稿でのインタラクション。
`OTHER`	上記のいずれのカテゴリーにも該当しないアセットでのインタラクション。

アセットタイトル

カスタムイベントをアセットに結び付けるには、リクエストにhs_page_titleまたはhs_asset_titleプロパティーを追加し、アセットの名前を文字列の形式で指定します。以下に例を示します。 hs_page_title:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

インタラクションソース

カスタム行動イベントを特定のソースに結び付けるには、リクエストにhs_touchpoint_sourceプロパティーを追加し、次のいずれかの値を設定します。

値	説明
`CONVERSATION`	インタラクションソースがコミュニケーションであることを示します。
`DIRECT_TRAFFIC`	インタラクションソースが直接トラフィックであることを示します。
`EMAIL_MARKETING`	インタラクションソースがマーケティングEメールであることを示します。
`HUBSPOT_CRM`	インタラクションソースがHubSpotのCRMであることを示します。
`INTEGRATION`	インタラクションソースが連携であることを示します。
`MARKETING_EVENT`	インタラクションソースがマーケティングイベントであることを示します。
`OFFLINE`	インタラクションソースがオフラインであることを示します。
`ORGANIC_SEARCH`	インタラクションソースがオーガニック検索であることを示します。
`OTHER_CAMPAIGNS`	インタラクションソースが未分類のキャンペーンからのものであることを示します。
`PAID_SEARCH`	インタラクションソースが有料検索広告であることを示します。
`PAID_SOCIAL`	インタラクションソースが有料ソーシャル広告であることを示します。
`REFERRALS`	インタラクションソースがリファーラルであることを示します。
`SALES`	インタラクションソースが営業であることを示します。
`SOCIAL_MEDIA`	インタラクションソースが（有料ソーシャル広告ではない）ソーシャルメディアであることを示します。

アカウントと設定

アプリ管理

認証

自動化

CMS

コミュニケーション設定

コミュニケーション

CRM

イベント

ファイル

マーケティング

スケジューラー

Webhook

カスタムイベント完了を送信する

イベントの定義

イベントデータを送信する

注：

イベントデータを取得する

イベントプロパティー

アトリビューションレポート

アセットタイプ

アセットタイトル

インタラクションソース

​イベントの定義

​イベントデータを送信する

​注：

​イベントデータを取得する

​イベントプロパティー

​アトリビューションレポート

​アセットタイプ

​アセットタイトル

​インタラクションソース

イベントの定義

イベントデータを送信する

注：

イベントデータを取得する

イベントプロパティー

アトリビューションレポート

アセットタイプ

アセットタイトル

インタラクションソース