Description Dynamically injects ads into an AMP page by using a remotely-served configuration file.
Availability Experimental
Required Script <script async custom-element="amp-auto-ads" src="https://cdn.ampproject.org/v0/amp-auto-ads-0.1.js"></script>
Supported Layouts N/A

Behavior

Given a sufficient number of valid placements (supplied in the configuration), amp-auto-ads tries to insert additional ads while adhering to a set of constraints specified by the ad network. These constraints will limit:

  • The total number of ads that can be inserted
  • The minimum distance that there should be between any adjacent ads
In addition to this, ads will only be inserted in locations on the page that do not cause an unacceptable re-flow (as determined by attemptChangeSize).

The <amp-auto-ads> tag should be placed as the first child of the <body>.

The ad network type and any additional information (required by the ad network) should be specified on the tag.

<amp-auto-ads
    type="adsense"
    data-ad-client="ca-pub-5439573510495356">
</amp-auto-ads>

Supported ad networks

Attributes

type (required)

An identifier for the ad network.

data-foo-bar

Most ad networks require further configuration, which can be passed to the network by using HTML data- attributes. The parameter names are subject to standard data attribute dash to camel case conversion. For example, "data-foo-bar" is send to the ad for configuration as "fooBar". See the documentation for the ad network on which attributes can be used.

common attributes

This element includes common attributes extended to AMP components.

Configuration Spec

The configuration defines where on the page <amp-auto-ads> can place ads. The configuration is fetched from a third-party ad network at the URL defined in ad-network-config.js. The configuration should be a serialized JSON object matching the ConfigObj definition described below.

Example Configuration

The following example specifies that the ad should be positioned immediately positions immediately after all <P class='paragraph'> elements that are within the third <DIV id='domId'> on the page. An ad placed in any of these positions should be of type BANNER and have a top margin of 4px and a bottom margin of 10px.

{
  "placements": [
    {
      "anchor": {
        "selector": "DIV#domId",
        "index": 2,
        "sub": {
          "selector": "P.paragraph",
          "all": true,
        },
      },
      "pos": 4,
      "type": 1,
      "style": {
        "top_m": 5,
        "bot_m": 10,
      },
    },
  ]
}

Object Definitions

ConfigObj

The fields to specify in the configuration object:

Field Name Type Description
placements Array<!PlacementObj> A required field that indicates the potential places where ads can be inserted on the page.
attributes Object<string, string> An optional field that specifies a mapping from the attribute name to attribute values to apply to all <amp-ad> elements injected using this configuration. Only the following attribute names are allowed:
  • type
  • layout
  • data-* (i.e. any data attribute)

PlacementObj

The fields to specify in the placements configuration object:

Field Name Type Description
anchor AnchorObj A required field that provides information used to look up the element(s) on the page that the placement position is anchored to.
pos RelativePositionEnum A required field that indicates the position of the placement relative to its anchor element.
type PlacementTypeEnum A required field that indicates the type of placement.
style PlacementStyleObj An optional field that indicates any styling that should be applied to an ad inserted in this placement position.
attributes Object<string, string> An optional field for a map from attribute name to value for attributes to apply to all <amp-ad> elements injected using this placement. An attribute specified here overrides any with the same name that is also specified on the parent ConfigObj. Only the following attribute names are allowed:
  • type
  • layout
  • data-* (i.e. any data attribute)

AnchorObj

The fields to specify in the anchor configuration object:

Field Name Type Description
selector string A required field that defines a CSS selector to select the element(s) at this level of the anchor definition.
index number An optional field to specify the index of the elements selected by the selector that this level of the anchor definition should be limited to. By default, the value is set to 0 (if the all field is false).
all boolean Ignored if the index field was specified. If set to trueindicates that all elements selected by the selector should be included; otherwise set to false.
min_c number An optional field that specifies the minimum length of an element's textContent property for it to be included. The default value is 0.
sub AnchorObj An optional field that specifies a recursive AnchorObj that will select elements within any elements selected at this level of anchor definition.

PlacementStyleObj

The fields to specify in the style configuration object:

Field Name Type Description
top_m number An optional field that indicates the top margin in pixels that an ad inserted in this position should have. Default value: 0.
bot_m number An optional field that indicates the bottom margin in pixels that an ad inserted in this position should have. Default value: 0.

RelativePositionEnum

The ENUM values for the pos field in the placements configuration object:

Name Value Description
BEFORE 1 Ad should be inserted as sibling immediately before the anchor.
FIRST_CHILD 2 Ad should be inserted as the first child of the anchor.
LAST_CHILD 3 Ad should be inserted as the last child of the anchor.
AFTER 4 Ad should be inserted as sibling immediately after the anchor.

PlacementTypeEnum

The ENUM values for the type field in the placements configuration object:

Name Value Description
BANNER 1 Placement describes a banner ad position.

Validation

See amp-auto-ads rules in the AMP validator specification.