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: :doc:`../../internal_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 :code:`/api/{version}/facebook/pages/` POST request. Required parameters: * pageId - Unique ID of your Facebook Page * name - Facebook Page Name .. code-block:: bash 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 :code:`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 :code:`/api/{version}/facebook/applications/` POST request. Required parameters: * appId - Unique ID of your Facebook Application * appSecret - Generated by Facebook Application secret .. code-block:: bash 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 ```````````````````````````````````````````````` .. include:: /bundles/SWPFacebookInstantArticlesBundle/authentication_flow.rst 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 :code:`/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.: :code:`article.getPriority() > 4` .. code-block:: bash 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 :code:`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 :code:`/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) .. code-block:: bash 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: :code:`views\platforms\facebook_instant_article.html.twig`. Publisher autmatically attaches current article meta like in regular page template (remember that there is :code:`gimme.route` set in this case). Minimal code for Instant Article templates needs to look like this: .. code-block:: twig

{{ gimme.article.title }}

{{ gimme.article.lead }}

{{ gimme.article.body|raw }} The HTML code of the article body (:code:`gimme.article.body`) will be parsed by :code:`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: :code:`/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.