facebookads provides an interface between your python application and Facebook's Ads API.
Use pip3
and python3
if you use Python 3. Use sudo
if any of these complain about permissions. easy_install pip
if you don't have pip
.
Via pip:
pip install facebookads
Or locally via downloaded package:
python setup.py install
To get started with the sdk you must have a Facebook app registered at https://developers.facebook.com/. In addition, your app must be approved for Ads API usage and have all migrations enabled. Learn more about the Ads API at https://developers.facebook.com/docs/ads-api.
To get started with the examples provided in the examples/ folder, you need:
- an app id
- app secret
- an access token
Note
The access token must be from the app above.
It is expected that an app in production will build its own infrastructure to interact with a user to generate an access token and choose an account to manage. To learn more about access tokens go to https://developers.facebook.com/docs/reference/ads-api/overview/.
Import the sdk:
import facebookads
Assuming you have a user with an access token, set up a FacebookSession
:
from facebookads.session import FacebookSession session = FacebookSession(<app_id>, <app_secret>, <access_token>)
Set up an FacebookAdsApi
instance using this session:
from facebookads.api import FacebookAdsApi api = FacebookAdsApi(session)
If you do not want to specify the api instance when instantiating graph objects, you can set an api instance as the default api instance through which objects will interface:
FacebookAdsApi.set_default_api(api)
The SDK implements a CRUD (create, read, update, delete) design. Objects relevant to exploring the graph are located in the objects module of the facebookads package.
All objects on the graph are instances of AbstractObject
. Some objects can
be directly queried and thus are instances of AbstractCrudObject
(a subclass
of AbstractObject
). Both these abstract classes are located in
facebookads.objects.
AbstractCrudObject can have all or some of the following methods:
- remote_create
- remote_read
- remote_update
- remote_delete
For example, AdCampaign has all these methods but AdAccount does not. Read the Ads API documentation for more information about how different ad objects are used.
Let's get all the ad accounts for the user with the given access token. Notice
we will not specify a keyword argument api=api
when instantiating the
AdUser
object because we've above set the default api. Also notice that
we wrap the return value of get_ad_accounts
with list()
because
get_ad_accounts
returns an EdgeIterator
and we want to get the full
list right away instead of having the iterator lazily loading accounts as we
iterate through it:
import facebookads.objects as objects me = objects.AdUser(fbid='me') my_accounts = list(me.get_ad_accounts())
We shall work with the following account, assuming the user chose the first one. You probably also only have one ad account:
my_account = my_accounts[0]
Note
If you want to work with an account for which you already know its
id, you can directly instantiate an AdAccount object by giving it an fbid
parameter (e.g. fbid='act_xyz'
). The user must have permission to use the
account, of course.
Let's create an AdCampaign. We can go to https://developers.facebook.com/docs/reference/ads-api/adcampaign to make sure we are following the creation requirements:
campaign = my_account.child(objects.AdCampaign) campaign[objects.AdCampaign.Field.name] = "FooBar Campain" campaign[objects.AdCampaign.Field.status] = objects.AdCampaign.Status.paused campaign.remote_create()
We can also read properties of an object from the api assuming that the object is already created and has a node path. Accessing properties of an object is simple since AbstractObjects implement the collections.MutableMapping. You can access them just like accessing a key of a dictionary:
my_account.remote_read(fields=[objects.AdAccount.Field.amount_spent]) print("Amount spent by account %s: %s" % ( my_account.get_id(), my_account[objects.AdAccount.Field.amount_spent], )
To update an object, we can modify its properties and then call the
remote_update
method to sync the object with the server:
# Correcting typo "Campain" -> "Campaign" campaign[objects.AdCampaign.Field.name] = "FooBar Campaign" campaign.remote_update()
We decide we don't want this campaign anymore:
campaign.remote_delete()
All CRUD calls support a params
keyword argument which takes a dictionary
mapping paramater names to values in case advanced modification is required.
remote_create
and remote_update
support a files
keyword argument
which takes a dictionary mapping file reference names to binary opened file
objects.
remote_read
supports a fields
keyworkd argument which is a convenient
way of specifying the 'fields' parameter. fields
takes a list of fields
which should be read during the call.
You can explore the edge of an object by instantiating an EdgeIterator
(
available in facebookads.objects). In addition, there are also methods you may
find in the class and method documentation which are a convenient way to
get these iterators. For example, above we iterated over all the accounts
associated with a user by calling the get_ad_accounts
method on the
AdUser
.
It is efficient to group together large numbers of calls into one http request.
The SDK makes this process simple. You can group together calls into an instance
of FacebookAdsApiBatch
(available in facebookads.api). To easily get one
for your api instance:
my_api_batch = api.new_batch()
Calls can be added to the batch instead of being executed immediately:
campaign.remote_delete(batch=my_api_batch)
Once you're finished adding calls to the batch, you can send off the request:
my_api_batch.execute()
Please follow batch call guidelines in the Ads API documentation. There are optimal numbers of calls per batch. In addition, you may need to watch out that for rate limiting as a batch call simply improves network performance and each call does count individually towards rate limiting.
See facebookads.exceptions
for a list of exceptions which may be thrown by
the SDK.
You may run the tests on your own account by executing the following, making sure to fill in your own app and account information:
python -m facebookads.test.tests app_id app_secret access_token account_id
Or:
python3 -m facebookads.test.tests app_id app_secret access_token account_id
Examples of usage are located in the examples/ folder.