Table of contents

Usage
- Supported ad networks
- Configuration Spec
  - Example Configuration
  - Object Definitions
Attributes
Validation

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 `true`indicates 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