CMS API | メディアブリッジ

メディアブリッジAPIを使用すると、インテグレーターは動画や音声ファイルなどのメディアオブジェクトとメディア消費データをHubSpotにプッシュできます。また、ユーザーのHubSpotアカウントで以下の機能が利用できるようになります。

• HubSpotのドラッグ＆ドロップエディターでページやEメールにメディアオブジェクトを埋め込むためのモジュール。
• プロスペクトまたは顧客が動画、音声、およびその他のメディアタイプを操作したときに表示されるCRMタイムラインイベント。
• ターゲットを絞り込み、パーソナライズされた体験を提供するためのセグメント化されたリスト。
• メディア消費イベントに基づいてインタラクションを自動化するワークフロー。
• メディアアセットの効果を測定するためのレポート。

メディアブリッジはカスタムオブジェクトと統合イベント（HubSpotのイベント トラッキング システム）の両方を使用します。つまり、メディアブリッジAPIとカスタムオブジェクトAPIの両方を使用して、連携を構築できます。

​

メディアブリッジ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アカウントに対するスコープ。

メディアブリッジアプリをHubSpotユーザーのアカウントに関連付けるには、次のようにします。

• メディアブリッジアプリの開発者アカウントで、アプリケーション定義を作成します。
• アプリケーションを定義する際には、以下のスコープを含めます。
  • media_bridge.read
  • media_bridge.write
• アプリからの呼び出しを認証する際は、OAuth認証を使用します。認証方式の詳細をご確認ください。

顧客のHubSpotアカウントにアプリが正しくインストールされたことを確認するには、次の手順に従います。

• https://app.hubspot.com/media-bridge-demo/{HubID}の{HubID}をアカウントIDに置き換えてアクセスします。
• 右上の［アプリ］ドロップダウンメニューをクリックし、ご使用のメディアブリッジアプリを選択します**。 **
• アプリでは、アプリでサポートされるメディアタイプの確認や、サンプルメディアの作成ができます。

メディアブリッジアプリが顧客のHubSpotアカウントにインストールされたら、以下のことを行えるようになります。

• メディアオブジェクトを作成する
• メディアオブジェクトを埋め込むためのCMSモジュールを作成する
• メディアイベントを送信する

​

メディアオブジェクトを作成する

メディアオブジェクトの定義を作成し、メディアブリッジアプリをユーザーのアカウントにインストールしたら、OAuthトークンを使用して、アカウントでメディアオブジェクトを作成し、変更できるようになります。メディアオブジェクトはカスタムオブジェクトなので、カスタムオブジェクトAPIエンドポイントを使用して作成します。

• GETリクエストを/media-bridge/v1/{appId}/settings/object-definitions/{mediaType}に送信して、objectTypeを見つけます。
• POSTリクエストを/crm/v3/objects/{objectType}に送信して、ユーザーのアカウントにメディアオブジェクトを作成します。

メディアオブジェクトは、サードパーティーのシステム内の埋め込み可能なコンテンツを表します。メディアブリッジに追加したメディアオブジェクトは、HubSpotのCMSコンテンツに埋め込み、メディアイベントと関連付けることができます。 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機能がサポートされるかどうかを決定します。

既定では、登録されたoEmbedドメインは、アプリをインストールした全てのお客様が使用できるようになります。お客様ごとに固有のカスタムドメインがある場合は、oEmbedドメインを設定するときに、APIリクエストに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 CMSでホスティングされている場合は、pageIdを提供する必要があります。
• ページがHubSpot CMSでホスティングされていない場合は、pageNameおよびpageUrlを含める必要があります。

3つのメディアイベントでサポートされているプロパティーの概要を次の表に示します。

プロパティー	イベントタイプ	説明
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	文字列	イベントが属するメディアタイプ（例：動画や音声）。単一のプロバイダーが複数のメディアタイプをサポートしている場合、このプロパティーを使用して、イベントを正しいオブジェクトに割り当てることができます。