AMP

amp-video-iframe

Displays an iframe containing a video player.

Required Script<script async custom-element="amp-video-iframe" src="https://cdn.ampproject.org/v0/amp-video-iframe-0.1.js"></script>
Supported Layoutsfill, fixed, fixed-height, flex-item, intrinsic, nodisplay, responsive

When should I use this?

This component is useful if you've built your own Javascript-based video player and would like to embed it in an AMP document, or if your player is provided by a third party not supported by the AMP component library.

  1. If you'd like to include a video directly on the AMP document, you should use amp-video.

  2. If you're using a common 3rd party like Youtube, Vimeo or others supported in AMP, you should use their supported component (e.g. amp-youtube, amp-vimeo).

  3. If you've built a custom player or are using one provided by an unsupported 3rd party, you should use amp-video-iframe. This is different from using amp-iframe in that it enables Video Features on AMP. See behavior below for more details.

Behavior

amp-video-iframe has several important differences from vanilla iframes and amp-iframe.

  • By default, an amp-video-iframe is sandboxed (see details).

  • amp-video-iframe implements all Video Features, like autoplay, minimize-to-corner and rotate-to-fullscreen.

  • amp-video-iframe must only request resources via HTTPS.

  • amp-video-iframe is not scrollable.

In short, amp-video-iframe plugs AMP video features into an embedded document that hosts a video player.

Usage of amp-video-iframe for advertising

amp-video-iframe must not be used for the primary purpose of displaying advertising. It is OK to use amp-video-iframe for the purpose of displaying videos, where part of the videos are advertising. This AMP policy may be enforced by not rendering the respective iframes.

Advertising use cases should use amp-ad instead.

The reasons for this policy are that:

  • amp-video-iframe enforces sandboxing and the sandbox is also applied to child iframes. This means landing pages may be broken, even if the ad itself appears to work.

  • amp-video-iframe has no controlled resize mechanism.

Attributes

src (required)The src attribute behaves mainly like on a standard iframe with one exception: the #amp=1 fragment is added to the URL to allow source documents to know that they are embedded in the AMP context. This fragment is only added if the URL specified by src does not already have a fragment.
poster (required)Points to an image URL that will be displayed while the video loads.
autoplayIf this attribute is present, and the browser supports autoplay, the video will be automatically played as soon as it becomes visible. There are some conditions that the component needs to meet to be played, which are outlined in the Video in AMP spec.
common attributesThis element includes common attributes extended to AMP components.
dockRequires amp-video-docking extension. If this attribute is present and the video is playing manually, the video will be "minimized" and fixed to a corner or an element when the user scrolls out of the video component's visual area. For more details, see documentation on the docking extension itself.
implements-media-sessionSet this attribute if the document inside the iframe implements the MediaSession API independently.
implements-rotate-to-fullscreenSet this attribute if the document inside the iframe implements rotate-to-fullscreen independently.
referrerpolicyThe referrerpolicy to be set on the iframe element.

Usage

Include an amp-video-iframe on your AMP document:

<amp-video-iframe layout="responsive"
    width="16"
    height="16"
    src="/my-video-player.html"
    poster="/my-video-poster.jpg">
</amp-video-iframe>

Integration inside the frame

In order for the video integration to work, the embedded document (e.g. my-video-player.html) must include a small library:

<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.
}
</script>

Note that this library is separate from the extension code (amp-video-iframe-0.1.js), because it lives on the non-AMP document that is iframed.

Simple integrations

If you're using a common video framework like JwPlayer or Video.js, you can simply call listenTo for a basic integration:

For JwPlayer:
function onAmpIntegrationReady(ampIntegration) {
  var myVideo = jwplayer('my-video');
  ampIntegration.listenTo('jwplayer', myVideo);
}
For Video.js:
function onAmpIntegrationReady(ampIntegration) {
  var myVideo = document.querySelector('#my-video');
  ampIntegration.listenTo('videojs', myVideo);
}

Never play the video inside the frame automatically. Instead, you should support the integration script and use the amp-video-iframe tag with the autoplay attribute. The AMP component will autoamtically send the necessary signals to your iframe to autoplay for a better user experience.

Custom integrations

It's possible to have more fine-grained control over how the video interacts with the host document by using the following methods:

method(name, callback)

Implements a method that calls playback functions on the video. For example:

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

These are methods that should be implemented:

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

You can choose to only implement this interface partially, with a few caveats:

  • mute and unmute are required for autoplay.

  • showcontrols and hidecontrols are required for the best possible UX. For example, when minimizing the video to the corner, a custom controls overlay is shown. If you don't provide methods to hide and show controls, two sets of controls could be displayed at the same time, which is a poor user experience.

  • fullscreenenter and fullscreenexit are required for best possible UX. For example, for rotate-to-fullscreen or the fullscreen button on minimized video.

postEvent(name)

Posts a playback event to the frame. For example:

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

The valid events are as follows.

EventDescription
canplayTriggered when your player is ready. This event must be posted before the player can become interactive.
playingTriggered when your player has started playing a video after load or pause.
pauseTriggered when your video has been paused.
endedTriggered when your video has ended playback. Note that you must also post a pause event alongside the ended event.
mutedTriggered when your video has been muted.
unmutedTriggered when your video has been unmuted.
ad_startTriggered when a pre/mid/post-roll ad is playing. This hides the autoplay shim displayed on the video.
ad_endTriggered when a pre/mid/post-roll ad has ended. This re-displays the autoplay shim if the user has not yet interacted with the video.

postAnalyticsEvent(eventType[, vars])

Posts a custom analytics event to be consumed by amp-analytics. The eventType must be prefixed with video-custom- to prevent naming collisions with other analytics event types.

This method takes an optional vars param that should define an object with custom variables to log. These are available as VIDEO_STATE, keyed by name prefixed with custom_, i.e. the object {myVar: 'foo'} will be available as {'custom_myVar': 'foo}.

getIntersection(callback)

Gets the intersection ratio (between 0 and 1) for the video element. This is useful for viewability information, e.g.

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

The callback passed to the function will be executed with an object that looks like this:

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

⚠ This should be considered a low-fidelity reading. Currently, the value for intersectionRatio will be 0 as long as the video is under 50% visible. This value is bound to change at any time, and the callbacks may be delayed or debounced.

getMetadata()

Returns an object containing metadata about the host document:

{
  "canonicalUrl": "foo.html",
  "sourceUrl": "bar.html",
}
需要更多帮助?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub