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>

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.

4. If you're a 3rd party video vendor, you can use amp-video-iframe to provide a simple way for authors to embed video.

Behavior

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

• By default, an amp-video-iframe is sandboxed.

• 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="9"
  src="/my-video-player.html"
  poster="/my-video-poster.jpg"
>
</amp-video-iframe>

my-video-player.html is the inner document loaded inside the frame that plays the video. This document must include and bootstrap an integration script so that the AMP document including the <amp-video-iframe> can coordinate the video's playback.

Third-party video vendors

If you're a vendor that does not provide a custom video player component, you can integrate with AMP in the form of an amp-video-iframe configuration, so authors can embed video provided through your service.

As a vendor, you can serve a generic integration document that references provided videos via URL parameters. AMP authors who use your video service only need to include an <amp-video-iframe> tag in their documents:

<!--
  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>

The src and poster URLs are appended with data-param-* attributes as query string.

The /amp-video-iframe document bootstraps the integration script so that the AMP document can coordinate with the player.

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.
    // YOU NEED TO IMPLEMENT THIS. See below.
  }
</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.

The provided callback specifies how the AMP document and the iframed video document talk to each other. You need to implement a set of playback methods and event dispatchers to plug these together. For common video frameworks, the integration script provides readymade playback support, but you can also write a custom integration yourself if you don't use any of the tools for which support is available.

Readymade integrations

If you're using a common video framework like JW Player or Video.js, you can call listenTo() for a basic, readymade integration. These integrations support all playback and UI controls when the framework provides them, see each for supported methods.

For JW Player

Default supported events: ad_end/ad_start, canplay, error, muted/unmuted, pause/playing

Default supported methods: pause/play, mute/unmute, hidecontrols/showcontrols, fullscreenenter/fullscreenexit

The amp object knows how to setup a JwPlayer instance by using listenTo('jwplayer'). If you're embedding your player using a video-specific script, you only need to register Jwplayer usage:

<script src="https://cdn.jwplayer.com/players/UVQWMA4o-kGWxh33Q.js"></script>
<script>
  (window.AmpVideoIframe = window.AmpVideoIframe || []).push(function (
    ampIntegration
  ) {
    ampIntegration.listenTo('jwplayer');
  });
</script>

Otherwise, pass in your JwPlayer instance through the signature amp.listenTo('jwplayer', instance):

(window.AmpVideoIframe = window.AmpVideoIframe || []).push(function (
  ampIntegration
) {
  ampIntegration.listenTo('jwplayer', jwplayer('my-video'));
});

For Video.js

Default supported events: canplay, ended, muted/unmuted, pause/playing

Default supported methods: pause/play, mute/unmute, hidecontrols/showcontrols, fullscreenenter/fullscreenexit

Pass in your <video> element through the signature ampIntegration.listenTo('videojs', myVideo). Video.js overloads this element to provide methods that the ampIntegration object uses to setup the player.

function onAmpIntegrationReady(ampIntegration) {
  var myVideo = document.querySelector('#my-video');
  ampIntegration.listenTo('videojs', myVideo);
}

listenTo initializes the Video.js instance on the <video> element if required. This uses the global videojs function by default. If your page provides the initializer differently, you must pass it in as the third argument:

function onAmpIntegrationReady(ampIntegration) {
  var myVideo = document.querySelector('#my-video');

  // ampIntegration initializes player with `myVideojsInitializer(myVideo)`
  ampIntegration.listenTo('videojs', myVideo, myVideojsInitializer);
}

Custom integrations

If you don't use any of the video frameworks supported by default, you must write a custom implementation to talk to AMP's video management.

These are the communication methods available:

• method to control playback.
• postEvent to inform the host document about playback events.
• getIntersection to get video's viewability on the host document.
• getMetadata to get information about the host document.

If you use a supported framework, it's possible to have more fine-grained control over the default implementation by using these same 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:

• play and pause are required for either/both of playback actions or autoplay.

• 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}.

getConsentData(callback)

The iframe document can request user consent data when the host document uses amp-consent.

The callback passed to the function will be executed with an object containing the following properties:

• consentMetadata
• consentString
• consentPolicyState
• consentPolicySharedData

{
  "consentMetadata": {
    "consentStringType": 2,
    "additionalConsent": "additional-consent-string",
    "gdprApplies": true,
    "purposeOne": true
  },
  "consentString": "accept-string",
  "consentPolicyState": 1,
  "consentPolicySharedData": {
    "tfua": true,
    "coppa": true
  }
}

For example, a video could be blocked from loading until consentPolicyState is available:

// 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...
});

A complete example using getConsentData is available as well.

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": "https://example.com/canonical.html",
  "sourceUrl": "https://example.com/amp.html",
  "title": "My host document's title",
  "lang": "en"
}

• canonicalUrl is the canonical URL.

• sourceUrl is the AMPHTML URL.

• title is the source URL's document title at the time the <amp-video-iframe> is initialized. null when the component is loaded in a shadow root.

• lang is the source URL's language specified in <html ⚡️ lang="en">. null when the component is loaded in a shadow root.