メディアブリッジAPI

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

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

メディアブリッジはカスタムオブジェクトと統合イベント（HubSpotのイベント トラッキング システム）の両方を使用します。つまり、メディアブリッジ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}に送信します。 

全てのAPI呼び出しには、ご使用の開発者アカウントIDがportalIDクエリーパラメーターとして含められます。 

メディア ブリッジ アプリをHubSpotユーザーのアカウントに関連付けるには、HubSpot開発者のアカウントでそのためのアプリ定義を作成する必要があります。アプリの定義には、以下の情報を含めます。

• 連携でHubSpotユーザーのアカウントに対して最初に関連付けを行う際に、ユーザーに表示されるロゴやテキストなどの詳細。
• 連携で必要となる、ユーザーのHubSpotアカウントに対するスコープ。 

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

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

お客様のポータルにアプリが正しくインストールされたことを確認するには、次のようにします。

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

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

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

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

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

メディアオブジェクトは、サードパーティーのシステム内の埋め込み可能なコンテンツを表します。メディアブリッジに追加したメディアオブジェクトは、HubSpotの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 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パラメーターを使用してこの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に送信します。 

HubSpotでユーザーのコンタクトタイムラインにメディアイベントを表示するには、セッションごとに再生イベントをメディア ブリッジ アプリに送信する必要があります。単一のセッションからのイベントは、コンタクトのアクティビティータイムラインで1つのカードに表示されます。 

v2イベントエンドポイントを使用して送信されたイベントは、v1エンドポイントを使用して送信されたイベントとは異なり、非同期で処理されます。そのため、以下のようにすることを推奨しています。

• 誤ったリクエストは即座にエラーになるため、v1バージョンのエンドポイントはテストに使用します。
• v2バージョンのエンドポイントは、その非同期性により、イベントがメディアブリッジに書き込まれる間のクライアントの遅延を防ぐのに役立つため、本番環境で使用します。また、メディアブリッジのサーバーに一時的な障害が発生した場合にも、イベントは保持され、再試行されます。

メディアイベントをコンタクトレコードに関連付けるには、contactIdまたはcontactUtkのいずれかを提供する必要があります。contactUtkのみが提供された場合、contactIdに変換されます。リクエストで両方が提供された場合は、contactIdが情報源として使用されます。このパラメーターにより、メディア ブリッジ アプリはコンタクトレコードとイベントの間に関連付けを作成できます。

コンタクトレコードに関連付けられたメディアイベントは、クロスオブジェクトのレポートで使用できます。これにより、お客さまはメディアイベントとコンタクトレコード、および関連する会社と取引を関連付けることができます。

メディアイベントをメディアに関連付けるには、mediaIDまたはexternalIDのいずれかのパラメーターをリクエストに含める必要があります。両方が提供された場合は、mediaIDが情報源として使用されます。

メディアイベントをHubSpotのページに関連付けるには、次のパラメーターをリクエストに含める必要があります。

• ページがHubSpot CMSでホスティングされている場合は、pageIdを提供する必要があります。
• ページがHubSpot CMSでホスティングされていない場合は、pageNameおよびpageUrlを含める必要があります。

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