ベータ版APIのアクセスとテストに関して

注：このAPIは開発途中のため、テストの結果やフィードバックに基づいて今後変更が生じる可能性があります。このようなエンドポイントをご利用いただくことによって、当社の開発者向け規約とDeveloper Beta Terms（開発者向けベータ版利用規約）（英語）を順守することに同意したものと見なされます。また、安定版ではないAPIのテストに伴うリスクを認識および理解していただいたことにもなります。
 

このAPIは現在ベータ版として提供されています。最新の安定版については、イベントの取得（英語）、IDによるイベントの取得（英語）、IDによるイベントのグループの取得（英語）のページをご確認ください。


カスタム行動イベント

概要エンドポイント
APPLICABLE PRODUCTS
  • Marketing Hub
    • Enterprise

カスタム行動イベントとは、アカウント定義のイベントで、イベントプロパティーにイベントの詳細を格納できます。HubSpotでは3種類のカスタム行動イベントを作成できます。

  • 手動でトラッキングされる行動イベントとは、HubSpotや連携によって自動的に取り込まれない、貴社固有のカスタムイベントのことです。このAPIを介して、これらのイベントに手動でデータを送信できます。

この記事では、手動でトラッキングされるカスタム行動イベントを作成する方法、APIを介してイベントデータを送信する方法、取り込まれたイベントデータを使用する方法を説明します。

イベントを作成する

イベントを設定するには、まず、HubSpotでイベントを作成します。イベントを作成するとHubSpotによって一連の既定のイベントプロパティーが追加され、ユーザーはそこにイベントデータを格納できます。イベントの追加プロパティーを作成することもできます。イベントのプロパティーは、いつでも作成または編集できます。 

イベントを設定したら、APIを介してデータを送信できます。

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

イベントデータをHubSpotに送信するには、POSTリクエストをhttps://api.hubspot.com/events/v3/sendに送信します。

リクエスト本文には、イベントの情報と、そのイベントの完了に関連付けるコンタクトを含める必要があります。カスタム行動イベントをトリガーする際は、次のフィールドが必須です。

  • 識別子：コンタクトのID、Eメールアドレス、またはイベントに関連付けられているコンタクトのutkのいずれか。
  • イベント名：イベントの内部名。これはHubSpotで確認できます。詳しくはイベントの内部名を確認する方法をご確認ください。カスタムイベント内部名

プロパティーデータを送信する

リクエスト本文にプロパティーを含めるには、次の形式を使用します。

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

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

Use this table to describe parameters / fields
プロパティーのタイプDescription
enumeration

一連のオプションを表す文字列。複数の値を送信する場合は、値をセミコロンで区切ります。このタイプは、HubSpotでのドロップダウン選択、ラジオ選択、および複数チェックボックスのプロパティーに対応しています。

date

UTCの深夜0時に設定されたUnixタイムスタンプ（ミリ秒単位）。このタイプは、HubSpotでの日付ピッカープロパティーに対応しています。

string

プレーンテキスト文字列。文字数の上限は65,536文字です。このタイプは、HubSpotでの単行および複数行のテキストプロパティーに対応しています。

number

数値。小数点以下は第一位までに制限されます。このタイプは、HubSpotでの数値および計算プロパティーに対応しています。

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

  • HubSpotアカウントにて、［レポート］＞［アナリティクスツール］の順に進みます。
  • ［カスタム行動イベント］をクリックします。
  • イベントの名前をクリックします。
  • ［プロパティー情報］タブをクリックします。
  • プロパティーテーブルで、プロパティーの名前の下に表示されているプロパティーのタイプを確認します。カスタムイベントのプロパティータイプ

 

イベントの時刻を設定する

イベントの完了時刻を指定するには、リクエストのoccurredAtフィールドにタイムスタンプを含めます。既定では、このフィールドがリクエストに含まれていない場合、HubSpotはリクエストの送信時刻を完了時刻として設定します。API自体の起動時刻とは異なるタイムスタンプを格納するには、occurredAtフィールドを利用できます。例えば、「パートナーウェビナーへの参加」というイベントがあるとします。ウェビナーは2週間前に開催されましたが、今日になってデータを受信しました。この場合、2週間前のタイムスタンプを格納したoccuredAtプロパティーを設定すると、HubSpotにこのプロパティーに応じた日付が設定されます。

リクエスト本文の例

以下に示すリクエスト本文の例では、都市、国、ページ、およびインタラクションソースのデータをHubSpotに送信します。イベントを完了したコンタクトは、objectIdフィールドで表されます。イベントデータの送信方法の詳細については、この記事の上部にある［エンドポイント］タブでご確認いただけます。

// POST to https://api/hubspot.com/events/v3/send { "eventName": "pe1234567_login_event", "properties": { "hs_city": "Cambridge", "hs_country": "United States", "hs_page_id": "53005768010", "hs_page_content_type": "LANDING_PAGE", "hs_touchpoint_source":"DIRECT_TRAFFIC" }, "objectType": "contacts", "objectId": "608051" }

Exceeding any of the following limits will result in a failed request:

  • The property label and internal name are limited to 50 characters.
  • URL and referrer properties can receive up to 1024 characters, while all other properties can receive up to 256 characters.
  • Each event completion can contain data for up to 50 properties.
  • Property internal names must start with a letter and contain only lowercase letters a-z, numbers 0-9, and underscores.
  • Properties with the same internal name after lowercasing are considered duplicates, and only one of the properties will be used on completion. HubSpot will sort in ascending lexicographical order and keep the last property seen among the first 50 properties.

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

コンタクトのイベントデータを取得するには、GETリクエストを/events/v3/events/eventType={EVENT_NAME}&objectType=contact&objectId={CONTACT_ID}に送信します。 

上記のリクエストには以下の要素が含まれています。

  • eventType：イベントの内部名。
  • objectType：レコードのオブジェクトタイプ。
  • objectId：コンタクトのID。

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

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

以下に、アセットタイプとインタラクションソースとして有効な値の説明とリクエストの例を記載します。

アセットのタイプ

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

// example request body { "eventName": "pe1234567_manually_tracked_event", "properties": { "hs_page_id": "53005768010", "hs_page_content_type": "LANDING_PAGE" }, "objectType": "contacts", "objectId": "6091051" }

You can also use the hs_asset_type property. If both hs_page_content_type and hs_asset_type are included in one request, hs_page_content_type will override the hs_asset_type value.

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

Use this table to describe parameters / fields
値Description
STANDARD_PAGE

ウェブサイトページでのインタラクション。

LANDING_PAGE

ランディングページでのインタラクション。

BLOG_POST

ブログ記事でのインタラクション。

KNOWLEDGE_ARTICLE

ナレッジベース記事でのインタラクション。

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

Use this table to describe parameters / fields
値Description
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

JSON 
// example request body
{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
 "objectType": "contacts",
 "objectId": "6091051"
}

インタラクションソース

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

Use this table to describe parameters / fields
値Description
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

インタラクションソースが（有料ソーシャル広告ではない）ソーシャルメディアであることを示します。
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。