If you include ads within the web version of your articles, you can also include ads in the Instant Article version as well. Ads in Instant Articles are rendered with a "Sponsored" heading to distinguish them from the body content of your article, indicating to your reader that the content is an ad.

Ads are defined using the standard HTML <figure> element, which wraps an <iframe> element containing the markup for your ad. To embed an ad in your Instant Article, apply the op-ad class to a <figure> element.

Ad Sizing

For the best reader experience, specify default height and width attributes in the <iframe> element. This will prevent text and other elements from moving around on the page as the ad loads. If a single ad template might include multiple ad sizes, specify your most common ad size.

Instant Articles also features dynamic ad sizing:

  • If you do not define the height and width for an ad, the ad will be automatically sized to fit the display screen based on the response from the ad server.

  • If a specific size is defined but the ad server returns a different size, the ad will be automatically sized.

The heights of ads in relation to their widths cannot exceed a 2:3 ratio in Instant Articles. Any ads that exceed the 2:3 aspect ratio will be automatically cropped from the bottom.

Ad Placement

Ads can be automatically placed within your Instant Articles in order to simplify the insertion of ads within your content. Automatic ad positioning is specified on a per-article basis, using the fb:use_automatic_ad_placement tag in the Article element.

For more information on the automatic placement of ads, refer the Ad Placement section in Monetization with Instant Articles.

Ads must take up the full size of the <iframe>. Make sure you are not including any margin or padding, so that the edges of the ad are flush with the edges of the <iframe>.

Ad Events

To help track behavior around direct sold ads, Instant Articles exposes several user interactions as JavaScript messages. You can also use these signals to customize ad behavior, for example starting autoplay (sound off) video when an ad enters the viewport or stopping autoplay video when an ad exits the viewport. The following events are available:

  1. enters_viewport message will be triggered when ad enters viewport
  2. center_enters_viewport message will be triggered when center of ad enters viewport
  3. center_exits_viewport message will be triggered when center of ad exits viewport
  4. exits_viewport message will be triggered when ad exits viewport

This example code shows how to listen for ad events.


Name Description Definition


The height of your ad.

Add the height attribute to the <iframe> element wrapping your code.

Source [required]

The source of the content for your ad.

Add your ad in one of the following methods:

  • Specify the URL pointing to the source for your ad.
  • Embed the full unescaped HTML and scripts as content within the <iframe> element representing this ad.


The width of your ad.

Add the width attribute to the <iframe> element wrapping your code.


URL to source of ad

If your ad can be served directly from a specific URL, you can specify the URL using the src attribute on the <iframe> element.

<figure class="op-ad">
    <iframe src=";adtype=banner300x250" height="300" width="250"></iframe>

Embed full source of ad

You can also embed the full unescaped set of HTML and scripts for your ad as text content within the <iframe> element. The document origin of the embed will be the canonical URL of the article.

<figure class="op-ad">
    <iframe height="300" width="250">
        <!-- Include full ad code here -->

Listening for ad events

Ad events implement the MessageEvent interface and are dispatched at the window object. To listen for ad events, use the following JavaScript:

<figure class="op-ad">
  <iframe height="300" width="250">
        window.addEventListener('message', receiveMessage);

        function receiveMessage(event) {
          if ( === 'enters_viewport') {
            // ad entered viewport