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: :doc:`../../internal_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 :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

Next step is registering Facebook Application (You need to create it first on Facebook Platform). 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 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 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 :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
```````````````````

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 :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
```````````````````````````````````````

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: :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 need to look like that:

.. code-block:: twig

    <!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 (: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 he will not recognize some elements then they will be
removed. You can preview how You 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.