AMP Conf 2020: Save the date!
AMP
ZH
English Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe

AMP for Ads specification

If you'd like to propose changes to the standard, please comment on the Intent to Implement.

AMPHTML ads is a mechanism for rendering fast, performant ads in AMP pages. To ensure that AMPHTML ad documents ("AMP creatives") can be rendered quickly and smoothly in the browser and do not degrade user experience, AMP creatives must obey a set of validation rules. Similar in spirit to the AMP format rules, AMPHTML ads have access to a limited set of allowed tags, capabilities, and extensions.

AMPHTML ad format rules

Unless otherwise specified below, the creative must obey all rules given by the AMP format rules, included here by reference. For example, the AMPHTML ad Boilerplate deviates from the AMP standard boilerplate.

In addition, creatives must obey the following rules:

Rule Rationale
Must use <html ⚡4ads> or <html amp4ads> as its enclosing tags. Allows validators to identify a creative document as either a general AMP doc or a restricted AMPHTML ad doc and to dispatch appropriately.
Must include <script async src="https://cdn.ampproject.org/amp4ads-v0.js"></script> as the runtime script instead of https://cdn.ampproject.org/v0.js. Allows tailored runtime behaviors for AMPHTML ads served in cross-origin iframes.
Must not include a <link rel="canonical"> tag. Ad creatives don't have a "non-AMP canonical version" and won't be independently search-indexed, so self-referencing would be useless.
Can include optional meta tags in HTML head as identifiers, in the format of <meta name="amp4ads-id" content="vendor=${vendor},type=${type},id=${id}">. Those meta tags must be placed before the amp4ads-v0.js script. The value of vendor and id are strings containing only [0-9a-zA-Z_-]. The value of type is either creative-id or impression-id. Those custom identifiers can be used to identify the impression or the creative. They can be helpful for reporting and debugging.

Example:

<meta name="amp4ads-id"
  content="vendor=adsense,type=creative-id,id=1283474">
<meta name="amp4ads-id"
  content="vendor=adsense,type=impression-id,id=xIsjdf921S">
<amp-analytics> viewability tracking may only target the full-ad selector, via "visibilitySpec": { "selector": "amp-ad" } as defined in Issue #4018 and PR #4368. In particular, it may not target any selectors for elements within the ad creative. In some cases, AMPHTML ads may choose to render an ad creative in an iframe.In those cases, host page analytics can only target the entire iframe anyway, and won’t have access to any finer-grained selectors.

Example:

<amp-analytics id="nestedAnalytics">
  <script type="application/json">
  {
    "requests": {
      "visibility": "https://example.com/nestedAmpAnalytics"
    },
    "triggers": {
      "visibilitySpec": {
      "selector": "amp-ad",
      "visiblePercentageMin": 50,
      "continuousTimeMin": 1000
      }
    }
  }
  </script>
</amp-analytics>

This configuration sends a request to the https://example.com/nestedAmpAnalytics URL when 50% of the enclosing ad has been continuously visible on the screen for 1 second.

Boilerplate

AMPHTML ad creatives require a different, and considerably simpler, boilerplate style line than general AMP documents do:

<style amp4ads-boilerplate>
  body {
    visibility: hidden;
  }
</style>

Rationale: The amp-boilerplate style hides body content until the AMP runtime is ready and can unhide it. If Javascript is disabled or the AMP runtime fails to load, the default boilerplate ensures that the content is eventually displayed regardless. In AMPHTML ads, however, if Javascript is entirely disabled, AMPHTML ads won't run and no ad will ever be shown, so there is no need for the <noscript> section. In the absence of the AMP runtime, most of the machinery that AMPHTML ads rely on (e.g., analytics for visibility tracking or amp-img for content display) won't be available, so it's better to display no ad than a malfunctioning one.

Finally, the AMPHTML ad boilerplate uses amp-a4a-boilerplate rather than amp-boilerplate so that validators can easily identify it and produce more accurate error messages to help developers.

Note that the same rules about mutations to the boilerplate text apply as in the general AMP boilerplate.

CSS

Rule Rationale
position:fixed and position:sticky are prohibited in creative CSS. position:fixed breaks out of shadow DOM, which AMPHTML ads depend on. lso, ads in AMP are already not allowed to use fixed position.
touch-action is prohibited. An ad that can manipulate touch-action can interfere with the user's ability to scroll the host document.
Creative CSS is limited to 20,000 bytes. Large CSS blocks bloat the creative, increase network latency, and degrade page performance.
Transition and animation are subject to additional restrictions. AMP must be able to control all animations belonging to an ad, so that it can stop them when the ad is not on screen or system resources are very low.
Vendor-specific prefixes are considered aliases for the same symbol without the prefix for the purposes of validation. This means that if a symbol foo is prohibited by CSS validation rules, then the symbol -vendor-foo will also be prohibited. Some vendor-prefixed properties provide equivalent functionality to properties that are otherwise prohibited or constrained under these rules.

Example: -webkit-transition and -moz-transition are both considered aliases for transition. They will only be allowed in contexts where bare transition would be allowed (see Selectors section below).

CSS animations and transitions

Selectors

The transition and animation properties are only allowed on selectors that:

  • Contain only transition, animation, transform, visibility, or opacity properties.

Rationale: This allows the AMP runtime to remove this class from context to deactivate animations, when necessary for page performance.

Good

.box {
  transform: rotate(180deg);
  transition: transform 2s;
}

Bad

Property not allowed in CSS class.

.box {
  color: red; // non-animation property not allowed in animation selector
  transform: rotate(180deg);
  transition: transform 2s;
}
Transitionable and animatable properties

The only properties that may be transitioned are opacity and transform. (Rationale)

Good

transition: transform 2s;

Bad

transition: background-color 2s;

Good

@keyframes turn {
  from {
    transform: rotate(180deg);
  }

  to {
    transform: rotate(90deg);
  }
}

Bad

@keyframes slidein {
  from {
    margin-left: 100%;
    width: 300%;
  }

  to {
    margin-left: 0%;
    width: 100%;
  }
}

Allowed AMP extensions and builtins

The following are allowed AMP extension modules and AMP built-in tags in an AMPHTML ad creative. Extensions or builtin tags not explicitly listed are prohibited.

Most of the omissions are either for performance or to make AMPHTML ads simpler to analyze.

Example: <amp-ad> is omitted from this list. It is explicitly disallowed because allowing an <amp-ad> inside an <amp-ad> could potentially lead to unbounded waterfalls of ad loading, which does not meet AMPHTML ads performance goals.

Example: <amp-iframe> is omitted from this list. It is disallowed because ads could use it to execute arbitrary Javascript and load arbitrary content. Ads wanting to use such capabilities should return false from their a4aRegistry entry and use the existing '3p iframe' ad rendering mechanism.

Example: <amp-facebook>, <amp-instagram>, <amp-twitter>, and <amp-youtube> are all omitted for the same reason as <amp-iframe>: They all create iframes and can potentially consume unbounded resources in them.

Example: <amp-ad-network-*-impl> are omitted from this list. The <amp-ad> tag handles delegation to these implementation tags; creatives should not attempt to include them directly.

Example: <amp-lightbox> is not yet included because even some AMPHTML ads creatives may be rendered in an iframe and there is currently no mechanism for an ad to expand beyond an iframe. Support may be added for this in the future, if there is demonstrated desire for it.

HTML tags

The following are allowed tags in an AMPHTML ads creative. Tags not explicitly allowed are prohibited. This list is a subset of the general AMP tag addendum whitelist. Like that list, it is ordered consistent with HTML5 spec in section 4 The Elements of HTML.

Most of the omissions are either for performance or because the tags are not HTML5 standard. For example, <noscript> is omitted because AMPHTML ads depends on JavaScript being enabled, so a <noscript> block will never execute and, therefore, will only bloat the creative and cost bandwidth and latency. Similarly, <acronym>, <big>, et al. are prohibited because they are not HTML5 compatible.

4.1 The root element

4.1.1 <html>

  • Must use types <html ⚡4ads> or <html amp4ads>

4.2 Document metadata

4.2.1 <head>

4.2.2 <title>

4.2.4 <link>

  • <link rel=...> tags are disallowed, except for <link rel=stylesheet>.
  • Note: Unlike in general AMP, <link rel="canonical"> tags are prohibited.

4.2.5 <style> 4.2.6 <meta>

4.3 Sections

4.3.1 <body> 4.3.2 <article> 4.3.3 <section> 4.3.4 <nav> 4.3.5 <aside> 4.3.6 <h1>, <h2>, <h3>, <h4>, <h5>, and <h6> 4.3.7 <header> 4.3.8 <footer> 4.3.9 <address>

4.4 Grouping Content

4.4.1 <p> 4.4.2 <hr> 4.4.3 <pre> 4.4.4 <blockquote> 4.4.5 <ol> 4.4.6 <ul> 4.4.7 <li> 4.4.8 <dl> 4.4.9 <dt> 4.4.10 <dd> 4.4.11 <figure> 4.4.12 <figcaption> 4.4.13 <div> 4.4.14 <main>

4.5 Text-level semantics

4.5.1 <a> 4.5.2 <em> 4.5.3 <strong> 4.5.4 <small> 4.5.5 <s> 4.5.6 <cite> 4.5.7 <q> 4.5.8 <dfn> 4.5.9 <abbr> 4.5.10 <data> 4.5.11 <time> 4.5.12 <code> 4.5.13 <var> 4.5.14 <samp> 4.5.15 <kbd > 4.5.16 <sub> and <sup> 4.5.17 <i> 4.5.18 <b> 4.5.19 <u> 4.5.20 <mark> 4.5.21 <ruby> 4.5.22 <rb> 4.5.23 <rt> 4.5.24 <rtc> 4.5.25 <rp> 4.5.26 <bdi> 4.5.27 <bdo> 4.5.28 <span> 4.5.29 <br> 4.5.30 <wbr>

4.6 Edits

4.6.1 <ins> 4.6.2 <del>

4.7 Embedded Content

  • Embedded content is supported only via AMP tags, such as <amp-img> or <amp-video>.

4.7.4 <source>

4.7.18 SVG

SVG tags are not in the HTML5 namespace. They are listed below without section ids.

<svg> <g> <path> <glyph> <glyphref> <marker> <view> <circle> <line> <polygon> <polyline> <rect> <text> <textpath> <tref> <tspan> <clippath> <filter> <lineargradient> <radialgradient> <mask> <pattern> <vkern> <hkern> <defs> <use> <symbol> <desc> <title>

4.9 Tabular data

4.9.1 <table> 4.9.2 <caption> 4.9.3 <colgroup> 4.9.4 <col> 4.9.5 <tbody> 4.9.6 <thead> 4.9.7 <tfoot> 4.9.8 <tr> 4.9.9 <td> 4.9.10 <th>

4.10 Forms

4.10.8 <button>

4.11 Scripting

  • Like a general AMP document, the creative's <head> tag must contain a <script async src="https://cdn.ampproject.org/amp4ads-v0.js"></script> tag.
  • Unlike general AMP, <noscript> is prohibited.
  • Rationale: Since AMPHTML ads requires Javascript to be enabled to function at all, <noscript> blocks serve no purpose in AMPHTML ads and only cost network bandwidth.
  • Unlike general AMP, <script type="application/ld+json"> is prohibited.
  • Rationale: JSON LD is used for structured data markup on host pages, but ad creatives are not standalone documents and don't contain structured data. JSON LD blocks in them would just cost network bandwidth.
  • All other scripting rules and exclusions are carried over from general AMP.