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 尚未包含片段时,才会添加此片段。 |
海报 | 视频加载时显示的图像的 URL。建议始终设置此属性以获得最佳感知性能。 |
自动播放 | 如果存在此属性,并且浏览器支持自动播放,则视频将在可见后立即自动播放。该组件需要满足一些条件才能播放,这些条件在 AMP 规范中的视频中概述。 |
通用属性 | 此元素包括扩展到 AMP 组件的 通用属性。 |
停靠 | 需要 amp-video-docking 扩展。如果存在此属性并且视频正在手动播放,则当用户滚动出视频组件的可视区域时,视频将“最小化”并固定在角落或元素上。有关更多详细信息,请参阅 停靠扩展本身的文档。 |
implements-media-session | 如果 iframe 内部的文档独立实现 MediaSession API,请设置此属性。 |
implements-rotate-to-fullscreen | 如果 iframe 内部的文档独立实现旋转到全屏,请设置此属性。 |
referrerpolicy | 要设置在 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
) 是分开的,因为它位于被 iframe 的非 AMP 文档中。
提供的回调指定 AMP 文档和 iframe 视频文档如何相互通信。您需要实现一组播放方法和事件分发器来将它们连接在一起。对于常见的视频框架,集成脚本 提供了现成的播放支持,但如果您不使用任何可用的支持工具,也可以 自己编写自定义集成。
autoplay
属性的 amp-video-iframe
标签。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
对于最佳可能的 UX 是必需的。例如,当将视频最小化到角落时,会显示一个自定义控件叠加层。如果您不提供隐藏和显示控件的方法,则可能同时显示两组控件,这是一种糟糕的用户体验。 -
fullscreenenter
和fullscreenexit
对于最佳可能的 UX 是必需的。例如,对于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 文档可以请求用户同意数据。
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
是规范 URL。 -
sourceUrl
是 AMPHTML URL。 -
title
是在初始化<amp-video-iframe>
时源 URL 的文档标题。当组件加载在影子根中时为null
。 -
lang
是在<html ⚡️ lang="en">
中指定的源 URL 的语言。当组件加载在影子根中时为null
。 -
jsonLd
包括 JSON-LD 标记的已解析内容(如果存在)。
您已经阅读了本文档十几次,但它并没有真正涵盖您的所有问题?也许其他人也有同感:在 Stack Overflow 上联系他们。
转到 Stack Overflow 发现错误或缺少功能?AMP 项目强烈鼓励您参与和贡献!我们希望您成为我们开源社区的持续参与者,但我们也欢迎您对您特别热衷的问题进行一次性贡献。
转到 GitHub