amp-video-iframe

1.0 0.1

<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-youtube、amp-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 沒有受控制的調整大小機制。

屬性

用法

在您的 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 作者只需要在其文件中加入 <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 網址會附加 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) 是分開的，因為它位於 iframe 的非 AMP 文件上。

提供的回呼指定 AMP 文件和 iframe 影片文件如何相互溝通。您需要實作一組播放方法和事件分派器，將它們結合在一起。對於常見的影片框架，整合指令碼 提供現成的播放支援，但如果您未使用任何支援工具，也可以自行編寫自訂整合。

現成的整合

如果您使用的是常見的影片框架，例如 JW Player 或 Video.js，您可以呼叫 listenTo() 以進行基本的現成整合。當框架提供所有播放和 UI 控制項時，這些整合會支援所有這些控制項，請參閱每個整合以瞭解支援的方法。

適用於 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 是獲得最佳 UX 的必要條件。例如，當將影片縮小到角落時，會顯示自訂控制項覆疊。如果您未提供隱藏和顯示控制項的方法，則可能會同時顯示兩組控制項，這會造成不良的使用者體驗。

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

postEvent(name)

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

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

有效的事件如下。

在播放前置/中間/後置廣告結束時觸發。如果使用者尚未與影片互動，這會重新顯示自動播放墊片。

postAnalyticsEvent(eventType[, vars])

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

此方法採用選用的 vars 參數，該參數應定義一個物件，其中包含要記錄的自訂變數。這些變數可作為 VIDEO_STATE 使用，索引鍵為名稱，字首為 custom_，即物件 {myVar: 'foo'} 將可作為 {'custom_myVar': 'foo'} 使用。

getConsentData(callback)

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

• 傳遞至函式的 callback 將會使用包含下列屬性的物件來執行
• consentMetadata (同意中繼資料)
• consentString (同意字串)
• consentPolicyState (同意政策狀態)

{
  "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 的範例也可用。

getIntersection(callback)

// 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。此值隨時可能會變更，且回呼可能會延遲或去抖動。

getMetadata()

{
  "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> 時。當元件載入到陰影根目錄時，null。

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