News for Developers

Back to News

Getting Started with Tiered Ads API Access

Related News

MPA

September 12 2017

Simplifying Ad Creation

December 18 2014

Ads API V2.2 Schedule

December 16 2014

We recently announced the first official version of our now tiered Ads API and the release of versions 2.2.0 of our PHP Ads API SDK and Python Ads API SDK. I want to quickly go over getting started with our SDKs and some of the new features that come in version 2.2.0 to help you get started.

Why use an SDK?

Working with our official SDKs provide value in a multitude of ways.

  1. You can focus on building your product, not worry about a platform to interface with our Ads API.
  2. Less maintenance work when managing new versions of the API and breaking changes.
  3. Reference implementation that includes best practices for making calls for editing or fetching objects in high volume.

Installation

You can easily install our SDKs using composer for the PHP Ads API SDK and pip for the Python Ads API SDK.

composer.json
====
{
"require": {
"facebook/php-ads-sdk": "2.2.*"
}
}

$ php composer.phar install --no-dev
$ pip install facebookads

Bootstrapping

New in both versions of the SDK is the ability to quickly authenticate your app in a single line of code. You'll need an access token which can be easily obtained from the Graph API Explorer if the app is already set up.

The access token from the Graph API Explorer is a short-lived access token and is fine for playing with the SDK. Our long-lived tokens, however, last much longer and are recommended for development. You can read more about

long-lived tokens here

.

use FacebookAds\Api;

Api::init($app_id, $app_secret, $access_token);
from facebookads.api import FacebookAdsApi

FacebookAdsApi.init(app_id, app_secret, access_token)

Fetching Objects

Both SDKs provide a method to read data from the API. Our SDK is designed in such a way that developers must explicitly decide when to make API calls. We do not automatically fetch data when you instantiate objects.

use FacebookAds\Api;
use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdAccountFields;

Api::init($app_id, $app_secret, $access_token);

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
// Make an API request to read account info.
$account->read(array(
AdAccountFields::NAME,
));

// Print out account name.
echo $account->{AdAccountFields::NAME};
from facebookads.api import FacebookAdsApi
from facebookads.objects import AdAccount

FacebookAdsApi.init(app_id, app_secret, access_token)

account = AdAccount('act_<AD_ACCOUNT_ID>')
# Make an API request to read account info.
account.remote_read(fields=[
AdAccount.Field.name,
])

# Print out account name.
print account[AdAccount.Field.name]

Creating a Campaign Object

Now let's create a campaign for the account.

use FacebookAds\Api;
use FacebookAds\Object\AdCampaign;
use FacebookAds\Object\Fields\AdCampaignFields;

Api::init($app_id, $app_secret, $access_token);

$campaign = new AdCampaign(null, 'act_<AD_ACCOUNT_ID>');
$campaign->{AdCampaignFields::NAME} = 'My New Campaign';
$campaign->{AdCampaignFields::CAMPAIGN_GROUP_STATUS} =
AdCampaign::STATUS_PAUSED;
// Make an API request to create campaign.
$campaign->create();

// Print out the name and status of our new campaign.
echo $campaign->{AdCampaignFields::NAME};
echo $campaign->{AdCampaignFields::CAMPAIGN_GROUP_STATUS};
from facebookads.api import FacebookAdsApi
from facebookads.objects import AdCampaign

FacebookAdsApi.init(app_id, app_secret, access_token)

campaign = AdCampaign(parent_id='act_11124366')
campaign[AdCampaign.Field.name] = 'My New Campaign'
campaign[AdCampaign.Field.status] = AdCampaign.Status.paused
# Make an API request to create campaign.
campaign.remote_create()

# Print out the name and status of our new campaign.
print campaign[AdCampaign.Field.name]
print campaign[AdCampaign.Field.status]

Roadmap

We're working hard to continue making the Ads API developer experience friendlier through making our SDKs more powerful and simpler to use. Here are some of the things that are upcoming.

  • The ability to explicitly define an API version per call.
  • Support for async ad group creation.
  • More reference code and documentation.

Further Reading

Both SDKs have extensive READMEs on their respective GitHub pages that go in further detail documenting their capabilities.

If you have any questions or comments, feel free to leave them below.


Related News

September 12 2017

December 18 2014

December 11 2014

December 02 2014

November 06 2014