最終更新日: 2025年8月28日
メディアブリッジAPIを使用すると、インテグレーターは動画や音声ファイルなどのメディアオブジェクトとメディア消費データをHubSpotにプッシュできます。また、ユーザーのHubSpotアカウントで以下の機能が利用できるようになります。
- HubSpotのドラッグ&ドロップエディターでページやEメールにメディアオブジェクトを埋め込むためのモジュール。
- プロスペクトまたは顧客が動画、音声、およびその他のメディアタイプを操作したときに表示されるCRMタイムラインイベント。
- ターゲットを絞り込み、パーソナライズされた体験を提供するためのセグメント化されたリスト。
- メディア消費イベントに基づいてインタラクションを自動化するワークフロー。
- メディアアセットの効果を測定するためのレポート。
メディアブリッジAPIの使用
メディアブリッジアプリをHubSpotユーザーのアカウントに関連付けるには、その前に、HubSpot開発者アカウントを使用して、メディアブリッジアプリを登録し、最初のメディアオブジェクト定義を設定する必要があります。メディアオブジェクト定義を作成してカスタマイズする
メディアオブジェクトを定義するには、POST
リクエストを/media-bridge/v1/{appId}/settings/object-definitions
に送信します。リクエスト本文には、mediaTypes
配列内にVIDEO
、AUDIO
、DOCUMENT
、IMAGE
、またはOTHER
のいずれかのメディアタイプ値を含めます。
メディアオブジェクトを定義したら、PATCH
リクエストを/media-bridge/v1/{appId}/schemas/{objectType}
に送信し、POST
リクエストを/media-bridge/v1/{appId}/properties/{objectType}
に送信して、メディア オブジェクト プロパティーを作成して変更します。
メディアブリッジアプリをHubSpotユーザーのアカウントに関連付ける
メディアブリッジアプリをHubSpotユーザーのアカウントに関連付けるには、HubSpot開発者のアカウントでそのためのアプリ定義を作成する必要があります。アプリの定義には、以下の情報を含めます。- 連携でHubSpotユーザーのアカウントに対して最初に関連付けを行う際に、ユーザーに表示されるロゴやテキストなどの詳細。
- 連携で必要となる、ユーザーのHubSpotアカウントに対するスコープ。
- メディアブリッジアプリの開発者アカウントで、アプリケーション定義を作成します。
- アプリケーションを定義する際には、以下のスコープを含めます。
media_bridge.read
media_bridge.write
- アプリからの呼び出しを認証する際は、OAuth認証を使用します。認証方式の詳細をご確認ください。
https://app.hubspot.com/media-bridge-demo/{HubID}
の{HubID}
をアカウントIDに置き換えてアクセスします。- 右上の[アプリ]ドロップダウンメニューをクリックし、ご使用のメディアブリッジアプリを選択します**。 **
- アプリでは、アプリでサポートされるメディアタイプの確認や、サンプルメディアの作成ができます。
メディアオブジェクトを作成する
メディアオブジェクトの定義を作成し、メディアブリッジアプリをユーザーのアカウントにインストールしたら、OAuthトークンを使用して、アカウントでメディアオブジェクトを作成し、変更できるようになります。メディアオブジェクトはカスタムオブジェクトなので、カスタムオブジェクトAPIエンドポイントを使用して作成します。GET
リクエストを/media-bridge/v1/{appId}/settings/object-definitions/{mediaType}
に送信して、objectType
を見つけます。POST
リクエストを/crm/v3/objects/{objectType}
に送信して、ユーザーのアカウントにメディアオブジェクトを作成します。
VIDEO
およびAUDIO
メディアオブジェクトで利用可能な全てのプロパティーは、以下の表でご確認いただけます。
*でマークされたフィールドは必須です。
パラメーター | 型 | 説明 |
---|---|---|
id | 数値 | HubSpotのメディアブリッジシステム内の特定のメディアを識別するために使用されるID。このIDはHubSpotによって自動生成されます。開発者が設定することはできません。 |
hs_duration | 数値 | メディアの再生時間(ミリ秒)。 |
hs_oembed_url * | 文字列 | oEmbed仕様に準拠した有効なoEmbedレスポンスを返す必要があるURL。html にiframeが含まれているvideo またはrich タイプが必要です。 |
hs_file_url | 文字列 | 未加工のメディアファイルのURL。ソーシャル埋め込み機能をサポートするために後で利用できます。 |
hs_thumbnail_url | 文字列 | コンテンツにメディアを埋め込むためのサムネイルとして使用される画像のURL。このサムネイルの望ましいサイズは640x480ピクセルです。 |
hs_poster_url | 文字列 | メディアを表す画像のURL。この画像は元のメディアと同じ寸法にする必要があり、画像のプレースホルダーが必要な場所で使用することができます(例えば、メディアがEメールに挿入される場合)。 |
hs_external_id | 文字列 | サードパーティーのシステム内のメディアのID。これにより、インテグレーターは自身のシステムで使用しているものと同じIDに基づいて、メディアブリッジからメディアを取得できます。(これは、このマッピングを利用するAPIエンドポイントです)。 |
hs_folder_path | 文字列 | プロバイダー指定のオブジェクトへのパス。サードパーティーのフォルダーシステムにあるオブジェクトの場所(存在する場合)を示すことを目的としています。HubSpotは、これらのオブジェクトをユーザーに表示する際にこのディレクトリー構造を表示しようと試みますが、プロバイダーに関連した名前が付いている最上位フォルダー内で各プロバイダーのオブジェクトとフォルダーをネストする場合があります。 |
hs_title * | 文字列 | メディアの名前。メディアピッカーなどの場所でHubSpot UI内に表示されます。 |
hs_details_page_link | 文字列 | ユーザーがメディアプロバイダーのシステムにあるメディアを表示または操作できるURL。HubSpot UI内で使用され、ユーザーがタイトルのみに頼らずにメディアを識別することを可能にします。 |
IMAGE
メディアオブジェクトの場合に使用できる全てのプロパティーは、以下の表でご確認いただけます。
*でマークされたフィールドは必須です。
パラメーター | 型 | 説明 |
---|---|---|
id | 数値 | HubSpotのメディアブリッジシステム内の特定のメディアを識別するために使用されるID。このIDはHubSpotによって自動生成されます。開発者が設定することはできません。 |
hs_oembed_url * | 文字列 | oEmbedoEmbed仕様に準拠した有効なレスポンスを返す必要があるURL。html にiframeが含まれているvideo またはrich タイプが必要です。 |
hs_file_url * | 文字列 | 未加工のメディアファイルのURL。ソーシャル埋め込み機能をサポートするために後で利用できます。 |
hs_thumbnail_url | 文字列 | メディアピッカーなどの場所にあるコンテンツにメディアを埋め込むためのサムネイルとして使用される画像のURL。このサムネイルの望ましいサイズは640x480ピクセルです。 |
hs_poster_url | 文字列 | メディアを表す画像のURL。この画像は元のメディアと同じ寸法にする必要があり、画像のプレースホルダーが必要な場所で使用することができます(例えば、メディアがEメールに挿入される場合)。 |
hs_external_id | 文字列 | サードパーティーのシステム内のメディアのID。これにより、インテグレーターは自身のシステムで使用しているものと同じIDに基づいて、メディアブリッジからメディアを取得できます。(これは、このマッピングを利用するAPIエンドポイントです)。 |
hs_folder_path | 文字列 | プロバイダー指定のオブジェクトへのパス。サードパーティーのフォルダーシステムにあるオブジェクトの場所(存在する場合)を示すことを目的としています。HubSpotは、これらのオブジェクトをユーザーに表示する際にこのディレクトリー構造を表示しようと試みますが、プロバイダーに関連した名前が付いている最上位フォルダー内で各プロバイダーのオブジェクトとフォルダーをネストする場合があります。 |
hs_title * | 文字列 | メディアの名前。メディアピッカーなどの場所でHubSpot UI内に表示されます。 |
hs_details_page_link | 文字列 | ユーザーがメディアプロバイダーのシステムにあるメディアを表示または操作できるURL。HubSpot UI内で使用され、ユーザーがタイトルのみに頼らずにメディアを識別することを可能にします。 |
メディアを埋め込むためのCMSモジュールの作成
HubSpotのCMSでメディアをレンダリングするためのモジュールは、各メディアブリッジアプリ プロバイダーが作成する必要があります。 メディアブリッジアプリがHubSpotアカウントにインストールされている場合、モジュール上の埋め込みフィールドに、追加の「メディア連携」ソースタイプが示されます。_ _これにより、ユーザーはインストールされたアプリからウェブサイトページに埋め込むメディアを選択できるようになります。 ユーザーが埋め込むメディアを選択すると、メディアのoembed_url
およびoembed_response
がHubLで使用可能になり、プレーヤーを簡単にレンダリングできるようになります。さらに、選択したメディアのid
とmedia_type
が保存され、基盤となるCRMオブジェクトをcrm_objects
HubL関数でクエリーすることが可能になります。これにより、メディアオブジェクトに含まれる全てのプロパティーまたはプロパティーの一部を取得できます。
メディアオブジェクトのIDが459と922の場合のcrm_objects HubL関数の使用例:
{% set objects = crm_objects("a123_Videos", [459,922]) %} {{ objects }}
同じオブジェクトの特定の画像を取得する場合:{% set object = crm_object("a123_Images", 459) %} {{ object }}
アプリではGET
リクエストを/media-bridge/{appId}/settings/object-definitions/{mediaType}
に送信することで、オブジェクトタイプ(この例では「a123_Videos」)を取得できます。
顧客がoAuthを介して接続した後、開発者はCMSソースコードAPIエンドポイントを使用して、カスタム モジュール コードを顧客のアカウントにプッシュする必要があります。モジュールコードが顧客のアカウントにプッシュされると、顧客は開発者が作成したモジュールをコンテンツ内で自動的に使用できるようになります。
oEmbedドメインを設定する
oEmbed HubL関数を使用するには、/media-bridge/v1/{appId}/settings/oembed-domains
にリクエストを送信して、oEmbedレスポンスの取得に使用されるドメインを登録する必要があります。以下のパラメーターが含まれている必要があります。
-
スキーム: メディアURLのURLパターン。このURLパターンは、oEmbed HubL関数に渡されたURLをoEmbed APIと照合するために使用されます。
*
を使用したワイルドカード値を使用できます(例:www.domain.com/*
)。 -
URL: oEmbed APIのURL。メディアは、
URL
パラメーターを使用してこのURLに渡されます。 - Discovery(ブール値): oEmbed APIでoEmbedのDiscovery機能がサポートされるかどうかを決定します。
portalId
値を渡して、oEmbedドメインの使用を許可するアカウントを指定できます。これにより、そのoEmbedドメインを使用できるアカウントが、指定されたHubSpotアカウントのみに制限されます。
カスタムモジュールを作成する
カスタムモジュールを作成するには、次のようにします。- [マーケティング]>[ファイルとテンプレート]>[デザインマネージャー の順に進みます。
- 左上の [ファイル]>[新規ファイル] をクリックします。
- ダイアログボックスで、[今日は何を作成しますか?] ドロップダウンメニューをクリックし、[モジュール] を選択します。
- [次へ] をクリックします。
- モジュールを使用するコンテンツのタイプ([ページ]、[ブログ記事]、[ブログリスト]、[Eメール]、または [引用])の隣にあるチェックボックスをオンにします。Eメールテンプレートで使用されるモジュールに、CSSおよびJavaScriptを含めることはできません。
- このモジュールをローカルモジュールまたはグローバルモジュールのどちらにするかを選択します。グローバルモジュールとして作成した場合、このモジュールのコンテンツを編集すると、モジュールが使用されている全ての場所に変更が反映されます。
- モジュールのファイル名を入力して、[作成] をクリックします。
- 右側の [フィールド] セクションで、[フィールドの追加] ドロップダウンメニューをクリックし、[埋め込み] を選択します。
- [サポートされるソースタイプ] セクションで、[メディアとの連携] を選択します。
- [既定の埋め込みコンテンツ] セクションで、[[メディアブリッジアプリ]から選択] をクリックします。
- 右側のパネルで、モジュールに埋め込むメディアを選択します。
- 必要に応じて、エディターオプション、フィールドの表示条件、フィールドのリピーターオプションを設定します。
- [HubL変数名] で、[コピー]>[スニペットをコピー] をクリックします。
- 「module.html」 セクションにスニペットを貼り付けます。
- ページ上でのモジュールの表示をプレビューするには、[プレビュー] をクリックします。
- 左側のセクションで、[[メディアブリッジアプリ]から選択] をクリックし、プレビューするメディアを選択します。
メディアイベントを送信する
メディアイベントは、メディアオブジェクトに関連して発生するイベント(例:再生イベント)です。メディアブリッジアプリに送信されたメディアイベントは、レポートやタイムラインCRMカードで使用できます。 メディアイベントには次の3種類があります。- 再生イベント: ユーザーがメディアの再生を開始した時間を表します。このイベントはコンタクトのタイムラインとレポートツールの両方で確認できます。
- 四分位数イベント: ユーザーが閲覧しているメディアで、四分位数のマイルストーン(0%、25%、50%、75%、100%)に到達した時間を表します。このイベントはコンタクトタイムラインのみで使用できます。
- 注意持続時間イベント: ユーザーがメディアを完全に消費し終えた時間、またはユーザーがセッションを終了した時間を表します。このイベントはレポートツール内でのみできます。
POST
リクエストを/media-bridge/v2/events/media-played
、/media-bridge/v2/events/media-played-percent
、および/media-bridge/v2/events/attention-span respectively
に送信します。
HubSpotでユーザーのコンタクトタイムラインにメディアイベントを表示するには、セッションごとに再生イベントをメディアブリッジアプリに送信する必要があります。単一のセッションからのイベントは、コンタクトのアクティビティータイムラインで1つのカードに表示されます。
V2イベントエンドポイントを使用して送信されたイベントは、v1エンドポイントを使用して送信されたイベントとは異なり、非同期で処理されます。そのため、以下のようにすることを推奨しています。
- 誤ったリクエストは即座にエラーになるため、v1バージョンのエンドポイントはテストに使用します。
- V2バージョンのエンドポイントは、その非同期性により、イベントがメディアブリッジに書き込まれる間のクライアントの遅延を防ぐのに役立つため、本番環境で使用します。また、メディアブリッジのサーバーに一時的な障害が発生した場合にも、イベントは保持され、再試行されます。
イベントをコンタクトレコードに関連付ける
メディアイベントをコンタクトレコードに関連付けるには、contactId
またはcontactUtk
のいずれかを提供する必要があります。contactUtk
のみが提供された場合は、contactId
に変換されます。リクエストで両方が提供された場合は、contactId
が信頼できる情報源として使用されます。このパラメーターにより、メディアブリッジアプリはコンタクトレコードとイベントの間に関連付けを作成できます。
コンタクトレコードに関連付けられたメディアイベントは、クロスオブジェクトのレポートで使用できます。これにより、お客様はメディアイベントとコンタクトレコード、および関連する会社と取引を関連付けることができます。
イベントをメディアに関連付ける
メディアイベントをメディアに関連付けるには、mediaID
またはexternalID
のいずれかのパラメーターをリクエストに含める必要があります。両方が提供された場合は、mediaID
が信頼できる情報源として使用されます。
注:
HubSpotは、再生イベントおよび四分位数のイベントと、メディアとの関連付けのみをサポートしています。イベントをページに関連付ける
メディアイベントをHubSpotのページに関連付けるには、次のパラメーターをリクエストに含める必要があります。- ページがHubSpot CMSでホスティングされている場合は、
pageId
を提供する必要があります。 - ページがHubSpot CMSでホスティングされていない場合は、
pageName
およびpageUrl
を含める必要があります。
プロパティー | イベントタイプ | 説明 |
---|---|---|
mediaBridgeObjectId | 全てのイベント | このイベントに関連するメディアのID。 |
externalId | 文字列 | サードパーティーのシステム内のメディアのID。これにより、開発者は自身のシステムで使用しているものと同じIDに基づいて、メディアブリッジ内のメディアを参照できます。これは、イベントでmediaBridgeObjectId の代わりに使用できます。externalId とmediaBridgeObjectId の両方が指定された場合は、mediaBridgeObjectId が使用され、externalIdは無視されます。 |
sessionId | 全てのイベント | 表示セッションを表す一意の識別子。プロバイダーによって異なるものを意味する可能性があります。HubSpotは、セッションの定義をプロバイダーに委ねています。この識別子は、同じセッションで発生したイベントをグループ化するために使用されます。サードパーティーのシステムによって生成されることを想定しています。 |
contactId | 全てのイベント | メディアを消費した、HubSpotのシステム内のコンタクトのID。これは、HubSpotのユーザートークン(utk)でコンタクトを取得するAPIを使用して取得できます。APIはユーザートークンの提供もサポートしており、コンタクトIDへの自動変換を処理します。 |
contactUtk | 全てのイベント | メディアを消費したコンタクトを識別するユーザートークン(utk)。 |
pageId | 全てのイベント | イベントが発生したページのコンテンツID。 |
pageName | 全てのイベント | イベントが発生したページの名前またはタイトル。 |
pageUrl | 全てのイベント | イベントが発生したページのURL。 |
occurredTimestamp | 全てのイベント | このイベントが発生した時間のタイムスタンプ(エポックからの経過ミリ秒数)。 |
rawDataString / rawDataMap | 注意持続時間 | メディアのスパンと、ユーザーが各スパンを消費した回数に関する最もきめ細かい情報を提供する未加工データです。例えば、各スパンが1秒である10秒の動画の場合、訪問者が動画の最初の5秒を視聴した後、動画を再生しなおして再び最初の2秒を視聴した場合、結果のrawDataString は、“0=2;1=2;2=1;3=1;4=1;5=0;6=0;7=0;8=0;9=0;” になります。 |
totalPercentPlayed | 注意持続時間 | ユーザーがメディアを消費したパーセンテージ。プロバイダーは、メディアの同じ部分が繰り返し消費された場合をどのように扱うかに応じて、異なる方法でこの値を計算できます。したがって、APIはイベントの注意持続時間の情報に対して、totalPercentWatchedの検証を試みません。このプロパティーがない場合、HubSpotは、注意持続時間マップから(値が1以上のスパンの数)/(スパンの合計数)を計算してこの値を求めます。 |
totalSecondsPlayed | 注意持続時間 | ユーザーがメディアを消費した秒数。メディアブリッジは、totalPercentPlayed *mediaDuration の式でこの値を求めます。プロバイダーが別の計算方法を希望する場合は、イベントの作成時に事前計算済みの値を提供できます。 |
playedPercent | 四分位数イベント | これまでに消費されたメディアの量の四分位数のパーセント値(0、25、50、75、100)。 |
iframeUrl | 再生イベント | iFrameで外部システムからのデータを表示するために使用されるURL。このプロパティーが指定された場合、コンタクトのタイムライン上のイベントに、モーダルウィンドウを開くリンクが表示されます。このリンクをクリックすると、iFrameのコンテンツが表示されます。 |
mediaType | 文字列 | イベントが属するメディアタイプ(例:動画や音声)。単一のプロバイダーが複数のメディアタイプをサポートしている場合、このプロパティーを使用して、イベントを正しいオブジェクトに割り当てることができます。 |