Skip to content

Latest commit

 

History

History
310 lines (247 loc) · 13.2 KB

amp-ad.md

File metadata and controls

310 lines (247 loc) · 13.2 KB
Raw

amp-ad / amp-embed

{% call callout('Note', type='note') %} 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. {% endcall %}

Description A container to display an ad. 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.
Availability Stable
Required Script <script async custom-element="amp-ad" src="https://cdn.ampproject.org/v0/amp-ad-0.1.js"></script> Note: amp-ad may still work without this script, but we highly recommend it for future compatibility
Supported Layouts fill, fixed, fixed-height, flex-item, nodisplay, responsive
Examples Annotated code example for amp-ad

Behavior

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 like all resources in AMP. 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.

<amp-ad width=300 height=250
    type="a9"
    data-aax_size="300x250"
    data-aax_pubname="test123"
    data-aax_src="302">
</amp-ad>

<amp-ad width=320 height=140
    type="colombia"
    layout=responsive
    data-clmb_slot="129883"
    data-clmb_position="1"
    data-clmb_section="0">
</amp-ad>

<amp-embed width=400 height=300
    type="taboola"
    layout=responsive
    data-publisher=thepublisher
    data-mode=themode
    data-article=auto
    data-placement="Below Article Thumbnails">
</amp-embed>

Supported ad networks

Supported embed types

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

Attributes

type

An identifier for the ad network. This selects the template that is used for the ad tag.

src

An optional src value for a script tag loaded for this ad network. This can be used with ad networks that require exactly a single script tag to be inserted in the page. The src value must have a prefix that is white-listed for this ad network.

data-foo-bar

Most ad networks require further configuration. This can be passed to the network 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".

json

An optional 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

An optional attribute. If provided, will require 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. The means ad rendering is delayed until the user confirmed the notification.

data-loading-strategy

Instructs AMP to load ads in a way that prefers a high degree of viewability, while sometimes loading too late to generate a view. Supported value: prefer-viewability-over-views.

common attributes

This element includes common attributes extended to AMP components.

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.

<amp-ad width=300 height=250
    type="foo">
  <div placeholder>Have a great day!</div>
</amp-ad>

No Ad available

  • amp-ad supports a child element with the fallback attribute. If supported by the ad network, this element is shown if no ad is available for this slot.
  • If there is no fallback element available, the amp-ad tag will be collapsed (set to display: none) if the ad sends a message that the ad slot cannot be filled and AMP determines that this operation can be performed without affecting the user's scroll position.

Example with fallback:

<amp-ad width=300 height=250 type="foo">
  <div fallback>Have a great day!</div>
</amp-ad>

Serving video ads

AMP natively supports a number video players like BrightCove, DailyMotion etc that can monetize ads. For a full list, see here.

If you use a 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 have to 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:

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 further process the incoming iframe configuration before drawing the ad using AMP's built-in system.

This is supported by passing 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']);

Validation

See amp-ad rules in the AMP validator specification.

Notes

To use <amp-ad> or <amp-embed>, the script to the amp-ad library is needed. It's recommended that you add the script manually; however, currently, it will be automatically fetched when amp-ad is used.