マーケティングイベント
マーケティングイベントは、コンタクトや会社と同様の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のコンタクトが、イベントの登録をキャンセルしたことを示します。
※ これらのAPIは、コンタクトのIDとイベント内のinteractionDateTime
の値が変更されていない限り、べき等であることにご注意ください。これにより、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レスポンスが返されます。
フィールド名 | 必須 | 型 | フィールドの説明 |
---|---|---|---|
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 | マーケティングイベントがキャンセルされたかどうかを示す。既定ではtrue です。 |
貴重なご意見をありがとうございました。