Marketing API

SDKs

The new Business SDK is replacing the Marketing API SDK. Learn about this SDK and how it can serve your business needs.

The easiest way to develop on Marketing API. The SDKs are open-source, and provide support for authentication, core object models, tests, and stability on top of the HTTP-based API.

Download

Marketing API changes often, get the latest autogenerated SDKs which provide parity with our API.

PHP SDKPython SDKJava SDKRuby SDKNodeJs SDK

Install PHP and Python SDKs

Install two SDKs in your development environment.

  • Requirements: Webserver running PHP 5.x, e.g. Apache/XAMPP/MAMP;
  • Facebook Ads API SDK for PHP / PYTHON to access the Marketing API.
  • Facebook SDK for PHP to login to our app (PHP only)
/* 
  PHP Requirements:
  PHP 5.4 or greater. The SDKs use Composer to   
  manage dependencies.
*/

//Run this in terminal to get the latest Composer:
curl -sS "https://getcomposer.org/installer" | php

/*
  If you encounter issues, see 
  "https://getcomposer.org/download/" to install Composer.
 */

//Next add this to "composer.json":
{
  "require": {
    "facebook/graph-sdk" : "~5.0",
    "facebook/php-ads-sdk": "2.8.*"
  }
}

//Then install it through composer:
php composer.phar install --no-dev

//The SDKs and dependencies are installed under "./vendor".
'''
  Python Requirements:
  Easiest way to install the SDK is using pip.
'''

#If you don't have pip:
easy_install pip

#Clone the git hub repo on your local machine:
git clone https://github.com/facebook/facebook-python-ads-sdk.git


#then execute the following to ensure that you grab all the dependencies:
pip install facebookads

#### Note: 
# There is a dependency installation issue with Python 3.
# If you're running Python 3 and configparser fails to install, 
# manually download the package from github:
# https://github.com/facebook/facebook-python-ads-sdk.git

Access Token via SDKs, PHP only

The shows how to get a user access token using the Facebook SDK for PHP. We do not offer getting a user access token using the Python SDK.

require_once __DIR__ . '/vendor/autoload.php';

use Facebook\Facebook;
use Facebook\Exceptions\FacebookResponseException;
use Facebook\Exceptions\FacebookSDKException;

// Init PHP Sessions
session_start();

$fb = new Facebook([
  'app_id' => '{your-app-id}',
  'app_secret' => '{your-app-secret}',
]);

$helper = $fb->getRedirectLoginHelper();

if (!isset($_SESSION['facebook_access_token'])) {
  $_SESSION['facebook_access_token'] = null;
}

if (!$_SESSION['facebook_access_token']) {
  $helper = $fb->getRedirectLoginHelper();
  try {
    $_SESSION['facebook_access_token'] = (string) $helper->getAccessToken();
  } catch(FacebookResponseException $e) {
    // When Graph returns an error
    echo 'Graph returned an error: ' . $e->getMessage();
    exit;
  } catch(FacebookSDKException $e) {
    // When validation fails or other local issues
    echo 'Facebook SDK returned an error: ' . $e->getMessage();
    exit;
  }
}

if ($_SESSION['facebook_access_token']) {
  echo "You are logged in!";
} else {
  $permissions = ['ads_management'];
  $loginUrl = $helper->getLoginUrl('http://localhost:8888/marketing-api/', $permissions);
  echo '<a href="' . $loginUrl . '">Log in with Facebook</a>';
}

Initialize Marketing API SDK

Once you are logged in, initialize the Marketing API SDK:

// Add to header of your file
use FacebookAds\Api;

// Add after echo "You are logged in "

// Initialize a new Session and instantiate an API object
Api::init(
  '{your-app-id}', // App ID
  '{your-app-secret}',
  $_SESSION['facebook_access_token'] // Your user access token
);
#Add to header of your file
from facebookads.api import FacebookAdsApi
from facebookads import objects

#Initialize a new Session and instantiate an API object:

my_app_id = '{your-app-id}'
my_app_secret = '{your-app-secret}'
my_access_token = '{your-access-token}' // Your user access token
FacebookAdsApi.init(my_app_id, my_app_secret, my_access_token)

Make a simple API test call. Read basic information from Facebook Ads. Import ad objects with simple API test calls. Read basic ad account data with Marketing API."

// Add to header of your file
use FacebookAds\Object\AdUser;

// Add after Api::init()
$me = new AdUser('me');
$my_adaccount = $me->getAdAccounts()->current();
#Add to header of your file
from facebookads.objects import AdUser
 
#Add after FacebookAdsApi.init
me = AdUser(fbid='me')
my_account = me.get_ad_accounts()[0]

Debug the response, for example:

print_r($my_adaccount->getData());
print my_account

On success, you get an array with ad account information:

Array
(
    [account_groups] => 
    [account_id] => 123456789
    [account_status] => 
    [age] => 
    [agency_client_declaration] => ...
)

Install Ruby SDKs

  • Requirements: Ruby 2.0+

Install using command line

gem install facebookads

or add the following line to your Gemfile

gem 'facebookads'

Access Tokens

FacebookAds.configure do |config|
  config.access_token = '{your-access-token}'
  config.app_secret = '{your-app-secret}'
end

Please refer to the README file in the project for detailed usage guide.

Third-party SDKs

These are unofficial, third-party SDKs for other languages and frameworks built by communities of active developers.

Inclusion in this list is not an endorsement or recommendation by Facebook. Inclusion is not intended to imply, directly or indirectly, that these organizations endorse or have any affiliation with Facebook. You should report feedback and bugs to their respective developers.

R
fbRads