Skip to content

Latest commit

 

History

History
223 lines (182 loc) · 11.9 KB

amp-iframe.md

File metadata and controls

223 lines (182 loc) · 11.9 KB
Raw

amp-iframe

Description Displays an iframe.
Availability Stable
Required Script <script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>
Examples amp-iframe.html
everything.amp.html

The following lists validation errors specific to the amp-iframe tag (see also amp-iframe in the AMP validator specification):

Validation Error Description
The 'example1' tag is missing or incorrect, but required by 'example2'. Error thrown when required amp-iframe extension .js script tag is missing or incorrect.
The tag 'example1' is missing a mandatory attribute - pick one of example2. Error thrown when neither src or srcdoc is included. One of these attributes is mandatory.
Missing URL for attribute 'example1' in tag 'example2'. Error thrown when src or srcdoc is missing it's URL.
Malformed URL 'example3' for attribute 'example1' in tag 'example2'. Error thrown when src or srcdoc URL is invalid.
Invalid URL protocol 'example3:' for attribute 'example1' in tag 'example2'. Error thrown src or srcdoc URL is http; https protocol required.
The attribute 'example1' in tag 'example2' is set to the invalid value 'example3'. Error thrown when scrolling attribute not auto, yes, or no. Error also thrown when frameborder not 0 or 1. Attribute value must be "" for allowfullscreen, allowtransparency, resizable.
The implied layout 'example1' is not supported by tag 'example2'. Error thrown when implied layout is set to CONTAINER; this layout type isn't supported.
The specified layout 'example1' is not supported by tag 'example2'. Error thrown when specified layout is set to CONTAINER; this layout type isn't supported.
The property 'example1' in attribute 'example2' in tag 'example3' is set to 'example4', which is invalid. Error thrown when invalid value is given for attributes height or width. For example, height=auto triggers this error for all supported layout types, with the exception of NODISPLAY.

Behavior

amp-iframe has several important differences from vanilla iframes that are designed to make it more secure and avoid AMP files that are dominated by a single iframe:

  • amp-iframe may not appear close to the top of the document (except for iframes that use placeholder as described below). They must be either 600px away from the top or not within the first 75% of the viewport when scrolled to the top – whichever is smaller. NOTE: We are currently looking for feedback as to how well this restriction works in practice.
  • They are sandboxed by default. Details
  • They must only request resources via HTTPS or from a data-URI or via the srcdoc attribute.
  • They must not be in the same origin as the container unless they do not allow allow-same-origin in the sandbox attribute. See the doc "Iframe origin policy" for further details on allowed origins for iframes.

Example:

<amp-iframe width=300 height=300
    sandbox="allow-scripts allow-same-origin"
    layout="responsive"
    frameborder="0"
    src="https://foo.com/iframe">
</amp-iframe>

Attributes

src, srcdoc, frameborder, allowfullscreen, allowtransparency

The attributes above should all behave like they do on standard iframes.

sandbox

Iframes created by amp-iframe always have the sandbox attribute defined on them. By default the value is empty. That means that they are "maximum sandboxed" by default. By setting sandbox values, one can opt the iframe into being less sandboxed. All values supported by browsers are allowed. E.g. setting sandbox="allow-scripts" allows the iframe to run JavaScript, or sandbox="allow-scripts allow-same-origin" allows the iframe to run JavaScript, make non-CORS XHRs, and read/write cookies.

If you are iframing a document that was not specifically created with sandboxing in mind, you will most likely need to add allow-scripts allow-same-origin to the sandbox attribute and you mights need to allow additional capabilities.

Note also, that the sandbox applies to all windows opened from a sandboxed iframe. This includes new windows created by a link with target=_blank (Add allow-popups to allow this to happen). Adding allow-popups-to-escape-sandbox to the sandbox attribute, makes those new windows behave like non-sandboxed new windows. This is likely most of the time what you want and expect. Unfortunately, as of this writing, allow-popups-to-escape-sandbox is only supported by Chrome.

See the the docs on MDN for further details on the sandbox attribute.

Iframe Resizing

An amp-iframe must have static layout defined as is the case with any other AMP element. However, it's possible to resize an amp-iframe in runtime. To do so:

  1. The amp-iframe must be defined with resizable attribute;
  2. The amp-iframe must have overflow child element;
  3. The IFrame document has to send a embed-size request as a window message.

Notice that resizable overrides scrolling value to no.

Example of amp-iframe with overflow element:

<amp-iframe width=300 height=300
    layout="responsive"
    sandbox="allow-scripts allow-same-origin"
    resizable
    src="https://foo.com/iframe">
  <div overflow tabindex=0 role=button aria-label="Read more">Read more!</div>
</amp-iframe>

Example of Iframe resize request:

window.parent.postMessage({
  sentinel: 'amp',
  type: 'embed-size',
  height: document.body.scrollHeight
}, '*');

Once this message is received the AMP runtime will try to accommodate this request as soon as possible, but it will take into account where the reader is currently reading, whether the scrolling is ongoing and any other UX or performance factors. If the runtime cannot satisfy the resize events the amp-iframe will show an overflow element. Clicking on the overflow element will immediately resize the amp-iframe since it's triggered by a user action.

Here are some factors that affect how fast the resize will be executed:

  • Whether the resize is triggered by the user action;
  • Whether the resize is requested for a currently active Iframe;
  • Whether the resize is requested for an Iframe below the viewport or above the viewport.

Iframe with Placeholder

It is possible to have an amp-iframe appear on the top of a document when the amp-iframe has a placeholder element as shown in the example below.

<amp-iframe width=300 height=300
   layout="responsive"
   sandbox="allow-scripts allow-same-origin"
   src="https://foo.com/iframe">
 <amp-img layout="fill" src="https://foo.com/foo.png" placeholder></amp-img>
</amp-iframe>
  • The amp-iframe must contain an element with the placeholder attribute, (for instance an amp-img element) which would be rendered as a placeholder till the iframe is ready to be displayed.
  • Iframe readiness can be known by listening to onload of the iframe or an embed-ready postMessage which would be sent by the Iframe document, whichever comes first.

Example of Iframe embed-ready request:

window.parent.postMessage({
  sentinel: 'amp',
  type: 'embed-ready'
}, '*');

Iframe viewability

Iframes can send a send-intersection message to its parent to start receiving IntersectionObserver style change records of the iframe's intersection with the parent viewport.

Example of Iframe send-intersection request:

window.parent.postMessage({
  sentinel: 'amp',
  type: 'send-intersection'
}, '*');

The Iframe can listen to an intersection message from the parent window to receive the intersection data.

Example of Iframe send-intersection request:

window.addEventListener('message', function(event) {
  const listener = function(event) {
    if (event.source != window.parent ||
        event.origin != window.context.location.origin ||
        !event.data ||
        event.data.sentinel != 'amp' ||
        event.data.type != 'intersection') {
      return;
    }
    event.data.changes.forEach(function (change) {
      console.log(change);
    });
});

The intersection message would be sent by the parent to the iframe when the iframe moves in or out of the viewport (or is partially visibile), when the iframe is scrolled or resized.

Tracking/Analytics iframes

We strongly recommend using amp-analytics for analytics purposes, because it is significantly more robust, complete and efficient solution and can be configured for a wide range of analytics vendors.

AMP only allows a single iframe, that is used for analytics and tracking purposes, per page. To conserve resources these iframes will be removed from the DOM 5 seconds after they loaded, which should be sufficient time to complete whatever work is needed to be done.

Iframes are identified as tracking/analytics iframes if they appear to serve no direct user purpose such as being invisible or small.