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}
に送信して、メディア オブジェクト プロパティーを作成して変更します。
media_bridge.read
media_bridge.write
https://app.hubspot.com/media-bridge-demo/{HubID}
の{HubID}
をアカウントIDに置き換えてアクセスします。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内で使用され、ユーザーがタイトルのみに頼らずにメディアを識別することを可能にします。 |
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エンドポイントを使用して、カスタム モジュール コードを顧客のアカウントにプッシュする必要があります。モジュールコードが顧客のアカウントにプッシュされると、顧客は開発者が作成したモジュールをコンテンツ内で自動的に使用できるようになります。
/media-bridge/v1/{appId}/settings/oembed-domains
にリクエストを送信して、oEmbedレスポンスの取得に使用されるドメインを登録する必要があります。以下のパラメーターが含まれている必要があります。
*
を使用したワイルドカード値を使用できます(例:www.domain.com/*
)。
URL
パラメーターを使用してこのURLに渡されます。
portalId
値を渡して、oEmbedドメインの使用を許可するアカウントを指定できます。これにより、そのoEmbedドメインを使用できるアカウントが、指定されたHubSpotアカウントのみに制限されます。
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エンドポイントを使用して送信されたイベントとは異なり、非同期で処理されます。そのため、以下のようにすることを推奨しています。
contactId
またはcontactUtk
のいずれかを提供する必要があります。contactUtk
のみが提供された場合は、contactId
に変換されます。リクエストで両方が提供された場合は、contactId
が信頼できる情報源として使用されます。このパラメーターにより、メディアブリッジアプリはコンタクトレコードとイベントの間に関連付けを作成できます。
コンタクトレコードに関連付けられたメディアイベントは、クロスオブジェクトのレポートで使用できます。これにより、お客様はメディアイベントとコンタクトレコード、および関連する会社と取引を関連付けることができます。
mediaID
またはexternalID
のいずれかのパラメーターをリクエストに含める必要があります。両方が提供された場合は、mediaID
が信頼できる情報源として使用されます。
pageId
を提供する必要があります。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 | 文字列 | イベントが属するメディアタイプ(例:動画や音声)。単一のプロバイダーが複数のメディアタイプをサポートしている場合、このプロパティーを使用して、イベントを正しいオブジェクトに割り当てることができます。 |