Facebook Business SDK for Python

The SDK follows a CRUD (Create, Read, Update, Delete) design pattern. Most objects are instances of AbstractObject or AbstractCrudObject located in facebook_business.adobjects.

Key methods available on many ad objects include:

• api_get: Read properties from the API.
• api_update: Sync local changes to the server.
• api_delete: Remove the object.
• create_xxx: Create a new instance of the object (e.g., create_campaign).
• get_xxx: Retrieve related objects or edges.

Note: Avoid using deprecated methods like remote_create, remote_read, remote_update, or remote_delete as they may be removed in future versions.

To improve network performance, you can group multiple API calls into a single HTTP request using FacebookAdsApiBatch.

1. Create a batch instance from your API object using api.new_batch().
2. Add calls to the batch by passing the batch instance to the batch parameter of an API method (e.g., campaign.api_delete(batch=my_api_batch)).
3. Execute all queued calls using my_api_batch.execute().

Note: Batching improves network performance but does not bypass rate limits; each call in a batch counts individually toward your rate limit.

my_api_batch = api.new_batch()

# Add calls to the batch instead of executing immediately
campaign.api_delete(batch=my_api_batch)

# Send the request
my_api_batch.execute()

This example demonstrates how to update specific products in a Facebook catalog by changing their price or marking them as out of stock. It is designed for users implementing Dynamic Product Ads (DPA) to keep their catalog synchronized with real-time changes like price fluctuations or stock availability.

The workflow consists of three components:

1. An XML product feed containing product data.
2. A script (stock_update.py) that reads the feed and selects products for update (e.g., randomly choosing products to change price).
3. A script (dpa_update.py) that uses the Ads API to apply those updates to the actual product catalog.

Pre-requisites

• A Facebook Business Manager account.
• A product catalog already created and populated based on an XML feed.
• Standard Facebook Python Ads SDK credentials (Access Token, etc.).

To execute the Dynamic Products Update demonstration, follow these steps:

1. Prepare the Feed: Ensure your product feed has been created and the products are loaded into your catalog.
2. Configure the Update Script: Open dpa_update.py and update the catalog_id variable with your actual Facebook Catalog ID.
3. Execute the Pipeline: Run the following command in your terminal to select three products from the XML feed and pipe the results into the update script:

   python stock_update.py feed-dpa.xml 3 | python dpa_update.py

4. Verify: Check the updated prices directly in your Facebook catalog to confirm the changes were applied.

The easiest way to install the SDK is using pip. For Python 3 environments, ensure you use pip3 and python3.

pip install facebook_business

Unit tests can be run without an access token or network access using the following command:

python -m facebook_business.test.unit

You can also use tox to run tests across multiple Python versions:

tox --skip-missing-interpreters

If you require the latest version from GitHub or a specific release tarball, you can install it manually using setup.py after downloading and unzipping the package.

python setup.py install

To use the SDK, you must initialize the FacebookAdsApi with your App ID, App Secret, and an Access Token. This sets the default API configuration for subsequent calls.

import sys
from facebook_business.api import FacebookAdsApi
from facebook_business.adobjects.adaccount import AdAccount

my_app_id = 'your-app-id'
my_app_secret = 'your-appsecret'
my_access_token = 'your-page-access-token'

# Initialize the API
FacebookAdsApi.init(my_app_id, my_app_secret, my_access_token)

# Use an object (e.g., AdAccount)
my_account = AdAccount('act_<your-adaccount-id>')
campaigns = my_account.get_campaigns()
print(campaigns)

To determine if an issue is with the SDK or the Meta API, you can enable debug mode in FacebookAdsApi.init. This will print the raw cURL request generated by the SDK to the console, allowing you to test the request manually.

from facebook_business.adobjects.page import Page
from facebook_business.api import FacebookAdsApi

FacebookAdsApi.init(access_token=access_token, debug=True)
page = Page(page_id).api_get(fields=fields,params=params)