oEmbed

oEmbedとは? どのように機能しますか?

oEmbedは、コンテンツをウェブサイトに埋め込むための標準フォーマットです。プロバイダーのAPIエンドポイントには、エンドユーザー(コンシューマー)のブラウザーから以下のパラメーターを指定したGETリクエストが送信されます。

  • URL(必須)
  • maxWidth(任意)
  • maxHeight(任意)
  • format(任意)

プロバイダーからは、指定された形式の構造化データが返されます。このデータが、エンドユーザー(コンシューマー)のページでの埋め込みコンテンツの表示に使用されます。oEmbedの詳細については、oEmbed仕様の公式ドキュメントを参照してください。

HubSpotではどのようにoEmbedを使用していますか?

HubSpotでは2つの動画埋め込みモジュール(Eメールおよびページ)、カスタムモジュール用の1つの埋め込みフィールド(メディアURL)、さらにウェブサイトでの埋め込みコンテンツの実装にoEmbedを使用する1つの関数(Eメールのみ)を提供しています。

HubSpotのモジュール内には「メディアURL」フィールドがあります。このフィールドは、前述のoEmbed仕様の「URL」パラメーターに相当します。HubSpotのモジュールは、ここに指定されるURLから、oEmbedレスポンスと呼ばれる情報をリクエストする処理を実行し、サイトで使用できるようにします。

Eメール内でoembed()関数を使用する場合は、URL、最大幅、最大の高さを含むリクエスト文字列を指定するだけです。開発者ドキュメントでこの関数の例を参照できます。

oEmbedレスポンスについて

oEmbedレスポンスは、プロバイダー(YouTube、Flickr、およびoEmbedに対応しているその他のプロバイダー)によって返されるJSONデータです。レスポンスのパラメーターについては、oEmbedドキュメントのセクション2.3.4で確認できます。レスポンスタイプ(photo、video、link、rich)ごとに固有のパラメーターが関連付けられています。

YouTubeからのoEmbedレスポンスの例を次に示します。この例では、タイプがvideoで、ウェブサイトへの動画プレイヤーの埋め込みに使用可能なコードを返すHTMLパラメーターが含まれていることが分かります。

// oEmbed Response from YouTube { "title" : "HubSpot Themes Challenge Workshop - Oct 1, 2020", "author_name" : "HubSpot Developers", "author_url" : "https://www.youtube.com/channel/UCT4M2Uw9rBDpa3JcKaz5UMQ", "type" : "video", "height" : 113, "width" : 200, "version" : "1.0", "provider_name" : "YouTube", "provider_url" : "https://www.youtube.com/", "thumbnail_height" : 360, "thumbnail_width" : 480, "thumbnail_url" : "https://i.ytimg.com/vi/Y4v6cKm2wqE/hqdefault.jpg", "html" : "<iframe width=\"200\" height=\"113\" src=\"https://www.youtube.com/embed/Y4v6cKm2wqE?feature=oembed\" frameborder=\"0\" allow=\"accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture\" allowfullscreen></iframe>" }

モジュールでの埋め込みフィールドの推奨される使用法

Eメール専用モジュール

モジュールがEメール専用の場合に埋め込みフィールドを使用するには、埋め込みフィールドとoembed()関数を組み合わせて使用することをお勧めします。次にこの使用例を示します。

{{ oembed({ url: module.embed_field.oembed_url}) }}

この関数は、指定されたurlに対するoEmbedレスポンスのパラメーターを含むディクショナリー(辞書型)を返します。個々のパラメーターには、ドット表記を使用してアクセスできます。

YouTubeの動画をメディアurlソースとして使用する例を以下に示します。

// gets the html code for embedding {{ oembed({ url: module.embed_field.oembed_url}).html }} // gets the video title {{ oembed({ url: module.embed_field.oembed_url}).title }} // gets the thumbnail URL of the video {{ oembed({ url: module.embed_field.oembed_url}).thumbnailURL }} //gets the author name {{ oembed({ url: module.embed_field.oembed_url}).authorName }}

ページまたはブログのモジュール

モジュールがページまたはブログ内で使用されている場合、JavaScriptを使用してoEmbedレスポンスを取得することをお勧めします。この方法が推奨される理由は、埋め込みフィールドを使用して結果を取得する際に、HubSpot側で結果がキャッシュされ、oEmbedデータが時間の経過と共に古くなる可能性があるためです。

JavaScriptを使用してoEmbedレスポンスの結果を取得する例を示します。この方法では結果が古くなる(キャッシュされる)ことがありません。 

注:これらは全て、カスタムモジュールのHTML + HubLセクションで行われます。また、モジュールコード開始時の条件に基づいて正しいCSSとJavaScriptを適切なエリアに配置するために、タグが使用されます。

{% if module.embed_field.source_type == "oembed" %} <div class="oembed_container {% if module.embed_field.size_type == 'auto_full_width' %} oembed_container--full-size{% endif %}" id="oembed_container-{{name}}"> <div class="iframe_wrapper" data-embed-url="{{ module.embed_field.oembed_url }}" {% unless module.embed_field.size_type == "auto_full_width" || module.embed_field.size_type == "exact" %} data-max-height="{% if module.embed_field.size_type == "auto_custom_max" %}{{ module.embed_field.max_height }}{% endif %}" data-max-width="{% if module.embed_field.size_type == "auto_custom_max" %}{{ module.embed_field.max_width }}{% endif %}" {% endunless %} {% if module.embed_field.size_type == "exact" %} data-height="{{ module.embed_field.height }}" data-width="{{ module.embed_field.width }}" {% endif %} > </div> </div> {% require_css %} <style> .oembed_container { display: inline-block; height: 100%; position: relative; width: 100%; } .oembed_container .iframe_wrapper > * { height: 100%; left: 0; margin: 0 auto; position: absolute; right: 0; top: 0; width: 100%; } .iframe_wrapper { height: 0; padding-bottom: 56.25%; padding-top: 25px; position: relative; } </style> {% end_require_css %} {% require_js %} <script> const oembedContainer = document.querySelector('.oembed_container'); const iframeWrapper = document.querySelector('.iframe_wrapper'); const url = iframeWrapper.dataset.embedUrl; if (url) { var request = new XMLHttpRequest(); var requestUrl = "/_hcms/oembed?url=" + url + "&autoplay=0"; request.open('GET', requestUrl, true); request.onload = function() { if (request.status >= 200 && request.status < 400) { var data = JSON.parse(request.responseText); const maxHeight = iframeWrapper.dataset.maxHeight !== undefined && !iframeWrapper.dataset.maxHeight ? data.height : iframeWrapper.dataset.maxHeight; const maxWidth = iframeWrapper.dataset.maxWidth !== undefined && !iframeWrapper.dataset.maxWidth ? data.width : iframeWrapper.dataset.maxWidth; const height = iframeWrapper.dataset.height !== undefined && !iframeWrapper.dataset.height ? data.height : iframeWrapper.dataset.height; const width = iframeWrapper.dataset.width !== undefined && !iframeWrapper.dataset.width ? data.width : iframeWrapper.dataset.width; const el = document.createElement('div'); el.innerHTML = data.html; const iframe = el.firstChild; iframeWrapper.appendChild(iframe); if (maxHeight) { const heightStr = maxHeight.toString(10) + "px"; oembedContainer.style.maxHeight = heightStr; iframe.style.maxHeight = heightStr; } if (maxWidth) { const widthStr = maxWidth.toString(10) + "px"; oembedContainer.style.maxWidth = widthStr; iframe.style.maxWidth = widthStr; } if (height) { const heightStr = height.toString(10) + "px"; oembedContainer.style.height = heightStr; iframe.style.height = heightStr; } if (width) { const widthStr = width.toString(10) + "px"; oembedContainer.style.width = widthStr; iframe.style.width = widthStr; } } else { console.error('Server reached, error retrieving results.'); } }; request.onerror = function() { console.error('Could not reach the server.'); }; request.send(); } </script> {% end_require_js %} {% else %} <div id="embed_container" class="embed_container"> <div class="iframe_wrapper"> {{ module.embed_field.embed_html }} </div> </div> {% require_css %} <style> .iframe_wrapper { height: 0; padding-bottom: 56.25%; padding-top: 25px; position: relative; } .embed_container { display: inline-block; height: 100%; position: relative; width: 100%; } .embed_container iframe { left: 0; max-height: 100%; max-width: 100%; position: absolute; right: 0; top: 0; } </style> {% end_require_css %} {% endif %}

Eメールおよびページ(またはブログ)のモジュール:

モジュールをページやブログと共にEメールにも使用している場合、oembed_responseオブジェクトを使用することもできます。URLが[メディアURL]フィールドに入力されて取り込まれると、このデータはoembed_responseオブジェクトでの使用のためにHubSpot側でキャッシュされます。oembed_responseディクショナリーの表示方法の例を以下に示します。

// outputs the oembed response {{ module.embed_field.oembed_response }}

ドット表記を使用してディクショナリーの子要素を取得できます。例えば、YouTubeの動画をソースとして使用する場合は以下のように処理できます。

// gets the html code for embedding {{ module.embed_field.oembed_response.html }} //outputs the title {{ module.embed_field.oembed_response.title }} // outputs the authors name {{ module.embed_field.oembed_response.author_name }} //outputs the thumbnail url (for use in the <img> tag) {{ module.embed_field.oembed_response.thumbnail_url }}

キャッシュされたoembed_responseのデータを更新するには、メディアURLを変更(1つの文字を削除して、再び追加)し、変更をモジュールに再適用します。

動画埋め込みモジュールと埋め込みフィールドのトラブルシューティング

「メディアURL」リンクを動画埋め込みモジュールまたは埋め込みフィールドに追加する際には、次のようなエラーが発生することがあります。 

「共有用にこのメディアURLを埋め込むことはできません。」

このエラーが発生した場合は、プロバイダーにいくつかの事項を確認します。

  • アセットプロバイダーのプラットフォームでoEmbed機能が提供されているか?oEmbedの公式ドキュメントには、この仕様に対応しているプロバイダーのリストが記載されています。また、プロバイダーに直接連絡して対応状況を確かめることもできます。
  • URLは「非公開」か?多くのプラットフォームでは、ユーザーがコンテンツを非公開にできます。例えば、Instagramのアカウントが非公開の場合、投稿が公開されている(ユーザーによるプラットフォームへのサインインや、フォロワー/フレンドの関係性を必要としない)状態でなければ、そのコンテンツを埋め込むことはできません。

oEmbedのHTTPステータスコード

oEmbed仕様に従って定義されているステータスコードを以下に示します。

  • 404 Not Found:リクエストされたURLのレスポンスがありません。
  • 501 Not Implemented:リクエストされたレスポンス形式を返すことができません。
  • 401 Unauthorized:リクエストされたURLに非公開のリソースが含まれています。

HubSpotは、サードパーティープロバイダーによるステータスコードの実装状況、またはoEmbed仕様への準拠状況に直接関与する立場にはありません。このためHubSpotでは、該当する場合には404エラーを返し、それ以外の場合は400ステータスコードまたは前述の内容に類似したメッセージを返します。メッセージは、レスポンスオブジェクトのmessageプロパティーに格納されます。


参考になりましたか?
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。