# 1. **Objective**

This guide outlines the proposed implementation of a method to collect **Facebook Page Insight data** using the **Facebook Graph API**. The objective is to streamline the process of gathering insights from Facebook Pages, including user interactions, engagement, and audience demographics, for analytical purposes.

# 2. **Overview**

Facebook Page Insights provide data that help administrators understand the performance of their Facebook Pages. This includes metrics like page impressions, unique visitors, l**ikes, shares, and more. The data can be collected programmatically using** Facebook's Graph API, requiring access tokens to authenticate and authorize data retrieval.

# 3. **Authentication Flow**

The process to obtain Facebook Page Insights data relies on an access token system. Below are the necessary steps to retrieve this data:

## 3.1 **Access Token Types**

There are different types of access tokens in the Facebook ecosystem:

- **User Access Token**: Allows the app to access the user’s Facebook account and can be used to request a Page Access Token.
- **Page Access Token**: Grants permission to access a Facebook Page's data. It is used to read, write, and manage the page’s content.

> Refer to Facebook’s documentation on [Access Tokens](https://developers.facebook.com/docs/facebook-login/guides/access-tokens) for more information.
>

## 3.2 **Token Flow**

To retrieve Facebook Page Insights, the following flow is required:

1. **App Setup**: A Facebook app must be created and configured with the necessary permissions to manage Facebook Pages.
2. **User Permission Request**: Admin users of the Facebook Pages need to grant permission to the Facebook app. This results in the generation of a **User Access Token**.
3. **Retrieve Page Access Token**: Use the User Access Token to request a **Page Access Token** via the Graph API.
4. **Request Insights**: Using the Page Access Token, make API requests to fetch insights for the Facebook Page.

# 4. **Implementation Steps**

## 4.1 Create Meta App and perform App Review

### Register as an Meta Developer

https://developers.facebook.com/docs/development/register/

### Create Meta App

Go to: https://developers.facebook.com/apps/creation/

- Choose **Other** in App Use Case
- Choose **Business** in App Type
- Fill in App name, Contact email

### Submit information for App Review

After create the Meta App, we can proceed with submitting information before the app can be used for Production (otherwise it’s only usable for users with roles in the app)

- Go into the App Basic Settings to fill in all the basic information (business verification can be skipped)
- Change the mode of the App from Development → Production
- Submit an App Review

## 4.2 Retrieve Facebook Page Insight Data

### Obtain User Access Token

Admins of the Facebook Page must log in via the Facebook app and grant access. Once access is granted, the user receives a **User Access Token**.

Example cURL command:

# Replace APP_ID and REDIRECT_URI with your Facebook App details
https://www.facebook.com/v20.0/dialog/oauth?
  client_id={APP_ID}
  &redirect_uri={REDIRECT_URI}
  &scope=pages_read_engagement,pages_show_list,read_insights

### **Retrieve Facebook Page Token**

Using the User Access Token, you can retrieve a list of pages that the user administers along with the corresponding **Page Access Tokens**.

Example cURL command to retrieve pages:

curl -i -X GET "https://graph.facebook.com/me/accounts?access_token={USER_ACCESS_TOKEN}"

### **Request Facebook Page Insights**

After obtaining the Page Access Token, you can request insights for the Facebook Page by using the Facebook Graph API. Insights provide detailed metrics like engagement, impressions, and reach.

Example cURL command to retrieve Page Impressions (Unique):

curl -i -X GET "https://graph.facebook.com/v20.0/{PAGE_ID}/insights/page_impressions_unique?access_token={PAGE_ACCESS_TOKEN}"

# 5. **Supported Metrics**

Facebook Page Insights offer a variety of metrics. These include:

- **Page Impressions**: Total views of the Page.
- **Page Likes**: Total number of people who liked the Page.
- **Page Reach**: The total number of unique people who saw the content on the Page.

For a full list of available metrics, refer to the [Page Insights Metrics](https://developers.facebook.com/docs/graph-api/reference/insights).

# 6. **Rate Limiting and Permissions**

Ensure the app has the appropriate permissions to query the Facebook Page Insights.

- `pages_read_engagement`
- `read_insights`
- `pages_show_list`

Additionally, Facebook enforces rate limits on API requests. Implement retry logic and error handling for scenarios where rate limits are exceeded.

# 7. **SDK Integration**

For convenience, Facebook provides SDKs that simplify the process of interacting with the Graph API. The [Facebook Python SDK](https://facebook-sdk.readthedocs.io/en/latest/api.html) allows for programmatic access to the API and can handle token management.

import facebook

graph = facebook.GraphAPI(access_token='PAGE_ACCESS_TOKEN', version="3.0")
page_insights = graph.get_object('me/insights/page_impressions_unique')

# 8. **Error Handling and Logging**

In cases of API failure or invalid access tokens, error handling is necessary. Monitor for:

- Expired tokens
- Permission issues
- Rate limit errors

Implement appropriate logging for API requests and responses to track the success and failures of data retrieval.

# 9. **Security Considerations**

- **Token Management**: Ensure that tokens are stored securely.
- **Privacy**: Be mindful of Facebook’s data privacy guidelines. Only request data necessary for your use case, and ensure proper consent from Facebook Page administrators.

# 10. **Conclusion**

This method provides a structured way to collect and analyze Facebook Page Insight data using the Facebook Graph API. By following the authentication flow, leveraging access tokens, and using appropriate API calls, administrators can programmatically gather insights to enhance social media strategies.