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

amp-ad

Description

A container to display an ad.

Required Scripts

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

Supported Layouts

fill fixed fixed-height flex-item fluid intrinsic nodisplay responsive

Usage

The amp-embed is an alias to the amp-ad tag, deriving all of its functionality with a different tag name. Use amp-embed when semantically more accurate. AMP documents only support ads/embeds served via HTTPS.

The specification of amp-ad / amp-embed is likely to significantly evolve over time. The current approach is designed to bootstrap the format to be able to show ads.

Ads are loaded like all other resources in AMP documents, with a special custom element called <amp-ad>. No ad network-provided JavaScript is allowed to run inside the AMP document. Instead, the AMP runtime loads an iframe from a different origin (via iframe sandbox) as the AMP document and executes the ad network’s JS inside that iframe sandbox.

The <amp-ad> requires width and height values to be specified according to the rule of its layout type. It requires a type argument that select what ad network is displayed. All data-* attributes on the tag are automatically passed as arguments to the code that eventually renders the ad. What data- attributes are required for a given type of network depends and must be documented with the ad network.

Example: Displaying a few ads

<amp-ad
  type="a9"
  data-amzn_assoc_ad_mode="auto"
  data-divid="amzn-assoc-ad-fe746097-f142-4f8d-8dfb-45ec747632e5"
  data-recomtype="async"
  data-adinstanceid="fe746097-f142-4f8d-8dfb-45ec747632e5"
  width="300"
  height="250"
  data-aax_size="300x250"
  data-aax_pubname="test123"
  data-aax_src="302"
>
</amp-ad>
<amp-ad
  width="300"
  height="250"
  type="industrybrains"
  sticky="bottom"
  data-width="300"
  data-height="250"
  data-cid="19626-3798936394"
>
</amp-ad>
<amp-embed
  type="taboola"
  width="400"
  height="300"
  layout="responsive"
  data-publisher="amp-demo"
  data-mode="thumbnails-a"
  data-placement="Ads Example"
  data-article="auto"
>
</amp-embed>

Open this snippet in playground

Placeholder

Optionally, amp-ad supports a child element with the placeholder attribute. If supported by the ad network, this element is shown until the ad is available for viewing. Learn more in Placeholders & Fallbacks.

<amp-ad width="300" height="250" type="foo">
  <div placeholder>Loading ...</div>
</amp-ad>

No ad available

If no ad is available for the slot, AMP attempts to collapse the amp-ad element (that is, set to display: none). AMP determines that this operation can be performed without affecting the user's scroll position. If the ad is in the current viewport, the ad will not be collapsed because it affects the user's scroll position; however, if the ad is outside of the current viewport, it will be collapsed.

If this is a sticky ad unit (sticky attribute is set), the entire sticky ad will not be displayed without regards to fallback attribute.

In the case that the attempt to collapse fails. The amp-ad component supports a child element with the fallback attribute. If there is a fallback element in presence, the customized fallback element is shown. Otherwise AMP will apply a default fallback.

Example with fallback:

<amp-ad width="300" height="250" type="foo">
  <div fallback>No ad for you</div>
</amp-ad>

Serving video ads

There are 3 ways to monetize videos in AMP with video ads:

AMP natively supports a number video players like BrightCove, DailyMotion, etc. that can monetize ads. For a full list, see the media components.
Use the amp-ima-video component that comes with a built-in IMA SDK and HTML5 video player
If you use a video player that is not supported in AMP, you can serve your custom player using amp-iframe. When using amp-iframe approach: _ Make sure there is a poster if loading the player in the first viewport. Details. _ Video and poster must be served over HTTPS.

Running ads from a custom domain

AMP supports loading the bootstrap iframe that is used to load ads from a custom domain such as your own domain.

To enable this, copy the file remote.html to your web server. Next up add the following meta tag to your AMP file(s):

<meta
  name="amp-3p-iframe-src"
  content="https://assets.your-domain.com/path/to/remote.html"
/>

The content attribute of the meta tag is the absolute URL to your copy of the remote.html file on your web server. This URL must use a "https" schema. It cannot reside on the same origin as your AMP files. For example, if you host AMP files on www.example.com, this URL must not be on www.example.com but something-else.example.com is OK. See "Iframe origin policy" for further details on allowed origins for iframes.

Security

Validate incoming data before passing it on to the draw3p function, to make sure your iframe only does things it expects to do. This is true, in particular, for ad networks that allow custom JavaScript injection.

Iframes should also enforce that they are only iframed into origins that they expect to be iframed into. The origins would be:

your own origins
https://cdn.ampproject.org for the AMP cache

In the case of the AMP cache you also need to check that the "source origin" (origin of the document served by cdn.ampproject.org) is one of your origins.

Enforcing origins can be done with the 3rd argument to draw3p and must additionally be done using the allow-from directive for full browser support.

Enhance incoming ad configuration

This is completely optional: It is sometimes desired to enhance the ad request before making the ad request to the ad server.

If your ad network supports fast fetch, then please use Real Time Config (RTC). (e.g. DoubleClick and AdSense integrations both support fast fetch and RTC)

If your ad network uses delayed fetch, you can pass a callback to the draw3p function call in the remote.html file. The callback receives the incoming configuration as first argument and then receives another callback as second argument (Called done in the example below). This callback must be called with the updated config in order for ad rendering to proceed.

Example:

draw3p(function(config, done) {
  config.targeting = Math.random() > 0.5 ? 'sport' : 'fashion';
  // Don't actually call setTimeout here. This should only serve as an
  // example that is OK to call the done callback asynchronously.
  setTimeout(function() {
    done(config);
  }, 100)
}, ['allowed-ad-type'], ['your-domain.com']);

Attributes

`type` (required)

Specifies an identifier for the ad network. The type attribute selects the template to use for the ad tag.

`sticky` (optional)

Use to denote that this is a sticky ad unit and specify the position of this unit. Its value must be one of:

top
bottom
bottom-right
left
right

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

`data-vars-foo-bar`

Attributes starting with data-vars– are reserved for amp-analytics vars.

`src` (optional)

Use this attribute to load a script tag for the specified ad network. This can be used for ad networks that require exactly a single script tag to be inserted in the page. The src value must have a prefix that is allow-listed for the specified ad network, and the value must use https protocol.

`json` (optional)

Use this attribute to pass a configuration to the ad as an arbitrarily complex JSON object. The object is passed to the ad as-is with no mangling done on the names.

`data-consent-notification-id` (optional)

If provided, requires confirming the amp-user-notification with the given HTML-id until the "AMP client id" for the user (similar to a cookie) is passed to the ad. This means that ad rendering is delayed until the user confirms the notification.

`data-loading-strategy` (optional)

Instructs the ad to start loading when the ad is within the given number of viewports away from the current viewport. Without the data-loading-strategy attribute, the number is 3 by default. You can specify a float value in the range of [0, 3] (If the value is not specified the value is set to 1.25).

Use a smaller value to gain a higher degree of viewability (i.e., increase the chance that an ad, once loaded, will be seen) but with the risk of generating fewer impressions (i.e., fewer ads loaded). If the attribute is specified but the value is left blank, the system assigns a float value, which optimizes for viewability without drastically impacting the impressions. Note, specifying prefer-viewability-over-views as the value also automatically optimizes viewability.

`data-ad-container-id` (optional)

Informs the ad of the container component id in the case of attempting to collapse. The container component must be an <amp-layout> component that's parent of the ad. When the data-ad-container-id is specified, and such a <amp-layout> container component is found, AMP runtime will try to collapse the container component instead of the ad component during no fill. This feature can be useful when an ad indicator is in presence.

title (optional)

Define a title attribute for the component to propagate to the underlying <iframe> element. The default value is "Advertisement".

common attributes

This element includes common attributes extended to AMP components.

Styling

<amp-ad> elements may not themselves have or be placed in containers that have CSS position: fixed set (with the exception of amp-lightbox and sticky ad unit). This is due to the UX implications of full page overlay ads. It may be considered to allow similar ad formats in the future inside of AMP controlled containers that maintain certain UX invariants.

Validation

See amp-ad rules in the AMP validator specification.

Supported ad networks

Supported embed types

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