This page explains how we use the Facebook Instant Articles (iA) system in conjunction with our WordPress sites at Global Voices. The guide is intended for technical staff site administrators to understand how it works and be able to setup and modify the many moving pieces that make iA work correctly.

What are Instant Articles?

Briefly, Instant Articles is when Facebook controls the display of our posts for mobile visitors who click on them inside Facebook. This is in contrast to the normal system, where the user sees a browser window that loads the mobile version of our site.

When posts come up as iA they load instantly, with a design created by Facebook. This is good because users want fast loading stories and the design looks good. It can be a challenge too, though, because we have to cram our content into the boxes provided by Facebook.

Day to Day iA Testing

All authors on GV will want to integrate a bit of iA vigilance into their workflow. Once Instant Articles are enabled on a site, all posts will be submitted by default, but others will be held back because they have warnings. Importantly some posts will fail to validate in iA for easily fixable reasons, when this happens we want to notice and fix the problem right away, to ensure the post has the best possible reach on Facebook.

There's a lot of post content that is “illegal” in iA for one reason or another. Our iA integration relies on various filters in our code that convert our HTML into the format Facebook demands. Without these filters, ALL our posts would show “no rules defined” errors, but even with them, it's easy to have HTML in a post that blocks it from being published in iA format.

Make sure your post has no warnings

When editing a post, you should see a box called Facebook Instant Articles somewhere on the screen (might be far down, in which case consider dragging it up to a more visible location). This box will tell you the status of your post, and specifically whether there are warnings or not.

If there are no warnings you are probably good, nothing in your post breaks iA, and it will be converted. Remember it's still good to check how your post displays on Facebook Itself (see section Check your post on Facebook itself section below).

If there are warnings (exclamation point in circle icon), then it's best to fix them immediately and get the post back into a “no warnings” (checkmark icon) state.

Fixing warnings

There are a lot of possible warnings, but mostly they are triggered by some HTML that shouldn't be in the post. Most of the time you just need to find the code it mentions, look at what it's doing in the post, and replace it with one of our standard formats. These often crop up because of copy+pasted code from elsewhere or from hand-coded HTML that is off-standard for GV posts.

In the example image here I've entered a totally invalid HTML tag <invalid-html-tag> as a demonstration. Instant Articles correctly identifies the tag as unexpected and says “no rules defined” because we haven't told it what to do with this tag. If you saw this message, you would search the post text for “<invalid-html-tag>” to find where it's used and replace it with something else.

If you ever get stuck and can't resolve iA warnings, please contact your editor or the technical director for assistance.

Note: Some post content will always have warnings

GV uses a lot of special content and formats, especially in the form of [shortcodes], and not all of it can be “cleaned up” to work with iA. In some cases, a post will need to remain invalid and never be iA, because it relies on custom content that can't be replicated in Facebook format. As above, if you can't resolve iA warnings on your post, please contact the technical director for assistance in figuring out if it can be fixed or not.

Check your post on Facebook itself

For published posts on a site using iA anyone can see how they look by using Facebook normally:

• Share the post on FB.
• Use a mobile device to view your share.
• Click on the share to view the iA version of the post.
• Scroll through and make sure all the content is what you expect.

Preview posts on FB Pages Manager App.

The other way of checking a post, if you are a manager of the site's Facebook page is using the FB Pages Manager App, which lets you preview any published post without having to share publicly on Facebook. See the section below for details.

Setting Up iA on a New Site

How does GV use Instant Articles?

We have chosen to use iA to get the benefits of increased traffic and speed. We're planning to use it on all our major sites. To make things easy for each site, we have hard-coded many customizations into our GV Plugin, trying to get all our important content to work with iA and avoiding having to configure the details over and over.

Note that because of the content restrictions on iA, some GV posts will never work with it. In those cases, the plugin should show you warnings that you can use to try to fix the content, or just give up and publish anyway. In cases where a post can't be used with Instant Articles, it will still work on Facebook, users will just see our mobile site (a little slower) rather than an iA version.

The Instant Articles for WP plugin attempts to walk you through the many steps involved in getting iA working for a WP site, but in the hopes of clarifying it further, they will be re-iterated here with a special focus on the parts that are important for a GV site already running GV Plugin, which includes many fixes and customizations that mean you don't have to worry some things.

Create an FB page for the site

In order to associate iA with a site, the site needs a public “Page” of its own. It doesn't have to be popular or even used very much, but it needs to exist for later steps in the process. We won't explain the full process here as it has many steps and should be mostly self-explanatory.

Note on page admins: Please ensure that all pages related to GV sites have a staff member (Tech Director/Lingua Manager) as a “manager”, in case we need to log in and help with settings, or in case we need to take over at some point in the future.

Create an FB “app” for the site

The other aspect of connecting the iA plugin to Facebook is setting up an “app” for the site you want to connect.

• For our purposes an “app” is very simple, we won't use most of the features other than to authenticate the site.
• Each site needs a separate app to function. This is because the app must have a URL set that matches the site, and only one URL can be entered per app.

Creating an app for iA

• Log in to https://developers.facebook.com/apps with your Facebook account that controls the page you created earlier.
• Click the Add a new app button.
• For Display Name please use the name of the site.
• For Contact Email please use webmaster@globalvoices.org
• For Category choose “News” or whatever fits best.
• Click Create App ID and fill out the captcha as necessary.
• You should now be in the manager for your app, click Dashboard to see the main screen.

Configuring an app for iA

• (If you didn't just finish the previous list) Visit https://developers.facebook.com/apps/ and click on your app.
• Click Settings in the sidebar.
• In App Domains field enter the URL of your site.
• Scroll down and click the Add Platform button at the bottom.
• Choose Website from the popup.
• A new box with appear with Site URL field, enter the URL of your site.

Adding other staff as admin of your app

Please make sure you have added relevant staff members (Tech Director/Lingua Manager) as “admins” of your app, in case we need to manage it at some point.

• Click Roles in the sidebar.
• In the Administrators box use the Add Administrators button to add other staff members (Tech Director/Lingua Manager).

Enable and configure Instant Articles for WP plugin

Now that you have a Facebook page for the site and a Facebook App for the site we are ready to configure the Instant Articles plugin inside WordPress.

• Go to Plugins and activate the Instant Articles for WP plugin if it isn't already active.
• Click on Instant Articles link in the admin sidebar.
• Read the overview and click Get Started.

Setting up your App ID+Secret and logging into Facebook

• Click the Get App ID button to open the Facebook Apps dashboard, then click on the app you created (or just use the tab you have open from before)
• Copy the App ID (long number) into the App ID field in the WordPress plugin options.
• Get the App Secret by clicking the Show button in the field (don't copy the •••••• dots!) and copy it into the App Secret field of the WordPress plugin options.
• Click Log in which reloads the page.
• Now you should see a blue Login with Facebook button, click it.
• Click Continue as [yourname] and agree to whatever it requests.
• If all goes well, you'll be taken back to the plugin settings page.

Setting up your page for Instant Articles

• You should see a box called Which Page Would You Like to Use for Instant Articles? Choose the page for this site.
• When the page is highlighted you should see some text and a Sign-up button. Click Sign up.
• In the new window choose your page, click the checkbox to agree to the terms and click Access Instant Articles Tools.
• You should be returned to the plugin options, where you can now choose your page and click the Select button.
• Next, it will tell you to Customize Your Style with Style Editor. Click this button to open a new tab with the many design options.
• You can do the design step now or later, either way, please see the Edit iA styles to match our theme section below for instructions.
• Return to the plugin options tab and click the blue Next button (it's okay if you didn't finish the design step yet).
•  You should now see the Submit for Review box, with information about your recent posts and whether you are ready to submit yet. Don't submit for review yet, read through the rest below first. 
  

Advanced settings

There is a section of options that is hidden by default at the bottom of iA plugin settings page. You can see it by clicking Open Advanced Settings now.

NOTE: You must save the advanced settings ONCE at the start, even if you change nothing! This is needed to make our custom settings get installed.

• Click Open Advanced Settings Now
• Scroll down and click Save Settings
• A yellow box will show at the top to indicate our custom settings are saved.

Most of these settings will be fine on their own because we have automated their values on the backend. Below are a few notes on what should be there.

• Article Style: Leave as default. When you edit the styles (see below) just edit the ‘default’ style.
• Ads: No.
• Analytics: Google Analyticator (GV integration) should be ticked under 3rd party integrations (this is automated based on our Google Analytics pugin).
• Development Mode: This one is useful and important. Use this to turn on the plugin and test posts in the FB Pages app (see below) without making the iA versions of your posts public. Consider turning this on initially for testing, but remember that you won't be able to Submit For Review if you are in Development Mode.
• Custom transformer rules: You should see Enable custom transformer rules already selected (automated) and the box full of code.
• Transformation warnings: Make sure that Publish articles containing warnings is not ticked! This ensures posts that would be broken in iA format are shown as normal web pages to readers.

With all that out of the way, you should be ready for next steps: Setting up the design and reviewing your posts that will be submitted.

Edit iA styles to match our theme

Instant Articles has a surprisingly detailed set of options for controlling the appearance of your stories. We will use these to try to approximate the branding and style used on GV sites. Sorry that this step is so tedious, Facebook doesn't offer a way to quickly clone these values.

Opening the Style options (assuming you don't have the tab open already)

• Visit your page on Facebook.
• Click Publishing Tools from the menu at the top.
• In the sidebar menu find the Instant Articles section and click on Configuration.
• In the Tools section at the bottom click on the Styles box.
• Click on the default box to open up the style editor (we will use the “default” config for simplicity).

Styles to configure

These should be listed in the order they appear in the Styles editor from top to bottom. Any styles unmentioned (most) can be left with default values. Make sure you click “default” and see “Save” without “create” on the left. “Create” will make your changes unsavable because of “duplication”.

For RTL sites, please change every “align” value from “left” to “right”.

• Logo
  • Logo File: Download and use this image file for core GV/Lingua sites.
  • Color: In the pulldown menu choose Bottom Border
  • Color: In the color box enter #BBBBBB
• Title
  • Typeface: Helvetica Neue Condensed Bold
• Subtitle
  • Typeface: Helvetica Neue
  • Type Color: #666666
• Byline 
  • Type Color: #666666
  • Line Height: .9x
  • Text Size: 1.2x
• Primary Heading
  • Typeface: Helvetica Neue Condensed Bold
• Secondary Heading
  • Typeface: Helvetica Neue Condensed Bold
• Body Text
  • Typeface: Meta Serif Pro Book
• Inline Link
  • Type Color: #1287c8
• Block Quote
  • Typeface: Meta Serif Pro Book
• Pull Quote
  • Typeface: Meta Serif Pro Book
• Small Caption Description
  • Text Size: 1.2x
• Footer, Credits, and Copyright
  • Text Size: 1.2x

When you are done click Save to save your settings then Close.

Review recent posts for errors

Before your posts will show as iA for readers you need to have at least 5 posts successfully validated and submitted as iA articles. Once that is ready you do a formal “Submit for Review” then wait 1-3 days for them to approve. After that users will see your posts as iA.

The plugin tries to streamline this process by checking your 5 most recent published posts and making a list of any that have errors blocking them from being converted into iA.

If you get to this step and there are posts listed, you'll have to find a way to get them to be “valid”. Note that just because posts aren't listed, doesn't mean there will be no errors after you submit for review! Please follow these steps for a few recent posts either way:

• Open the post editor (the plugin settings page will link to it)
• Find the Instant Articles box (in the column below the post content by default).
• Read any blue error messages and try to understand them.
• Look in the article for unusual formatting related to the error message.
• If you can't figure it out use Edit Flow to add the webmaster user to the post and ask for help clearing up the error.

This is a process you will need to get used to, as it will essentially apply to all posts going forward if you want them to take advantage of the benefits of Instant Articles. See Day to Day iA Testing section above for more details.

The initial submit for review cannot contain errors. So unlike going forward, you will need to have all 5 recent posts be totally valid. This may mean temporarily removing custom content that causes iA invalidity. Once a site is finished with this initial process it is okay for some posts to remain invalid and just never be shown as iA.

Submit the site for review

• Go to the plugin settings in the wp-admin sidebar Instant Articles.
• If there is a green Submit for review button then your recent posts are considered valid and you can submit them for review.
  • IMPORTANT! THIS IS BROKEN: As of Feb 2017 the “Submit for Review” button in the plugin has a bug that makes it always fail, with a vague “Permissions Error” message after a long wait.
  • So we need to submit directly from Facebook's site, rather than using the plugin.
    • Visit your page on Facebook.
    • Click Publishing Tools from the menu at the top.
    • In the sidebar menu find the Instant Articles section and click on Configuration.
    • Find the blue Submit for Review button and if there are no warnings, push it!
  • Once you've submitted your site for review the plugin settings screen will update and show your new status (awaiting review), so you can use it to check if you've been approved yet.
• Only after the review is approved will the posts show to normal users of iA.
• In the meantime, you can preview your posts in the FB Pages Manager App (See section below)
• See Day to Day iA Testing section above for validating posts.

FB Pages app: Test iA version of posts

While the Instant Articles box in the post editor is useful for knowing if the post has errors or not, it doesn't let you see how your post will look in iA, so even though a post may appear valid, it is still important to review their final output.

For most authors, the only way to do this will be to publish your post (without any iA errors so it gets submitted) then share it to Facebook, then use your phone to view the share, which will show you the iA version.

If you are the manager of this site's Facebook page, you have another option: The Pages app from Facebook. 

The pages app lets you log into your Facebook account and manage any pages you own with great detail. One of it's many features is allowing you to preview iA posts without sharing them first. This can be a LOT more convenient for reviewing many posts or reviewing a new post before sharing it to Facebook, in case it needs more work.

Importantly, the Pages Manager App works even before the site is finished the “Submit for review”, so it's the most important way to check that all your content is doing what you expect before you Submit For Review and normal visitors start seeing the iA version.

• Download FB Pages Manager App.
• Log in and find your page.
• From the page overview screen, click the “…” icon in the bottom right, then find Instant Articles in the list.
• At the top of the Instant Articles screen are three tabs:
  • Production: Posts you've submitted to actual iA and which will be shown to users if your site has been approved.
  • Development: Posts submitted while the iA WP plugin was set to “Development mode”. You can review them, but they won't be shown to users unless the plugin setting is changed and the post is resaved.
  • Examples: Several demo posts from Facebook, showing how it SHOULD look (rarely useful).
  • From here you can click through to any of the posts you've saved as iA and see how they look.

If there are no posts in the Instant Articles section of your page:

• Make sure the plugin is enabled and configured on the site and that you are looking at the correct tab in the Pages app (Development if development mode is enabled in the plugin's Advanced Settings).
• Make sure that when you save posts the Instant Articles box of the post editor is showing success messages. If there are invalid parts of the post then it will never be sent.
• Make sure you have saved posts AFTER enabling the plugin and getting logged in to the plugin settings page. Go save some new posts and see if they show up.