amp-video-iframe

Displays an iframe containing a video player.

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

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
• postEvent
• getIntersection
• getMetadata

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.

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",
}