マーケティングイベント

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

HubSpotでアプリ定義を作成する

HubSpotユーザーのアカウントに連携を接続できるようにするためには、HubSpotで連携用のアプリ定義を作成する必要があります。アプリ定義には、ユーザーアカウントとの初期接続を試行する際に、HubSpotユーザーに対して表示されるロゴやテキストの詳細や、連携の際にユーザーのHubSpotアカウントで必要となる権限（スコープ）などが含まれます。

次の手順で、アプリの作成を開始できます。

• 開発者アカウントを作成します。
• 開発者アカウントでアプリ定義を作成（英語）します。
• アプリケーション定義に、適切なマーケティングイベントのスコープを含めます。
  • crm.objects.marketing_events.read マーケティングイベントの情報を読み取れるようにする場合。
  • crm.objects.marketing_events.write マーケティングイベントの情報を作成、削除、または変更できるようにする場合。

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

サブスクライバーの状態に関するエンドポイント

サブスクライバー状態のエンドポイントを使用すると、HubSpotのコンタクトがマーケティングイベントに登録したかどうかの状況を記録できます。例えば、HubSpotのコンタクトがマーケティングイベントに登録した場合、このエンドポイントを使用してそれを記録します。

サブスクリプションエンドポイントには、以下の2つがあります。

• POST /marketing/v3/marketing-events/events/{externalEventId}/{subscriberState}/upsert：一連のHubSpotコンタクト（コンタクトIDで識別）と、指定されたIDのマーケティングイベントとの間の登録状態を記録します。
• POST /marketing/v3/marketing-events/events/{externalEventId}/{subscriberState}/email-upsert：一連のHubSpotコンタクト（Eメールアドレスで識別）と、指定されたIDのマーケティングイベントとの間の登録状態を記録します。

{subscriberState}には、次の3つの値を使用できます。

• register：HubSpotのコンタクトがイベントに登録していることを示します。
• attend：HubSpotコンタクトがイベントに出席したことを示します。
• cancel:イベントに登録していたHubSpotのコンタクトが、イベントの登録をキャンセルしたことを示します。

設定を構成する

アプリに対してマーケティングイベントを適切に有効化するためには、いくつかの設定が必要です。

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

これは利便性を目的に提供されている機能ですが、これに依存せず、CRUDメソッドを使用してご自身でマーケティングイベントを作成することをお勧めします。

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

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

要件：

• 許容値：
  • externalAccountId（QueryParam）：外部アプリでの顧客のaccountId。
  • appId（QueryParam）：イベントの詳細をリクエストしているHubSpotアプリケーションのID。これはアプリのIDになります。
  • externalEventId（PathParam）：詳細を取得する対象のイベントの、外部アプリでのID。
• 戻り値：
  • マーケティングイベントの詳細

ステップ2：MarketingEventExtensionでAPIを設定する

MarketingEventDetailsオブジェクトを返すアプリ内のAPI作成が完了したら、次は、MarketingEventExtensionでこのAPIへのURLパスを設定し、HubSpotがイベント詳細を取得するためのリクエストの送信先を把握できるようにする必要があります。

※設定するパスは、次の要件を満たしている必要があります。

• %s文字列が最低1つ含まれている必要があります。これをパスパラメーターとして使用して、イベントID（externalEventId）に代入します。
• 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

次のフィールドを含むJSONレスポンスが返されます。