Facebook Instant Articles Integration

Superdesk Publisher has built-in integration with Facebook Instant Articles. This cookbook describes all the steps needed for proper configuration.

Step 1. Register Facebook Page and Application in Publisher

Note

As at the moment of writing this documentation there is no UI in Superdesk for this feature, needed actions will be described with CURL direct API calls.

Note

Any Publisher API request requires authentication. Read more about this here: API authentication

Instant Articles are strongly connected with a Facebook Page. To start you need to enable that feature in Your Facebook Page settings. Once this is set up, call our API to register that page in Publisher.

A Facebook Page can be registered in Publisher with a REST API /api/{version}/facebook/pages/ POST request.

Required parameters:

  • pageId - Unique ID of your Facebook Page
  • name - Facebook Page Name
1
curl -X POST 'http://webpublisher.dev/api/v1/facebook/pages/' -H 'Origin: http://webpublisher.dev' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: */*' -H 'Connection: keep-alive' -H 'DNT: 1' -d "facebook_page[pageId]=1234567890987654321&facebook_page[name]=Test Page" --compressed

The next step is registering the Facebook Application (You need to create it first on the Facebook Platform). The application is used for retrieving never expired access token - it will be used by Publisher in Facebook API calls.

Facebook Application can be registered in Publisher with a REST API /api/{version}/facebook/applications/ POST request.

Required parameters:

  • appId - Unique ID of your Facebook Application
  • appSecret - Generated by Facebook Application secret
1
curl -X POST 'http://webpublisher.dev/api/v1/facebook/applications/' -H 'Origin: http://webpublisher.dev' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: */*' -H 'Connection: keep-alive' -H 'DNT: 1' -d "facebook_application[appId]=1234567890987654321&facebook_application[appSecret]=superS3cretSecretFromFacebook" --compressed

Step 2. Facebook Page/Application authentication

Assuming that in your database you have Application with id 123456789 and Page with id 987654321 (and both it exists on Facebook platform), You need to call this url (route: swp_fbia_authorize): /facebook/instantarticles/authorize/123456789/987654321

In response You will be redirected to Facebook where You will need allow for all required permissions.

After that Facebook will redirect You again to application where (in background - provided by Facebook code will be exchanged for access token and that access) you will get JSON response with pageId and accessToken (never expiring access token).

Step 3. Create Content List (bucket)

In most cases you wouldn’t want to push everything to Instant Articles. Publisher allows you to define rules for articles selected for Instant Articles publication. This solution is based on Content Lists. Content lists allow you to define custom criteria and apply them to every published article - if an article matches the criteria it’s added to that Content List and automatically published to Instant Articles.

Content Lists can be created in Publisher with a REST API /api/{version}/content/lists/ POST request.

Required parameters:

  • name - Content List name
  • type - Content List type, in this case it must be “bucket”
  • expression - (optional) Expression used for testing published articles eg.: article.getPriority() > 4
1
curl -X POST 'http://webpublisher.dev/api/{version}/content/lists/' -H 'Origin: http://webpublisher.dev' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: */*' -H 'Connection: keep-alive' -H 'DNT: 1' -d "content_list[name]=Facebook Instant Articles&content_list[type]=bucket" --compressed

This list don’t have expression parameter defined so it will catch all published articles.

Step 3. Create Feed

Feeds are used to connect Facebook Pages and Content Lists. With them, you can send selected articles to different Facebook Pages.

Feeds can be created in Publisher with a REST API /api/{version}/facebook/instantarticles/feed/ POST request.

Required parameters:

  • contentBucket - Content List id
  • facebookPage - Facebook Page id (from publisher)
  • mode - Instant Article publishing mode: 0 (devlopment) or 1 (production)
1
curl -X POST 'http://webpublisher.dev/api/{version}/content/lists/' -H 'Origin: http://webpublisher.dev' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: */*' -H 'Connection: keep-alive' -H 'DNT: 1' -d "facebook_instant_articles_feed[contentBucket]=1&facebook_instant_articles_feed[facebookPage]=1&&facebook_instant_articles_feed[mode]=0" --compressed

Step 4. Create Instant Article template

An Instant Article is created from parsed template file. The look and feel of Instant Articles can be controlled by template files in the theme. That file must be located here: views\platforms\facebook_instant_article.html.twig. Publisher autmatically attaches current article meta like in regular page template (remember that there is gimme.route set in this case).

Minimal code for Instant Article templates needs to look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
<!doctype html>
<html lang="en" prefix="op: http://media.facebook.com/op#">
    <head>
        <meta charset="utf-8">
        <link rel="canonical" href="{{ url(gimme.article) }}">
    </head>
    <body>
        <header>
            <h1>{{ gimme.article.title }}</h1>
            <time class="op-published" datetime="{{ gimme.article.publishedAt|date("Y-m-d\\Th:i:s\\Z", false) }}">{{ gimme.article.publishedAt|date("Y-m-d h:i ") }}</time>

        </header>
        <p>{{ gimme.article.lead }}</p>
        {{ gimme.article.body|raw }}
    </body>
</html>

The HTML code of the article body (gimme.article.body) will be parsed by Transformer. Transformer will try to match html elements to Instant Articles tags (for example images). If it does not recognize some elements they will be removed. You can preview how your template works with currently published articles here: /facebook/instantarticles/preview/{articleId}.

Note

Preview url is available only in Publisher Development mode. To send that article to FBIA library from preview add ?listId={content bucket Id} to url.

Step 5. Publish Your articles to Facebook Instant Articles

After all previous steps - publishing should happen automatically just after publishing article matching Content List criteria.