<commit_before><!---
Copyright 2016 The AMP HTML Authors. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS-IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->


# AMP A4A AD CREATIVE FORMAT

![Draft standard](https://upload.wikimedia.org/wikipedia/commons/f/ff/DRAFT_ICON.png "By Reneman (Own work) [CC BY-SA 3.0 (http://creativecommons.org/licenses/by-sa/3.0)], via Wikimedia Commons")

** >> WORK IN PROGRESS.  SUBJECT TO CHANGE. << **

_This set of standards is still in development and is likely to be revised.
Feedback from the community is welcome.  Please comment here or on the [Intent
to Implement](https://github.com/ampproject/amphtml/issues/4264)_.

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

## A4A Format Rules
 
1. Unless otherwise specified below, the creative must obey all rules
   given by the [AMP format rules](../../spec/amp-html-format.md),
   included here by reference.  For example, the A4A
   [Boilerplate](amp-a4a-format.md#2) deviates from the AMP
   standard boilerplate.

   _*In addition*_:

1. The creative must use `<html ⚡4ads>` or `<html amp4ads>` as its enclosing
   tags.

   _Rationale_: Allows validators to identify a creative document as either a 
   general AMP doc or a restricted A4A doc and to dispatch appropriately.

1. The creative 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`.

   _Rationale_: Allows tailored runtime behaviors for A4A served in cross-origin iframes.

1. Unlike in general AMP, the creative must not include a `<link 
rel="canonical">` tag.

   _Rationale_: Ad creatives don't have a "non-AMP canonical version"
   and won't be independently search-indexed, so self-referencing
   would be useless.

1. The creative 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`. 

   _Rationale_: Those custom identifiers can be used to identify the impression
   or the creative. They can be helpful for reporting and debugging. 

   _Example_:
   ```html
<meta name="amp4ads-id" content="vendor=adsense,type=creative-id,id=1283474">
<meta name="amp4ads-id" content="vendor=adsense,type=impression-id,id=xIsjdf921S">
   ```

1. Media: Videos must not enable autoplay.  This includes 
both the `<amp-video>`
   tag as well as autoplay on `<amp-anim>`, `<amp-carousel>`, and 3P video 
   tags such as `<amp-youtube>`.

   _Rationale_: Autoplay forces video content to be downloaded immediately, 
   which slows the page load.

1. Media: Audio must not enable autoplay.  This includes both the `<amp-audio>`
   tag as well as all audio-including video tags, as described in the previous 
   point.

   _Rationale_: Same as for video.

1. Analytics: `<amp-analytics>` viewability tracking may only target the full-ad
   selector, via  `"visibilitySpec": { "selector": "amp-ad" }`, as defined in
   [Issue #4018](https://github.com/ampproject/amphtml/issues/4018) and
   [PR #4368](https://github.com/ampproject/amphtml/pull/4368).  In
   particular, it may not target any selectors for elements within the ad 
   creative.

   _Rationale_: In some cases, A4A 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_:
  
  ```html
<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 URL
  `https://example.com/nestedAmpAnalytics` when 50% of the enclosing ad has been
  continuously visible on the screen for 1 second._

### Boilerplate

A4A creatives require a different, and considerably simpler, boilerplate style line than
[general AMP documents do](https://github.com/ampproject/amphtml/blob/master/spec/amp-boilerplate.md):

```html
<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 A4A, however, if Javascript is entirely 
disabled, A4A 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 A4A and ad creatives rely on (e.g., analytics for visibility 
tracking or `amp-img` for content display) won't be available, so it's better to <commit_msg>Fix amp-a4a-format.md format (#8488)<commit_after><!---
Copyright 2016 The AMP HTML Authors. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS-IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->


# AMP A4A AD CREATIVE FORMAT

![Draft standard](https://upload.wikimedia.org/wikipedia/commons/f/ff/DRAFT_ICON.png "By Reneman (Own work) [CC BY-SA 3.0 (http://creativecommons.org/licenses/by-sa/3.0)], via Wikimedia Commons")

** >> WORK IN PROGRESS.  SUBJECT TO CHANGE. << **

_This set of standards is still in development and is likely to be revised.
Feedback from the community is welcome.  Please comment here or on the [Intent
to Implement](https://github.com/ampproject/amphtml/issues/4264)_.

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

## A4A Format Rules
 
- Unless otherwise specified below, the creative must obey all rules
   given by the [AMP format rules](../../spec/amp-html-format.md),
   included here by reference.  For example, the A4A
   [Boilerplate](amp-a4a-format.md#2) deviates from the AMP
   standard boilerplate.

   _*In addition*_:

- The creative must use `<html ⚡4ads>` or `<html amp4ads>` as its enclosing
   tags.

   _Rationale_: Allows validators to identify a creative document as either a 
   general AMP doc or a restricted A4A doc and to dispatch appropriately.

- The creative 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`.

   _Rationale_: Allows tailored runtime behaviors for A4A served in cross-origin iframes.

- Unlike in general AMP, the creative must not include a `<link 
rel="canonical">` tag.

   _Rationale_: Ad creatives don't have a "non-AMP canonical version"
   and won't be independently search-indexed, so self-referencing
   would be useless.

- The creative 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`. 

   _Rationale_: Those custom identifiers can be used to identify the impression
   or the creative. They can be helpful for reporting and debugging. 

   _Example_:
```html
<meta name="amp4ads-id" content="vendor=adsense,type=creative-id,id=1283474">
<meta name="amp4ads-id" content="vendor=adsense,type=impression-id,id=xIsjdf921S">
```

- Media: Videos must not enable autoplay.  This includes 
both the `<amp-video>`
   tag as well as autoplay on `<amp-anim>`, `<amp-carousel>`, and 3P video 
   tags such as `<amp-youtube>`.

   _Rationale_: Autoplay forces video content to be downloaded immediately, 
   which slows the page load.

- Media: Audio must not enable autoplay.  This includes both the `<amp-audio>`
   tag as well as all audio-including video tags, as described in the previous 
   point.

   _Rationale_: Same as for video.

- Analytics: `<amp-analytics>` viewability tracking may only target the full-ad
   selector, via  `"visibilitySpec": { "selector": "amp-ad" }`, as defined in
   [Issue #4018](https://github.com/ampproject/amphtml/issues/4018) and
   [PR #4368](https://github.com/ampproject/amphtml/pull/4368).  In
   particular, it may not target any selectors for elements within the ad 
   creative.

   _Rationale_: In some cases, A4A 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_:
  
```html
<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 URL
  `https://example.com/nestedAmpAnalytics` when 50% of the enclosing ad has been
  continuously visible on the screen for 1 second._

### Boilerplate

A4A creatives require a different, and considerably simpler, boilerplate style line than
[general AMP documents do](https://github.com/ampproject/amphtml/blob/master/spec/amp-boilerplate.md):

```html
<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 A4A, however, if Javascript is entirely 
disabled, A4A 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 A4A and ad creatives rely on (e.g., analytics for visibility 
tracking or `amp-img` for content display) won't be available, so it's better to 
{'fraction_non_alphanumeric': 0.09507839356082837, 'fraction_numerical': 0.014840278360023476, 'mean_word_length': 3.8985626283367556, 'pattern_counts': {'":': 18, '<': 51, '<?xml version=': 0, '>': 51, 'https://': 18, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6798062', 'n_tokens_mistral': 3786, 'n_tokens_neox': 3508, 'n_words': 1457}