重要提示:此文件不適用於您目前選取的廣告格式!
amp-video-iframe
描述
嵌入包含影片播放器的 iframe。
必要腳本
<script async custom-element="amp-video-iframe" src="https://cdn.ampproject.org/v0/amp-video-iframe-0.1.js"></script>
我應該在何時使用它?
如果您已建立自己的 Javascript 影片播放器,並想要將其嵌入 AMP 文件中,或者您的播放器是由 AMP 元件函式庫不支援的第三方提供,則此元件非常有用。
-
如果您想直接在 AMP 文件中加入影片,則應使用
amp-video
。 -
如果您使用常見的第三方,例如 Youtube、Vimeo 或 AMP 支援的其他服務,則應使用他們支援的元件 (例如
amp-youtube
、amp-vimeo
)。 -
如果您已建立自訂播放器,或使用不受支援的第三方提供的播放器,則應使用
amp-video-iframe
。這與使用amp-iframe
不同,因為它可以在 AMP 上啟用影片功能。有關更多詳細資訊,請參閱下方的行為。 -
如果您是第三方影片供應商,則可以使用
amp-video-iframe
為作者提供一種簡單的影片嵌入方式。
行為
amp-video-iframe
與原始 iframe 和 amp-iframe
有幾個重要的差異。
-
預設情況下,
amp-video-iframe
是沙箱化的。 -
amp-video-iframe
實作了所有影片功能,例如自動播放、最小化至角落和旋轉至全螢幕。 -
amp-video-iframe
僅能透過 HTTPS 要求資源。 -
amp-video-iframe
不可捲動。
簡而言之,amp-video-iframe
將 AMP 影片功能插入到託管影片播放器的嵌入式文件中。
將 amp-video-iframe 用於廣告
amp-video-iframe
不得用於顯示廣告的主要目的。為了顯示影片的目的而使用 amp-video-iframe
是可以的,其中部分影片是廣告。此 AMP 政策可能會透過不呈現各自的 iframe 來強制執行。
廣告使用案例應改用 amp-ad
。
此政策的原因是:
-
amp-video-iframe
強制執行沙箱化,並且沙箱也適用於子 iframe。這表示到達頁面可能會損壞,即使廣告本身似乎可以運作。 -
amp-video-iframe
沒有受控制的大小調整機制。
屬性
src (必填) | src 屬性的行為主要與標準 iframe 類似,但有一個例外:#amp=1 片段會新增至 URL,讓來源文件知道它們已嵌入在 AMP 環境中。只有在 src 指定的 URL 尚未有片段時,才會新增此片段。 |
預覽圖 | 影片載入時顯示的圖片網址。建議您務必設定此屬性,以獲得最佳的感知效能。 |
自動播放 | 如果存在此屬性,且瀏覽器支援自動播放,則影片會在可見時立即自動播放。元件需要滿足一些條件才能播放,這些條件已在 AMP 影片規格中概述。 |
通用屬性 | 此元素包含擴充至 AMP 元件的通用屬性。 |
停駐 | 需要 amp-video-docking 擴充功能。 如果存在此屬性,且影片為手動播放,則當使用者捲動離開影片元件的可視區域時,影片會「最小化」並固定在角落或元素上。如需更多詳細資訊,請參閱停駐擴充功能本身的說明文件。 |
實作媒體工作階段 | 如果 iframe 內的文件獨立實作了 MediaSession API,請設定此屬性。 |
實作旋轉至全螢幕 | 如果 iframe 內的文件獨立實作了旋轉至全螢幕,請設定此屬性。 |
參照網址政策 | 要在 iframe 元素上設定的 referrerpolicy 。 |
data-param-* | 所有 data-param-* 屬性都會新增為 iframe src 的查詢參數。它們可用於將自訂值傳遞到播放器文件。鍵和值將會進行 URI 編碼。鍵將會使用駝峰式命名。
|
用法
在您的 AMP 文件中加入 amp-video-iframe
<amp-video-iframe layout="responsive" width="16" height="9" src="/my-video-player.html" poster="/my-video-poster.jpg" > </amp-video-iframe>
my-video-player.html
是載入到框架內播放影片的內部文件。此文件必須包含並引導整合腳本,以便包含 <amp-video-iframe>
的 AMP 文件可以協調影片的播放。
第三方影片供應商
如果您是不提供自訂影片播放器元件的供應商,則可以使用 amp-video-iframe 配置的形式與 AMP 整合,以便作者可以嵌入透過您的服務提供的影片。
作為供應商,您可以提供一個通用整合文件,該文件透過 URL 參數參照提供的影片。使用您影片服務的 AMP 作者只需要在其文件中包含 <amp-video-iframe>
標籤
<!-- data-param-* attributes are added to src and poster, so this would use the following composed urls: src: https://vendor.example/amp-video-iframe ?videoid=MY_VIDEO_ID &channelid=MY_CHANNEL_ID poster: https://vendor.example/poster.jpg ?videoid=MY_VIDEO_ID &channelid=MY_CHANNEL_ID --> <amp-video-iframe layout="responsive" width="16" height="9" src="https://vendor.example/amp-video-iframe" poster="https://vendor.example/poster.jpg" data-param-videoid="MY_VIDEO_ID" data-param-channelid="MY_CHANNEL_ID" > </amp-video-iframe>
src
和 poster
URL 會附加 data-param-*
屬性作為查詢字串。
/amp-video-iframe
文件會引導整合腳本,以便 AMP 文件可以與播放器協調。
框架內的整合
為了使影片整合能夠運作,嵌入式文件 (例如 my-video-player.html
) 必須包含一個小型函式庫
<script async src="https://cdn.ampproject.org/video-iframe-integration-v0.js" ></script> <!-- Wait for API to initialize --> <script> (window.AmpVideoIframe = window.AmpVideoIframe || []).push( onAmpIntegrationReady ); function onAmpIntegrationReady(ampIntegration) { // `ampIntegration` is an object containing the tools required to integrate. // This callback specifies how the AMP document and the iframed video document // talk to each other. // YOU NEED TO IMPLEMENT THIS. See below. } </script>
請注意,此函式庫與擴充功能程式碼 (amp-video-iframe-0.1.js
) 是分開的,因為它位於非 AMP 文件 (iframe) 上。
提供的回呼函式指定了 AMP 文件和 iframe 影片文件如何相互通訊。您需要實作一組播放方法和事件分派器,將這些方法和分派器組合在一起。對於常見的影片框架,整合腳本提供了現成的播放支援,但如果您未使用任何支援可用的工具,也可以自行編寫自訂整合。
amp-video-iframe
標籤與 autoplay
屬性搭配使用。AMP 元件會自動將必要的訊號傳送至您的 iframe 以進行自動播放,以獲得更好的使用者體驗。現成整合
如果您使用常見的影片框架,例如 JW Player 或 Video.js,則可以呼叫 listenTo()
進行基本、現成的整合。當框架提供這些整合時,這些整合支援所有播放和 UI 控制項,請參閱每個整合以了解支援的方法。
listenTo
方法。請繼續閱讀以下特定 API。
適用於 JW Player
預設支援的事件: ad_end
/ad_start
、canplay
、error
、muted
/unmuted
、pause
/playing
預設支援的方法: pause
/play
、mute
/unmute
、hidecontrols
/showcontrols
、fullscreenenter
/fullscreenexit
amp
物件知道如何使用 listenTo('jwplayer')
設定 JwPlayer 實例。如果您使用特定於影片的腳本嵌入播放器,則只需要註冊 Jwplayer 用法
<script src="https://cdn.jwplayer.com/players/UVQWMA4o-kGWxh33Q.js"></script> <script> (window.AmpVideoIframe = window.AmpVideoIframe || []).push(function ( ampIntegration ) { ampIntegration.listenTo('jwplayer'); }); </script>
否則,請透過簽章 amp.listenTo('jwplayer', instance)
傳入您的 JwPlayer 實例
(window.AmpVideoIframe = window.AmpVideoIframe || []).push(function ( ampIntegration ) { ampIntegration.listenTo('jwplayer', jwplayer('my-video')); });
適用於 Video.js
預設支援的事件: canplay
、ended
、muted
/unmuted
、pause
/playing
預設支援的方法: pause
/play
、mute
/unmute
、hidecontrols
/showcontrols
、fullscreenenter
/fullscreenexit
透過簽章 ampIntegration.listenTo('videojs', myVideo)
傳入您的 <video>
元素。Video.js 會重載此元素,以提供 ampIntegration
物件用來設定播放器的方法。
function onAmpIntegrationReady(ampIntegration) { var myVideo = document.querySelector('#my-video'); ampIntegration.listenTo('videojs', myVideo); }
如果需要,listenTo
會在 <video>
元素上初始化 Video.js 實例。預設情況下,這會使用全域 videojs
函數。如果您的頁面以不同的方式提供初始化程式,則必須將其作為第三個引數傳入
function onAmpIntegrationReady(ampIntegration) { var myVideo = document.querySelector('#my-video'); // ampIntegration initializes player with `myVideojsInitializer(myVideo)` ampIntegration.listenTo('videojs', myVideo, myVideojsInitializer); }
自訂整合
如果您未使用任何預設支援的影片框架,則必須編寫自訂實作才能與 AMP 的影片管理進行通訊。
這些是可用的通訊方法
method
來控制播放。postEvent
來通知主機文件有關播放事件。getIntersection
來取得影片在主機文件上的可見度。getMetadata
來取得有關主機文件的資訊。
如果您使用支援的框架,則可以使用這些相同的方法來更精細地控制預設實作。
method(name, callback)
實作一個在影片上呼叫播放功能的方法。例如
ampIntegration.method('play', function () { myVideo.play(); });
這些是應該實作的方法
play
pause
mute
unmute
showcontrols
hidecontrols
fullscreenenter
fullscreenexit
您可以選擇僅部分實作此介面,但有一些注意事項
-
play
和pause
是播放動作或自動播放的任一項/兩者都需要的。 -
mute
和unmute
是自動播放需要的。 -
showcontrols
和hidecontrols
是為了獲得最佳使用者體驗所必需的。例如,當將影片最小化到角落時,會顯示自訂控制項覆疊。如果您未提供隱藏和顯示控制項的方法,則可能會同時顯示兩組控制項,這會造成不良的使用者體驗。 -
fullscreenenter
和fullscreenexit
是為了獲得最佳使用者體驗所必需的。例如,對於rotate-to-fullscreen
或最小化影片上的全螢幕按鈕。
postEvent(name)
將播放事件發佈到框架。例如
myVideoElement.addEventListener('pause', function () { ampIntegration.postEvent('pause'); });
有效事件如下。
事件 | 描述 |
canplay | 當您的播放器準備就緒時觸發。必須在播放器可以互動之前發佈此事件。 |
playing | 當您的播放器在載入或暫停後開始播放影片時觸發。 |
pause | pause |
當您的影片已暫停時觸發。 | ended |
當您的影片已結束播放時觸發。請注意,您也必須在 | muted |
當您的影片已靜音時觸發。 | unmuted |
當您的影片已取消靜音時觸發。 | ad_start |
當前/中/後置廣告正在播放時觸發。這會隱藏影片上顯示的自動播放墊片。 | ad_end |
當前/中/後置廣告已結束時觸發。如果使用者尚未與影片互動,這會重新顯示自動播放墊片。
postAnalyticsEvent(eventType[, vars])
發佈自訂分析事件,供 amp-analytics
使用。eventType
必須以 video-custom-
作為前綴,以防止與其他分析事件類型發生命名衝突。
此方法採用一個選用的 vars
參數,該參數應定義一個包含要記錄的自訂變數的物件。這些變數以 VIDEO_STATE
的形式提供,並以 custom_
為前綴的名稱作為鍵,即物件 {myVar: 'foo'}
將以 {'custom_myVar': 'foo'}
的形式提供。
amp-consent
時,iframe 文件可以要求使用者同意資料。如果您只需要在未給予同意時阻止 iframe 載入,則最好設定 data-block-on-consent
屬性,而不是呼叫 getConsentData()
{ "consentMetadata": { "consentStringType": 2, "additionalConsent": "additional-consent-string", "gdprApplies": true, "purposeOne": true }, "consentString": "accept-string", "consentPolicyState": 1, "consentPolicySharedData": { "tfua": true, "coppa": true } }
consentPolicySharedData
// Create and listen to video once consent is given on the parent page: integration.getConsentData(function(consent) { if ( consent.consentPolicyState !== /* SUFFICIENT */ 1 && consent.consentPolicyState !== /* UNKNOWN_NOT_REQUIRED */ 3 ) { integration.postEvent('error'); return; } // You can use other consent values to map video consent logic as well. console.log(consent); // Initialize video and integration once consent is available. var video = document.createElement(video); video.style = "width: 100vw; height: 100vh"; video.src = document.body.getAttribute('data-videoid'); document.body.appendChild(video); integration.method('play', function() { video.play(); }); // etc... });
例如,可以阻止影片載入,直到 consentPolicyState
可用為止
也提供了一個使用 getConsentData
的完整範例。
// Will log intersection every 2 seconds setInterval(function () { integration.getIntersection(function (intersection) { console.log('Intersection ratio:', intersection.intersectionRatio); }); }, 2000);
取得影片元素的交集比率(介於 0 和 1 之間)。這對於可見度資訊很有用,例如
{"time": 33333.33, "intersectionRatio": 0.761}
傳遞給函數的 callback
將會使用看起來像這樣的物件執行
⚠ 這應被視為低精確度的讀取。目前,只要影片的可見度低於 50%,intersectionRatio
的值就會為 0。此值隨時可能會變更,並且回呼可能會延遲或去抖動。
{ "canonicalUrl": "https://example.com/canonical.html", "sourceUrl": "https://example.com/amp.html", "title": "My host document's title", "lang": "en" }
-
傳回包含有關主機文件元資料的物件
-
canonicalUrl
是標準網址。 -
sourceUrl
是 AMPHTML 網址。 -
title
是<amp-video-iframe>
初始化時來源網址的文件標題。當元件載入到 shadow root 中時為null
。 -
lang
是<html ⚡️ lang="en">
中指定的來源網址的語言。當元件載入到 shadow root 中時為null
。
jsonLd
包含 JSON-LD 標籤的已剖析內容 (如果存在)。 需要更多協助嗎?
您已經閱讀此文件十幾次了,但它仍然沒有涵蓋您的所有問題嗎?也許其他人也有同樣的感覺:在 Stack Overflow 上與他們聯繫。 前往 Stack Overflow發現錯誤或缺少功能嗎?
AMP 專案強烈鼓勵您的參與和貢獻!我們希望您能成為我們開放原始碼社群的持續參與者,但我們也歡迎針對您特別熱衷的問題的一次性貢獻。