Common Errors and Troubleshooting Tips

This document provides guidance on how to correct common causes of errors in Instant Articles and how to optimize Instant Articles performance. The content of this document will be updated as new questions arise.

You’ll find tips on the following subjects here:

Common Errors

Embed Troubleshooting

Ad Troubleshooting

JavaScript Troubleshooting

Tool Access Troubleshooting

Common Errors

Here are a few tips to help you avoid simple design and technical bumps when publishing articles. We've learned a lot from our early partners and hope this knowledge will help you get through the article review process more quickly, continue to publish new articles mistake-free, and create great article experiences for your readers.

Missing Logo

The Mistake

We've noticed that some articles are missing logos. Logos not only associate articles with specific publishers, but also help publishers gain brand recognition.

All articles must include a logo, which you should upload in the Style Editor.

The Easy Solution

To add a logo to the identity bar:

  1. Go to 'Publishing Tools' on your Page.
  2. Click 'Configuration' under the 'Instant Articles' header in the left navigation menu.
  3. Scroll to the 'Styles' panel. Click into one of your existing style templates or click '+ Add Style' to create a new template.
  4. Click the 'Upload Logo' button in the 'Identity Bar' at the top of the Style Editor. Don't forget to use the logo scaler (click the 'Resize Logo' button) to set the logo's size correctly. Logos that are either too small or too large can detract from the article experience.

Examples

In the example above, you'll notice that there is no logo in the identity bar (located above the article title). Publishers must include a logo in the identity bar, as seen in the example below.

Lack of Custom Styling

The Mistake

We've spotted many articles that do not take advantage of custom styling opportunities. Not only does custom styling help define your brand within articles, but it also makes your articles more visually compelling.

Your Instant Articles should include at least the same degree of custom styling as in their web versions. However, we recommend using special, easy to add, Instant Article features that set your articles apart from their web versions.

The Easy Solution

Use the Style Editor to create or modify the styles used for typographic elements that appear in your articles:

  1. Go to 'Publishing Tools' on your Page.
  2. Click 'Configuration' under the 'Instant Articles' header in the left navigation menu.
  3. Scroll to the 'Styles' panel.
  4. Click into one of your existing style templates or click '+ Add Style' to create a new template.
  5. Choose to customize any of the 24 text elements (i.e. color, size, and font) and include them in your kicker, title and subtitle, byline, quotes and headings.
  6. Learn more about creating and modifying styles, as well as how to add them into your articles here.

Examples

Use custom colors to highlight certain words or inline links in the Article Body, as demonstrated by the example below.

Missing Captions

The Mistake

Some articles exclude captions. Captions should be added to the following media to provide more information about them: Images, Videos, Slideshows, Maps, Social Embeds, and Interactive Graphics. You can choose for your captions to render above, below or superimposed on top of the media element.

If you include caption elements, such as caption title, caption body, and caption credit, in the web version of an article, then you must ensure that they appear and are correctly styled in the Instant Article.

The Easy Solution

Captions are specified using the standard HTML <figcaption> element. To attach a caption to a media element within an Instant Article:

  1. Go to 'Publishing Tools' on your Page.
  2. Click 'Instant Articles' in the left navigation menu.
  3. Click the 'Edit' pencil icon to the right of the post you would like to add styled captions to.
  4. Insert a <figcaption> element inside the <figure> element that defines the media element.
  5. Further customize your captions by specifying the alignment and choosing among four font sizes.
  6. Learn more about your customized caption options and how to implement them here.

Examples



In the example above, the image is missing a caption. Publishers must include image captions, below images, as shown below, or above or superimposed on top of the image.

Embed Troubleshooting

How to insert unescaped HTML directly in an iframe

To add embedded content to an Instant Article, embed the full, unescaped HTML within the <iframe>:

<iframe>
  <h1 class="...">Hello World</h1>
</iframe>

Do not insert escaped HTML in the srcdoc attribute:

<iframe srcdoc="&lt;h1 class=&quot;...&quot;&gt;Hello World&lt;/h1&gt;"></iframe>

Although embedding child elements directly within an <iframe> is non-standard HTML, it is supported in Instant Articles. This is why we also support the HTML srcdoc attribute. The unescaped approach simply makes it easier to read the markup.

Ad Troubleshooting

If you see empty ads in your Instant Articles

Empty ads are blank spaces in an Instant Article where ads should be inserted but are not displaying.

The most common root causes of empty ads are the following:

  1. No/Low Ad Inventory. Low ad inventory, targeting restrictions or frequency or user caps may be causing ad requests to go unfilled. If you are using Audience Network, try moving it up in your waterfall. If you are not using Audience Network currently, consider adopting it to backfill empty ad slots. Instant Articles ads policies require that all ad requests return ads in response.
  2. Programmatic Ads. As part of our ads policies, we do not allow the usage of any programmatic advertising. We ask that you remove or replace any programmatic ads with direct sold ads or ads delivered from Audience Network. While programmatic sales are not allowed, we do allow third-party ad serving for ads sold directly.
  3. Latency. If you are hosting ads on your own domain or any 3rd-party ad servers, check to ensure there is little to no latency on your ad server. Latency is the lag time between an ad request and when the ad creative returns.

If your Ad doesn't load in an Instant Article

If your ad won't load in an Instant Article, troubleshooting begins by verifying that it renders properly on the web. If the ad loads in a standard web browsertext, it should also load inside an Instant Article.

To verify a static ad, find the Instant Articles markup for the ad in an article. It should look like this:

<iframe class="op-ad" src="www.adwebsite.com" ...></iframe>

Copy the ad URL from inside the src parameter and open it in the browser of your choice. Verify that you can view the ad in the browser.

If your ad is served from a service such as DoubleClick for Publishers, or if it requires any other HTML or JavaScript, use this verification process:

  1. Create a text file on your desktop called index.html
  2. Open and view your article markup (via the Instant Articles Admin Tools on your page). Copy everything inside the iframe and paste it into the index.html file on your desktop.
  3. Save index.html and try double-clicking it. The ad should open in your browser.
  4. If the ad doesn't load after you double-click on it, try opening the index.html file directly from your web browser (Chrome, Safari, IE, Firefox, etc.)

If the ad still doesn't load, that's often because some part of the ad's HTML or JavaScript isn't working correctly.

Using relative URLs in the iframe is a common cause of ad errors. This can happen if you are reusing HTML from a different website in the Instant Article. In such cases, the preferred solution is to use an absolute URL instead. However, if you have to use a relative URL, use the HTML <base> element within the iframe to specify your base domain, as shown:

<figure class="op-ad">
  <iframe height="60" width="320">
    <base href="http://www.adwebsite.com/">
    <img src="/relative/path/to/image.png" alt="...">
  </iframe>
</figure>

If the ad/embed loads, but it's the wrong size

Ads or embeds may be displayed in the wrong size if the height and/or width of the iframe is specified incorrectly .

For social embeds, it's best to simply omit the height and width attributes and let Instant Articles automatically determine the correct size.

For ads, verify that the height and width of the iframe are set to match the size of the ad content, and that no padding or spacing is contained in the iframe.

Please see the Format Reference for additional details.

JavaScript Troubleshooting

How to debug JavaScript in an iframe

If you suspect the JavaScript in an Instant Articles iframe is misbehaving, remote debugging tools are the first things to try. Remote debugging tools provide an interactive remote JavaScript console, similar to the console in your browser's developer tools, where you can remotely execute code within the iframe, or access logs and uncaught exceptions.

Here are a few free, open-source remote JavaScript tools:

These tools allow you to drop in a piece of JavaScript to relay console messages and exceptions to a server where you can access the output. Some tools have hosted servers available, while others require you to set up your own server. See each of the individual links above for detailed instructions on how to use the tools.

As an example, let's use jsconsole.com to test some JavaScript:

  1. Go to http://jsconsole.com/?:listen to generate a unique key.
  2. Copy the script code snippet and paste it into the source code of the iframe you are debugging. It should look something like this:
<iframe>
  <script src="http://jsconsole.com/remote.js?YOUR-UNIQUE-KEY-HERE"></script>
  <script>
    // Your js here
  </script>
</iframe>

Now, when your script outputs to the console or throws exceptions, the output appears on jsconsole.com. You can also execute code from here, which will then run in the iframe on your device.

Two words of caution:

  1. These JavaScript tools are not developed or supported by Facebook.
  2. Take extra care if you are using a hosted service, to ensure you don't accidentally send sensitive or confidential information to a publicly available endpoint.

Tool Access Troubleshooting

You must be an Analyst, Admin or Editor of your Page to see Instant Articles tools. The same applies to be able to preview Instant Articles on the Pages Manager mobile app. If you do not currently have one of those roles, you can be added two different ways:

  1. Use your organization's Business Manager account to edit roles on the Page.
  2. Use the Page Roles tab under Settings on your Page to edit roles on the Page.