AMP

重要事項:此文件不適用於您目前選取的格式 stories

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 元件程式庫不支援的第三方所提供,則此元件非常有用。

  1. 如果您想要將影片直接包含在 AMP 文件中,則應使用 amp-video

  2. 如果您使用的是常見的第三方,例如 Youtube、Vimeo 或 AMP 中支援的其他服務,則應使用其支援的元件 (例如 amp-youtubeamp-vimeo)。

  3. 如果您已建置自訂播放器,或是使用不受支援的第三方所提供的播放器,您應使用 amp-video-iframe。這與使用 amp-iframe 不同,因為它在 AMP 上啟用了影片功能。請參閱下方的 行為 以取得更多詳細資訊。

  4. 如果您是第三方影片供應商則可以使用 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 尚未具有片段時,才會新增此片段。
poster 影片載入時顯示的圖片 URL。建議您務必設定此屬性,以獲得最佳感知效能。
autoplay 如果存在此屬性,且瀏覽器支援自動播放,則影片會在可見時立即自動播放。元件需要符合一些條件才能播放,這些條件在 AMP 規格中的影片中概述
通用屬性 此元素包含延伸至 AMP 元件的通用屬性
dock 需要 amp-video-docking 擴充功能。如果存在此屬性且影片是手動播放,則當使用者捲動離開影片元件的可視區域時,影片會「最小化」並固定在角落或元素上。如需更多詳細資訊,請參閱 docking 擴充功能本身的說明文件。
implements-media-session 如果 iframe 內的文件獨立實作 MediaSession API,請設定此屬性。
implements-rotate-to-fullscreen 如果 iframe 內的文件獨立實作 rotate-to-fullscreen,請設定此屬性。
referrerpolicy 要在 iframe 元素上設定的 referrerpolicy
data-param-* 所有 data-param-* 屬性都會新增為查詢參數至 iframe 的 src。它們可用於將自訂值傳遞至播放器文件。
金鑰和值將會進行 URI 編碼。金鑰將會使用駝峰式命名。
  • data-param-foo="bar" 會變成 &foo=bar
  • data-param-channel-id="SOME_VALUE" 會變成 &channelId=SOME_VALUE

用法

在您的 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 整合,以便作者可以嵌入透過您的服務提供的影片。

對於大多數影片供應商而言,amp-video-iframe 提供了足夠的工具來執行常見的播放動作 (請參閱方法事件)。請參閱供應商播放器規格,以取得關於您是否可以使用 amp-video-iframe 或應改為建置第三方播放器元件的更多詳細資訊。

作為供應商,您可以提供一般整合文件,該文件透過 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>

srcposter URL 會附加data-param-* 屬性作為查詢字串

/amp-video-iframe 文件會啟動整合指令碼,以便 AMP 文件可以與播放器協調。

如果您是託管整合文件的供應商,請隨時在此頁面中貢獻程式碼範例,並指定您提供的 src 和可用的 data-param-* 屬性。

框架內的整合

為了讓影片整合能夠運作,嵌入的文件 (例如 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 PlayerVideo.js,則可以呼叫 listenTo() 以進行基本、現成的整合。當框架提供所有播放和 UI 控制項時,這些整合支援所有播放和 UI 控制項,請參閱每個整合以瞭解支援的方法。

根據您使用的影片框架,您會以不同的方式呼叫 listenTo 方法。請繼續閱讀下方的特定 API。

如果您需要現成實作中沒有的功能,則可以額外使用自訂整合方法

適用於 JW Player

預設支援的事件: ad_end/ad_startcanplayerrormuted/unmutedpause/playing

預設支援的方法: pause/playmute/unmutehidecontrols/showcontrolsfullscreenenter/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

預設支援的事件: canplayendedmuted/unmutedpause/playing

預設支援的方法: pause/playmute/unmutehidecontrols/showcontrolsfullscreenenter/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(name, callback)

實作一種方法,該方法會呼叫影片上的播放功能。例如

ampIntegration.method('play', function () {
  myVideo.play();
});

這些是應該實作的方法

  • play
  • pause
  • mute
  • unmute
  • showcontrols
  • hidecontrols
  • fullscreenenter
  • fullscreenexit

您可以選擇僅部分實作此介面,但有一些注意事項

  • playpause 是播放動作或自動播放的必要條件。

  • muteunmute 是自動播放的必要條件。

  • showcontrolshidecontrols 是獲得最佳 UX 的必要條件。例如,當將影片最小化至角落時,會顯示自訂控制項疊加層。如果您未提供隱藏和顯示控制項的方法,則可能會同時顯示兩組控制項,這會造成不良的使用者體驗。

  • fullscreenenterfullscreenexit 是獲得最佳 UX 的必要條件。例如,適用於 rotate-to-fullscreen 或最小化影片上的全螢幕按鈕。

postEvent(name)

將播放事件發佈到框架。例如

myVideoElement.addEventListener('pause', function () {
  ampIntegration.postEvent('pause');
});

有效事件如下。

事件 說明
canplay 當您的播放器準備就緒時觸發。必須先發佈此事件,播放器才能變成互動式。
playing 當您的播放器在載入或暫停後開始播放影片時觸發。
pause 當您的影片已暫停時觸發。
ended 當您的影片已結束播放時觸發。請注意,您也必須在 ended 事件旁邊發佈 pause 事件。
muted 當您的影片已靜音時觸發。
unmuted 當您的影片已取消靜音時觸發。
ad_start 當播放前/中/後廣告時觸發。這會隱藏影片上顯示的自動播放墊片。
ad_end 當播放前/中/後廣告結束時觸發。如果使用者尚未與影片互動,這會重新顯示自動播放墊片。

postAnalyticsEvent(eventType[, vars])

發佈自訂分析事件以供 amp-analytics 使用。eventType 必須以 video-custom- 為字首,以防止與其他分析事件類型發生命名衝突。

此方法採用選用的 vars 參數,該參數應定義一個物件,其中包含要記錄的自訂變數。這些變數會以 VIDEO_STATE 的形式提供,並以 custom_ 為字首的金鑰命名,亦即物件 {myVar: 'foo'} 將會以 {'custom_myVar': 'foo'} 的形式提供。

getConsentData(callback)

當主機文件使用 amp-consent 時,iframe 文件可以要求使用者同意資料。

如果您只需要在未給予同意時封鎖 iframe 載入,則最好設定 data-block-on-consent 屬性,而不是呼叫 getConsentData()

傳遞至函式的 callback 將會使用包含下列屬性的物件來執行

{
  "consentMetadata": {
    "consentStringType": 2,
    "additionalConsent": "additional-consent-string",
    "gdprApplies": true,
    "purposeOne": true
  },
  "consentString": "accept-string",
  "consentPolicyState": 1,
  "consentPolicySharedData": {
    "tfua": true,
    "coppa": true
  }
}

例如,可以封鎖影片載入,直到 consentPolicyState 可用為止

// 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...
});

也提供使用 getConsentData 的完整範例。

getIntersection(callback)

取得影片元素的交集比率 (介於 0 和 1 之間)。這對於可見度資訊很有用,例如

// Will log intersection every 2 seconds
setInterval(function () {
  integration.getIntersection(function (intersection) {
    console.log('Intersection ratio:', intersection.intersectionRatio);
  });
}, 2000);

傳遞至函式的 callback 將會使用看起來像這樣的物件來執行

{"time": 33333.33, "intersectionRatio": 0.761}

⚠ 這應該視為低精確度讀數。目前,只要影片的可見度低於 50%,intersectionRatio 的值就會是 0。此值隨時可能會變更,且回呼可能會延遲或去抖動。

getMetadata()

傳回包含有關主機文件中繼資料的物件

{
  "canonicalUrl": "https://example.com/canonical.html",
  "sourceUrl": "https://example.com/amp.html",
  "title": "My host document's title",
  "lang": "en"
}
  • canonicalUrl 是標準網址。

  • sourceUrl 是 AMPHTML URL。

  • title 是來源 URL 的文件標題,時間點為 <amp-video-iframe> 初始化時。當元件載入至陰影根目錄時,null

  • lang 是來源 URL 的語言,在 <html ⚡️ lang="en"> 中指定。當元件載入至陰影根目錄時,null

  • jsonLd 包含 JSON-LD 標籤的已剖析內容 (如果存在)。

需要更多協助嗎?

您已閱讀此文件十幾次,但它仍然沒有涵蓋您的所有問題嗎?也許其他人也有相同的感覺:在 Stack Overflow 上與他們聯繫。

前往 Stack Overflow
發現錯誤或缺少功能嗎?

AMP 專案強烈鼓勵您的參與和貢獻!我們希望您能成為我們開放原始碼社群的長期參與者,但我們也歡迎您針對您特別感興趣的問題提供一次性貢獻。

前往 GitHub