AMP

Important: this documentation is not applicable to your currently selected format stories!

amp-auto-ads

Description

Dynamically injects ads into an AMP page by using a remotely-served configuration file.

 

Required Scripts

<script async custom-element="amp-auto-ads" src="https://cdn.ampproject.org/v0/amp-auto-ads-0.1.js"></script>

Usage

Dynamically injects ads into an AMP page by using a remotely-served configuration file.

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

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)
adConstraints AdConstraintsObj An optional field that specifies the constraints that should be used when placing ads on the page. If not specified then amp-auto-ads will attempt to use the default constraints specified in [ad-network-config.js](https://github.com/ampproject/amphtml/blob/main/extensions/amp-auto-ads/0.1/ad-network-config.js).
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)
stickyAdAttributes Object<string, string> An optional field for a map from attribute name to value for attributes to apply to all <amp-sticky-ad> elements injected using this placement. Only the following attribute names are allowed:
  • 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.
AttributesEnum

The ENUM value indicates attributes from configuration object for different ad formats:

Name Value Description
BASE_ATTRIBUTES attributes Indicates the `attributes` field in the configuration object.
STICKY_AD_ATTRIBUTES stickyAdAttributes Indicates the `stickyAdAttributes` field in the configuration object.
PlacementTypeEnum

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

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

The fields to specify in the adConstraints configuration object:

Field Name Type Description
initialMinSpacing string A required field that indicates the minimum distance that an ad should be from any ads already on the page (either manually placed or previously placed by amp-auto-ads) at the time of insertion. Values are expressed as a number with a units prefix. E.g. "10px" means 10 pixels, or "0.5vp" means half a viewport height. Negative values are invalid. The supported units are:
  • px - pixels
  • vp - multiple of viewport height
This value applies only when the number of ads already on the page is less than any adCount matcher specified in the subsequentMinSpacing field.
subsequentMinSpacing Array<!SubsequentMinSpacingObj> An optional field that specifies the ad spacings that should apply based on how many ads are already on the page at the time of insertion.
maxAdCount number A required field that specifies the maximum number of ads that amp-auto-ads can cause there to be on a page. Both manually placed ads, as well as those placed by amp-auto-ads count towards this total. E.g. if this field were set to 5 and there were 3 manually placed ads on the page, then amp-auto-ads would place a maximum of 2 additional ads.
SubsequentMinSpacingObj

The fields to specify in the subsequentMinSpacing configuration object. subsequentMinSpacing entries can be used to change the spacing required between any additional ads based on the number of ads already on the page. As an example, consider the following scenario:

  • 2 existing ads on the page
  • subsequentMinSpacing field is: [ {adCount: 3, spacing: "500px"}, {adCount: 5, spacing: "1000px"}, ]

Initially there are 2 existing ads on the page, so no mapping matches. The minimum spacing therefore defaults to initialMinSpacing in the AdConstraints object. amp-auto-ads will recursively try to place ads until it runs out of placements that could be used without breaking the adContraints. After amp-auto-ads has placed its first ad, there are now 3 ads on the page, since there is a mapping for 3 (or more) ads in subsequentMinSpacing, the min spacing now becomes 500px. This applies up until the point where there are 5 ads on the page, since there is a rule for 5 ads. Inserting the 6+th ad would then require it to be clear of other ads by at least 1000px.

Field Name Type Description
adCount number A required field. The minimum number of ads already on the page that cause this rule to apply (assuming no other rule is a better match). See description above for a more detailed explanation.
spacing string A required field that specifies the minimum ad spacing that applies when this rule is matched based on the adCount. Values are expressed as a number with a units prefix. E.g. "10px" means 10 pixels, or "0.5vp" means half a viewport height. Negative values are invalid. The supported units are:
  • px - pixels
  • vp - multiple of viewport height

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.

Validation

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

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow
Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub