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
- AdSense
- Alright
- Denakop
- DoubleClick (experimental)
- FirstImpression.io
- Premium Programmatic
- Wunderkind
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 | Typ | 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:
|
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 | Typ | 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:
|
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:
|
AnchorObj
The fields to specify in the anchor
configuration object:
Field Name | Typ | 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 | Typ | 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 | Typ | 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:
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 | Typ | 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:
|
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.
Вы читали этот документ десятки раз, но так и не нашли ответов на все свои вопросы? Возможно, другие люди столкнулись с такой же проблемой — обратитесь к ним на Stack Overflow.
Перейти на Stack Overflow Нашли ошибку или недостающую функцию?Проект AMP активно поощряет ваше участие и сотрудничество! Мы надеемся, что вы станете постоянным участником нашего открытого сообщества, но разовые вклады в работу над задачами, которые вам особенно интересны, также приветствуются.
Перейти на GitHub