Facebook Social Walkthrough

Currently Supported API Versions

• Marketing API version 14
• Graph API version 15

Introduction

This document provides detailed instructions on how to configure and use the Facebook Social API integration within Rivery. Rivery supports various Facebook reports that enable users to pull data from Facebook pages, including private and public pages, as well as specific insights related to posts, videos, and feeds.

The document covers the steps to connect your Facebook account to Rivery, select the appropriate pages for data extraction, and choose the relevant report types and metrics. It also outlines the limitations and restrictions, such as the need for admin roles to access certain post fields and Facebook’s rate limits.

Pages

Each Facebook report is associated with one or more Facebook pages.

Viewing Your Facebook Pages

To view the list of Facebook pages you own, click the refresh button after adding your Facebook connection.

If you want to pull data for all the pages owned by your user, you can leave the page selection box empty.

Pulling Data from Non-Owned Pages

To pull data from Facebook pages that you do not own, you need to manually add the relevant page_id.

• The page_id can be found using the Facebook page URL.
  Example: The page_id for https://www.facebook.com/rivery.io is rivery.io.

After selecting the appropriate page(s), you can pull data for the selected pages.

Page Fields

Data can only be pulled from the fields visible in Facebook's public pages, excluding private fields such as Best_page, Access_token, and others.

Facebook Social Reports in Rivery

Rivery supports four types of Facebook reports:

1. Feed Report

   • Returns data about the selected Facebook page feeds (e.g., Likes, Comments, Shares).

   Note:
   Data can be pulled from public Facebook pages or private pages that your Facebook account owns.
   However, public page data may have fewer fields due to Facebook privacy settings.
   Also, Facebook limits data pulls to 200 calls per hour for pages you don’t own. Exceeding this limit will result in errors.

2. Insights - Page

   • Returns data on Facebook page insight metrics such as Impressions, Clicks, etc.
   • Data can only be pulled from private pages owned by your Facebook account.
   • The metrics include reactions from other pages that shared a post, so the numbers might be higher than those shown in the UI. Use the Feed Report for UI-specific metrics.

3. Insights - Post

   • Returns data on the posts of the selected Facebook page(s) such as Impressions, Clicks, etc.

4. Insights - Video

   • Returns video insights for selected Facebook pages, including Impressions, Clicks, etc.
   • Video insights are aggregated across pages. If a video is posted on multiple pages, the insights will be the sum of all those pages.

Feed Report

To pull data for the feed report:

1. Select Metadata Fields
   Choose the metadata fields you wish to include for each reporting level (Feed, Comments, Reactions, etc.).
   You can leave the input box empty to pull all available fields.

2. Tagging or Hidden Posts
   At the bottom of the page, check the relevant boxes to include data on tagged or hidden posts.

   

The feed report will also automatically include the total number of comments and reactions by type (e.g., Happy, Sad, Like) within the selected date range.

Insights Reports

For insights reports:

1. Select Pages
   Choose the pages for which you want to retrieve insights.

2. Select Metadata Fields
   Choose metadata fields relevant to the report level. For example, for post insights, fields will be specific to individual posts.

3. Select Metrics
   Choose the metrics you wish to measure (e.g., Impressions, Views, etc.).

4. Select Metrics Period
   Define the period for which metrics will be calculated (e.g., Daily, Weekly, etc.).

5. Additional Data
   Some reports offer additional data via checkboxes. For example, in the Insights - Posts report, you can include data from "Promotable" (dark) posts in addition to regular posts.

Metrics for each report:

• Metrics starting with page_* are for the Page Insights Report.
• Metrics starting with post_* are for the Post Insights Report.
• Metrics starting with post_video_* are for the Video Insights Report.

Post Fields Restrictions:
To extract post fields for a live video that has ended, you must have an admin role on the post's page.

Fields that require an admin role for access include: description, name, object_id, source, and type.

Metrics

Select the metrics relevant to your insights reports. Common metrics include:

• Impressions
• Views
• Clicks

Metrics Period Resolution

The Metrics Period Resolution defines the time frame over which your metrics are calculated.
For instance, selecting "Daily" for the Impressions metric will return daily results for the selected date range.

Important:
Some metrics may not work with the chosen Metrics Period Resolution. Refer to the Facebook Documentation for more details.

Time Period

For all types of Facebook Social Reports, you can choose the report's time period.

You can select:

• A custom date range (e.g., from a specific start to end date).
• A predefined time period (e.g., Yesterday, Last Week, etc.).

Date Range Selection Instructions:

1. Select the start and end date for the report.
2. Leave the end date empty to pull data until the moment the river runs.
3. The start date will be automatically updated with each run.
4. Choose the time zone offset to adjust the date to your local time zone if the end date is left empty.
5. Use Days back to specify how many days before the start date to pull data.

Note: The start date will not be updated if a river run is unsuccessful unless you choose to advance it even on failure (not recommended).

Ignore Errors for Accounts

You can enable the option to ignore errors for accounts. If an issue arises while generating a report for one or more accounts, the river will continue running without failure.

Facebook Graph API Rate Limitation

The Facebook Graph API enforces rate limits to ensure fair usage across all users and applications. These rate limits differ depending on the type of access token being used, which can either be at the user-level or application-level.

User-Level Rate Limits

Each user is assigned a specific rate limit for API calls. This limit is calculated over a rolling one-hour window. If a user exceeds the allotted number of requests, further requests will be blocked until the usage drops below the threshold. This mechanism ensures that users do not overwhelm the system and that resources are distributed fairly among all users.

Application-Level Rate Limits

For applications, the rate limit is based on the number of active users. The limit is calculated as 200 requests per user per rolling hour, and this limit is shared across all users of the application. Therefore, the total number of requests made by all users contributes to the application’s overall rate limit. It is important for applications to monitor and manage API calls carefully to prevent hitting the application-wide limit.

Monitoring Rate Limits

You can track the current status of your rate limits through response headers in the API calls. One of the most useful headers is X-App-Usage, which provides real-time data on the percentage of the limit being used. Monitoring these headers helps you stay aware of your API usage and adjust your request pacing accordingly.

Best Practices to Avoid Rate Limiting Disruptions

To avoid disruptions due to rate limiting, consider implementing the following best practices:

• Manage Request Pacing: Distribute your API requests over time to ensure that they don’t accumulate too quickly and exceed the rate limits.
• Handle Rate-Limit Responses: Set up your application to detect and handle rate-limit responses (such as HTTP status code 429), so that it can retry the request once the limit window resets.
• Use Request Queuing or Throttling: Implement queuing or throttling mechanisms to control the rate at which API requests are sent, ensuring they stay within the allowable limits.

Impact on Rivery River Runs

Rate limits can also impact the duration of river runs in Rivery. If the API requests exceed the rate limit, the process may pause until the next rate limit window is available. This pause can extend the overall time it takes for a river run to complete. To minimize this impact, it’s essential to optimize API calls and follow the best practices outlined above.