Facebook Instant Articles Integration

Superdesk Publisher have build in integration with Facebook Instant Articles. This cookbook describes all steps needed for proper configuration.

Step 1. Register Facebook Page and Application in Publisher

Note

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

Note

Publisher API request require authentication. Read more about this here: API authentication

Instant Articles are strongly connected with Facebook Page. To start you need to enable that feature in Your Facebook Page settings. After that call our API to register that page in Publusher.

Facebook Page can be registered in Publisher with 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

Next step is registering Facebook Application (You need to create it first on Facebook Platform). 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 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 of the cases you don’t want to push everything to Instant Articles. Publisher allows to define rules for articles selected for Instant Articles publication. This solution is based on Content Lists. Content list allows You to define custom criteria and check them on every published article - if article matches criteria then it’s added to that Content List and automatically published to Instant Articles.

Content List can be created in Publisher with 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

Feed’s are used to connecting Facebook Pages and Content Lists. Thanks to them, you can send selected articles to different Facebook Pages.

Feed can be created in Publisher with 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

Instant Article is created from parsed template file. Look and feel of Instant Article can be controlled by templates files in theme. 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 need to look like that:

 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>

HTML code of 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 he will not recognize some elements then they will be removed. You can preview how You 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.