マーケティングイベント

概要エンドポイント

マーケティングイベントは、コンタクトおよび会社と同様に、CRMオブジェクトです。ウェビナーなどのマーケティングイベントをトラッキングし、他のHubSpot CRMオブジェクトに関連付けることができます。この記事では、マーケティングイベントAPIを使用してマーケティングイベントをアプリと連携させる方法について詳しく説明します。

In this article

スコープの要件

いずれかのマーケティング イベント エンドポイントにAPIリクエストを送信するには、次のスコープが必要です。

  • crm.objects.marketing_events.read：マーケティングイベントおよび参加データを取得する権限を付与します。
  • crm.objects.marketing_events.write：マーケティングイベント情報を作成、削除、変更する権限を付与します。

アプリによって行われた呼び出しを認証する際は、非公開アプリのアクセストークンまたはOAuthのいずれかを使用できます。認証方式の詳細をご確認ください。利用可能なエンドポイントの完全なリストについては、この記事の上部にある［エンドポイント］タブをクリックしてください。

イベントの作成と更新

/marketing/v3/marketing-events/events/upsertエンドポイントにPOSTリクエストを送信することで、マーケティングイベントを作成または更新できます。要求本文のinputsフィールドに、更新するイベントに対応する任意のcustomPropertiesと、イベントのその他の詳細（イベントの名前、開始時刻、説明など）を含めることができます。

リクエストで指定されたIDを持つマーケティングイベントが既に存在する場合、そのマーケティングイベントは更新されます。ない場合は、新しいイベントが作成されます。

例えば、次の要求は、「Virtual cooking class」という名前で、IDが4のイベントを作成します。

// Example request body for POST request to /marketing/v3/marketing-events/events/upsert { "inputs": [ { "customProperties": [ { "name": "property1", "value": "1234" } ], "eventName": "Virtual cooking class", "startDateTime": "2023-11-30T17:46:20.461Z", "eventOrganizer": "Chef Joe", "eventDescription": "Join us for a virtual cooking class! Yum." "eventCancelled": false, "externalAccountId": "CookingCo", "externalEventId": "4" } ] }

この記事の上部にある［エンドポイント］タブをクリックすると、リクエストに含めることができる全ての利用可能なフィールドの完全なリストを確認できます。

イベント参加エンドポイント

イベント参加状態エンドポイントを使用すると、HubSpotコンタクトによるマーケティングイベントの登録状態を記録できます。例えば、このエンドポイントを使用して、HubSpotのコンタクトがマーケティングイベントに登録したことを記録できます。

コンタクトの参加ステータスを更新するために使用できるエンドポイントは2つあります。以前、参加者のステータスの更新に/upsertまたは/email-upsertエンドポイントを使用していた場合は、代わりに以下のエンドポイントを使用して、同じ機能を利用しつつ、コンタクトタイムラインにコンタクトの参加期間を入力することもできます。

  • 既存のコンタクトのコンタクトIDを使用する場合：
    • 外部アプリケーションのイベントのIDをexternalEventIdとして使用し、/marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/createにPOSTリクエストを送信します。
    • リクエスト本文で、次のフィールドを含むinputsオブジェクトを指定します。
      • interactionDateTime：コンタクトがイベントに登録した日時。
      • vid：既存のコンタクトのコンタクトID。
  • イベント参加者の1人のEメールアドレスを使用する場合：
    • /marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-createにPOSTリクエストを送信します。
    • リクエスト本文で、次のフィールドを含むinputsオブジェクトを指定します。
      • interactionDateTime：コンタクトがイベントに登録した日時。
      • email：inputs内のemailフィールドの値として指定する、参加者のEメールアドレス。 
    • 指定したEメールアドレスが既存のコンタクトのアドレスと一致しない場合は、新しいコンタクトが作成されます。

上記のエンドポイントの両方について、対応するパスパラメーターに次の値を指定します。

  • externalEventId：マーケティングイベントのID。
  • subscriberState：コンタクトの新しい参加ステータスと一致する以下の列挙値。
    • REGISTERED：HubSpotコンタクトがイベントに登録したことを示します。
    • ATTENDED：HubSpotコンタクトがイベントに参加したことを示します。コンタクトのステータスをATTENDEDに更新する場合は、リクエスト本文のパラメーターとして、ISO 8601インスタント形式で指定したjoinedAtおよびleftAtタイムスタンプを含めることもできます。
    • CANCELLED：以前イベントに登録したHubSpotコンタクトが登録をキャンセルしたことを示します。

イベントが完了したら、/marketing/v3/marketing-events/events/{externalEventId}/completeにPOSTリクエストを送信することにより、イベントを完了とマークし、参加の測定指標（例：全ての参加者の参加期間）を計算できます。このアクションは元に戻せないため、全ての参加状態変更イベントがすでに発生している場合にのみ、このエンドポイントを呼び出す必要があります。 

注：これらのAPIは、コンタクトのIDとイベントのinteractionDateTime値が変更されていない限り、べき等性があります。これにより、重複したイベントがマーケティング イベント プロパティーにHubSpotによって作成されることなく、サブスクライバーの状態を複数回安全に設定できます。

アプリ設定を構成する

マーケティングイベントがHubSpotと適切に同期するためには、いくつかの設定が必要です。

HubSpotに登録状態の変更（登録やキャンセルなど）を送信すると、HubSpotはまず、指定されたイベントIDに対応するマーケティングイベントが存在するかどうかを確認します。存在しない場合、HubSpotはアプリに設定されたエンドポイントを呼び出してマーケティングイベントの詳細を取得し、HubSpotでイベントを作成してから、サブスクライバー状態の変更を公開します。

これは利便性を目的に提供されている機能ですが、HubSpotでマーケティングイベントを作成するこの機能には依存せず、この記事の上部にある［エンドポイント］タブにあるCRUDメソッドを使用して、マーケティングイベントを自分で作成することをお勧めします。

ステップ1：アプリでAPIを作成する

マーケティングイベントをサポートするためにHubSpotでは、マーケティングイベントを使用する各アプリでAPIを定義し、特定のマーケティングイベントに関する情報を取得することを要件としています。

要件：

  • 許容値：
    • externalAccountId：外部アプリの顧客のaccountIdを指定するクエリーパラメーター。
    • appId：イベントの詳細をリクエストしているHubSpotアプリケーションのIDを指定するクエリーパラメーター。これはアプリのIDです。
    • externalEventId：HubSpotが詳細な情報をリクエストしている外部アプリのイベントのIDを指定する、リクエストのURL内のパスパラメーター。
  • 戻り値：
    • マーケティングイベントの詳細を提供するJSONオブジェクト。以下の表で詳しく説明しているフィールドを含みます。
フィールド名 必須 型 フィールドの説明
eventName true string マーケティングイベントの名前。
eventOrganizer true string マーケティングイベントの主催者の名前。
eventType false string このイベントのタイプを説明します。例：WEBINAR、CONFERENCE、WORKSHOP
startDateTime false string($date-time) マーケティングイベントの開始日時。
endDateTime false string($date-time) マーケティングイベントの終了日時。
eventDescription false string マーケティングイベントの説明。
eventUrl false string 外部イベントアプリケーションでマーケティングイベントが存在するURL。
eventCancelled false bool マーケティングイベントがキャンセルされたかどうかを示します。既定ではfalseです。

HubSpotはX-HubSpot-Signature-v3ヘッダーも送信します。これは、リクエストがHubSpotから送信されたことを確認するために使用できます。署名の詳細とその検証方法については、リクエスト署名を参照してください。

ステップ2：HubSpotにAPIへのURLパスを提供する

特定のマーケティングイベントの詳細を提供するオブジェクトを返すAPIをアプリで作成したので、次は/marketing/v3/marketing-events/{appId}/settingsにPOSTリクエストを送信して、HubSpotにAPIへのURLパスを提供する必要があります。これにより、HubSpotはアプリにリクエストを送信してマーケティングイベントの詳細を取得する方法を決定できます。

POSTリクエストの本文で、eventDetailsURLフィールドを使用してURLを指定します。eventDetailsURLは次の2つの要件を満たす必要があります。

  • %s文字列を含んでいること。HubSpotはこの文字列をパスパラメーターとして使用し、イベントのID（externalEventId）に代入します。
  • https://プレフィックスとドメイン名（例：my.event.app）を含む、APIリソースへのフルパスであること。

例えば、https://my.event.app/events/%sのeventDetailsURLを設定し、idが1234-event-XYZのイベントの詳細を取得するリクエストを行う必要がある場合、HubSpotアプリのidがapp-101で、アカウントのidがABC-account-789だとすると、HubSpotは次のURLにGETリクエストを送信します。

https://my.event.app/events/1234-event-XYZ?appId=app-101&externalAccountId=ABC-account-789

参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。