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:
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.
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.
To add a logo to the identity bar:
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.
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.
Use the Style Editor to create or modify the styles used for typographic elements that appear in your articles:
Use custom colors to highlight certain words or inline links in the Article Body, as demonstrated by the example below.
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.
Captions are specified using the standard HTML
<figcaption> element. To attach a caption to a media element within an Instant Article:
<figcaption>element inside the
<figure>element that defines the media element.
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.
To add embedded content to an Instant Article, embed the full, unescaped HTML within the
<iframe> <h1 class="...">Hello World</h1> </iframe>
Do not insert escaped HTML in the
<iframe srcdoc="<h1 class="...">Hello World</h1>"></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.
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:
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.
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>
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.
<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:
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: