Technical Docs
Integration Docs
Facebook Instant Articles

Facebook Instant Articles

#Start tracking

To add Parse.ly tracking to your Facebook Instant Articles, follow these 4 steps:

#1. Check your existing configuration

Make sure your Instant Articles are already configured and served properly, including the formatting of RSS feeds. For more information on this, please visit Facebook’s Instant Articles documentation.

#2. Set the Parse.ly canonical URL

There is no need to specify metadata on an Instant Article, because that data can be retrieved from the web version. As long as you set the Parse.ly canonical URL to correctly reference the original article, we will automatically associate the metadata with both versions. Set the Parse.ly canonical URL in Facebook Instant Article source code like this:

<link rel="canonical" href="https://blog.parse.ly/post/2109/meet-espns-benjamin-alamar/">

(For more on how the Parse.ly Crawler navigates pages, see "How does the crawler handle posts with multiple URLs?")

#3. Insert the tracking code

Once your Facebook Instant Articles are error-free, insert the following code snippet before the closing </article> tag. For more information on proper tag formatting, please consult Facebook’s analytics documentation.

<!-- Analytics code for your article -->
<figure class="op-tracker">
    <iframe>
        <script>
            PARSELY = {
                autotrack: false,
                fbInstantArticles: true,
                onload: function() {
                    PARSELY.beacon.trackPageView({
                        urlref: 'http://facebook.com/instantarticles'
                    });
                    return true;
                }
            }
        </script>
        <script id="parsely-cfg" src="//cdn.parsely.com/keys/######/p.js"></script>
    </iframe>
</figure>

Replace ###### with your Parse.ly site id, e.g. mysite.com.

This tracking code must be placed on all Instant Articles you wish to track, whether you are manually uploading the articles or syndicating them via Facebook's preferred RSS feed. For more details on automated RSS publication, please consult Facebook's documentation.

#4. Verify data in the Parse.ly dashboard

Once you're tracking FB Instant Articles correctly, you'll see data in the "Channels" tab of your dashboard.

If you don't see any data, check out our troubleshooting tips.

#Understanding Facebook Instant Article tracking

#Unique Visitor Duplication

Facebook does not offer the ability to assign user identifiers that can be linked to those generated by the standard Parse.ly JavaScript tracker on your website. As a result, a reader who views an Instant Article in the Facebook app and later views an article on your own domain will be counted as two visitors instead of one. We account for this fact in our calculation of new vs. returning visitors.

#Engaged Time Tracking

Facebook does not offer the ability to track engagement as accurately as the standard Parse.ly JavaScript tracker does on your website. In Facebook Instant Articles, a user is said to be engaged while the article is displaying on their device. This approximation works because the Facebook application only displays a single page at a time. Engaged time tracking stops when device locks or the Facebook application is put into the background.

If you don't see engaged time for FB Instant articles in your Parse.ly dashboard, please see "Adding engaged time tracking to legacy installations".

#FAQ

#Do I need to provide metadata on FB Instant Article pages?

No. As a rule, the Parse.ly Crawler does not retrieve data from FB Instant Article pages. Instead, when it encounters a FB Instant Article page, it will follow the URL in the <link rel="canonical"> tag as the Parse.ly canonical URL. For more on how the tracker groups URLs across platforms, see "How does the crawler handle posts with multiple URLs?".

#Can I add Parse.ly FB Instant Article tracking via Google Tag Manager?

Yes. Make sure you understand the HTML context that your tag will be inserted into to avoid common mistakes in formatting.

#Can I track FB Instant Article videos in Parse.ly?

No. For a summary of the specific metrics available, see our Channel FAQs.

#Troubleshooting

If you've added the tracking code to your FB Instant Article pages but are not yet seeing data in the Parse.ly dashboard, here are things you should check:

  1. Make sure that on the rendered page, the tracking code is wrapped in just one <figure> and <iframe> tag. (See examples of common mistakes below for patterns to avoid.)
  2. Make sure you add the tracking code to the <body> of the page, not the <head>. We recommend placing the code right before the closing </article> tag.
  3. If using an RSS feed, make sure the analytics code is wrapped within the CDATA section of the <content:encoded> element.

If you've verified all of the above but still aren't receiving data, contact support@parsely.com for additional help.

#Examples of common mistakes

#Incorrect formats

<!-- INCORRECT: Nesting figure wrapper tags -->
<figure class="op-tracker">
    <figure class="op-tracker">
        <iframe>
            <!-- Other analytics code -->
            <!-- Parse.ly analytics code -->
        </iframe>
    </figure>
</figure>

<!-- INCORRECT: Nesting iframe wrapper tags -->
<figure class="op-tracker">
    <iframe>
        <!-- Other analytics code -->
        <iframe>
            <!-- Parse.ly analytics code -->
        </iframe>
    </iframe>
</figure>

<!-- INCORRECT: Multiple iframe tags -->
<figure class="op-tracker">
    <figure class="op-tracker">
        <iframe>
            <!-- Other analytics code -->
        </iframe>
        <iframe>
            <!-- Parse.ly analytics code -->
        </iframe>
    </figure>
</figure>

<!-- INCORRECT: Omitting figure wrapper tags -->
<iframe>
    <!-- Other analytics code -->
    <!-- Parse.ly analytics code -->
</iframe>

<!-- INCORRECT: Omitting iframe wrapper tags -->
<figure class="op-tracker">
    <!-- Other analytics code -->
    <!-- Parse.ly analytics code -->
</figure>

<!-- INCORRECT: Omitting figure wrapper tag class-->
<figure>
    <iframe>
        <!-- Other analytics code -->
        <!-- Parse.ly analytics code -->
    </iframe>
</figure>

#Corrected format

<!-- CORRECT -->
<figure class="op-tracker">
    <iframe>
        <!-- Other analytics code -->
        <!-- Parse.ly analytics code -->
    </iframe>
</figure>

#Adding engaged time tracking to legacy installations

#Legacy documentation

If you are a new Parse.ly customer, you can ignore this section, as it only applies to existing customers who implemented Facebook Instant Articles tracking prior to June 2018. For any customers who implemented tracking on or after June 1st 2018, the tracking code example above is already configured to track engaged time. If engaged time does not appear in your Parse.ly dashboard, a configuration change may be required, so please contact support.

To activate engaged time tracking, search your Facebook Instant Article source template for the line that looks like this:

PARSELY = {
    autotrack: false,

Beneath that line, insert the following line:

    fbInstantArticles: true,

so that it looks like:

PARSELY = {
    autotrack: false,
    fbInstantArticles: true,

and save your template. This enables engaged time tracking for your Facebook Instant Articles.

#Contact us

Please contact Parse.ly support after making the changes above, so that we can ensure the new engaged time data is accurately reflected in your dashboard.

Please allow up to an hour after implementing this change for Facebook Instant engaged time to be reflected in the Parse.ly dashboard: often, however, the change is visible before that.

rocket emoji