AMP

重要提示:此文档不适用于您当前选择的格式故事

amp-video-iframe

描述

嵌入一个包含视频播放器的 iframe。

 

必需脚本

<script async custom-element="amp-video-iframe" src="https://cdn.ampproject.org/v0/amp-video-iframe-1.0.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 扩展。 如果存在此属性,并且视频正在手动播放,则当用户滚动出视频组件的可视区域时,视频将被“最小化”并固定到角落或元素。有关更多详细信息,请参见关于停靠扩展本身的文档。
implements-media-session 如果 iframe 内的文档独立实现了 MediaSession API,则设置此属性。
implements-rotate-to-fullscreen 如果 iframe 内的文档独立实现了旋转到全屏,则设置此属性。
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) 是分开的,因为它位于 iframed 的非 AMP 文档上。

提供的回调指定 AMP 文档和 iframed 视频文档如何相互通信。您需要实现一组播放方法和事件分发器才能将它们连接在一起。对于常见的视频框架,集成脚本提供了现成的播放支持,但如果您不使用任何支持可用的工具,也可以自行编写自定义集成

切勿自动播放框架内的视频。 相反,您应该支持集成脚本并将 amp-video-iframe 标记与 autoplay 属性一起使用。AMP 组件会自动向您的 iframe 发送必要的信号以自动播放,从而提供更好的用户体验。

现成的集成

如果您使用 JW PlayerVideo.js 等常见视频框架,则可以调用 listenTo() 进行基本的现成集成。当框架提供时,这些集成支持所有播放和 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 用于控制播放。
  • postEvent 用于向宿主文档通知播放事件。
  • getIntersection 用于获取视频在宿主文档上的可见性。
  • getMetadata 用于获取有关宿主文档的信息。

如果您使用受支持的框架,则可以使用相同的方法对默认实现进行更精细的控制。

method(name, callback)

实现一个在视频上调用播放功能的 方法。例如

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

以下是应实现的方法

  • 播放
  • 暂停
  • 静音
  • 取消静音
  • 显示控件
  • 隐藏控件
  • 进入全屏
  • 退出全屏

您可以选择仅部分实现此接口,但有一些注意事项

  • 播放和暂停对于播放操作或自动播放是必需的。

  • 静音和取消静音对于自动播放是必需的。

  • 显示控件和隐藏控件对于实现最佳用户体验是必需的。例如,当将视频最小化到角落时,会显示自定义控件叠加层。如果不提供隐藏和显示控件的方法,则可能会同时显示两组控件,从而导致较差的用户体验。

  • 进入全屏和退出全屏对于实现最佳用户体验是必需的。例如,用于 rotate-to-fullscreen 或最小化视频上的全屏按钮。

postEvent(name)

将播放事件发布到框架。例如

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

以下是有效的事件。

事件 描述
canplay 当您的播放器准备就绪时触发。此事件必须在播放器可以交互之前发布。
playing 当您的播放器在加载或暂停后开始播放视频时触发。
暂停 当您的视频已暂停时触发。
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 网址。

  • title 是初始化 <amp-video-iframe> 时源网址的文档标题。当组件在 Shadow DOM 中加载时,为 null

  • lang 是源网址中在 <html ⚡️ lang="en"> 中指定的语言。当组件在 Shadow DOM 中加载时,为 null

  • jsonLd 包含 JSON-LD 标记的已解析内容(如果存在)。

需要更多帮助吗?

您已经阅读此文档很多次,但它并未真正涵盖您的所有问题?也许其他人也有同感:请在 Stack Overflow 上与他们联系。

前往 Stack Overflow
发现错误或缺少功能?

AMP 项目强烈鼓励您参与并做出贡献!我们希望您能成为我们开源社区的持续参与者,但也欢迎您针对自己特别热衷的问题做出一次性贡献。

前往 GitHub