Facebook Marketing API Upgrade Guide

This guide helps you upgrade your apps across versions. For a list of the changes in each Marketing API release, please see our Marketing API Changelog.

You may also be interested in reviewing the Platform Changelog for any non-Marketing API (such as Pages API or general Graph API) changes that may affect you. Certain changes are called out below, but it is recommended to review the Platform Changelog for the full list.

Upgrading from unversioned calls to v2.2

Implementing Versions in your Apps

To upgrade to v2.2, developers using a Facebook SDK should download the newest version of that SDK - our SDKs automatically use the newest API version available when that SDK version was released. If using our Ads SDKs, the latest PHP and Python SDKs are calling v2.2. Developers using other SDKs may have to manually add v2.2 to the URLs called when accessing the Graph API.

For example, here's a call to v2.2

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v2.2/me/adaccounts"

This works for all versions, in this general form:

https://graph.facebook.com/<API_VERSION>/{request-path}

where <API_VERSION>/ is the version needed, preceded by 'v' (e.g. 'v2.2').

New Field Expansion format for Making Nested Requests

A new, more compact syntax has been introduced for making nested API requests. The old syntax is still available in v2.1, but apps should switch to using the new format as soon as possible.

API Response Changes

All API endpoints will now always return valid JSON. Many API calls before v2.1 returned plain text true or a raw int like 378293782 as the response. With v2.1+, those calls will now return valid JSON, such as:

  {
    “success”: true
  }

This will affect any API endpoints that previously returned something that was not valid JSON - typically this is mostly only publishing or deleting endpoints.

Consult the reference docs for Marketing API to see if any endpoints that you use have changed response formats.

Bid and Targeting

Begin specifying targeting and bid_type at the ad set level, Facebook will no longer accept these fields at the ad level. Also begin setting bid_info at the ad set level. This field will be required at ad set level, while optional at ad level for greater control.

Stop using Action Spec targeting, which is a beta feature. This will no longer be supported.

More information on this change here.

Addition of Promoted Object at Ad Set level

A new field promoted_object will be required while creating ad sets when the campaign's objectives is WEBSITE_CONVERSIONS, PAGE_LIKES, OFFER_CLAIMS, MOBILE_APP_INSTALLS, CANVAS_APP_INSTALLS, MOBILE_APP_ENGAGEMENT or CANVAS_APP_ENGAGEMENT. It describes the thing an ad set is promoting. See Promoted Object.

Knowing what object an ad set is meant to promote is helpful for a number of reasons:

1. Facebook can automatically infer the conversion specs for adgroups
   Right now, for objectives like MOBILE_APP_INSTALLS you must specify the conversion specs explicitly. Once the application being promoted is specified explicitly within the promoted object, there is no more ambiguity and the conversion specs becomes automatic. See conversion specs documentation for more details.

2. We can prevent the mixing of promoted objects
   The Facebook ads delivery system will try to find the best performing ad within an ad set. As such, it assumes that all of the ads within an ad set are essentially fungible. If they are promoting completely different things, this will often lead to un-desireable results. For a long time, we have encouraged Facebook advertisers NOT to promote multiple mobile applications, or use multiple, different conversion pixels among the ads in a single ad set. Now, this can be automatically checked and enforced. All ads must validate against the promoted object if it set in the ad set during creation.

3. Simplify user interfaces
   For marketing developers who are creating self-serve interfaces, the promoted object will help pre-set information when advertisers are creating new ads. For example, if someone is making a new ad, inside of an existing ad set, if that ad set is promoting a particular page, or application, or conversion pixel, this information can be retrieved from the API and used to pre-set certain aspects of the ad, or limit the choices available. We expect this to lead to simpler, more streamlined interfaces where advertisers do not have to specify this kind of information multiple times.

More information on this change here.

Reach and Frequency

• The target_specs endpoint will be replaced with target_spec, only allowing for one spec per prediction.
• The new target_spec field returns an object where target_specs used to return an array.
• A new field, story_event_type, will be added. This field will be used to specify when an ad set may or may not have video ads and is required when targeting all mobile devices.

More information on this change here.

Custom Audience Targeting

Advertisers will need to specify one or many App IDs when adding, removing, or opt-ing out users from Custom Audiences based only on the Facebook user ID or app-scoped user ID. Specifically, a new field, app_ids, is required when "schema"="UID" and takes an array of app IDs.

use FacebookAds\Object\CustomAudience;
use FacebookAds\Object\Fields\CustomAudienceFields;
use FacebookAds\Object\Values\CustomAudienceTypes;

// Add Facebook IDs of users of certain applications
$audience = new CustomAudience('<AUDIENCE_ID>');
$audience->addUsers(
  array(1234, 5678, 9012), // User ids
  CustomAudienceTypes::ID,
  array(1111,2222)  // App ids
);

// Add Facebook IDs of users of certain applications
curl \
-F 'payload = { \ 
"schema":"UID", \
"data":[1234, 5678, 9012], \
"app_ids":[1111,2222]}' \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/<API_VERSION>/<AUDIENCE_ID>/users"

More information on this change here.

New Graph API framework conversion

Starting with version 2.2 update the endpoints listed in the changelog to respect OAuthInsufficientScopeException instead of GraphMethodException and to begin using a cursor-based approach to paging. You may also now specify a flag summary=true to fetch back the total_count.

Also pay special attention to the /<USER_ID/adaccounts edge which has additional changes.

Upgrading to Facebook AdsAPI PHP SDK v2.2.*

This section is meant only for developers transitioning between the SDK v0.9.* to v2.2.*, if you want to get started using the sdk visit our Github page

Get the latest verson

If you included the SDK into your application through composer:

composer update --no-dev

Otherwise check our Github releasese page to download the latest version.

The new init method

Previous versions of the SDK used to rely on \Facebook\FacebookSession to initialize:

// THIS IS LEGACY CODE: won't work with v2.2.0+

use FacebookAds\Api;
use Facebook\FacebookSession;

// Set the default application information to be used with this session
FacebookSession::setDefaultApplication('<APP_ID>', '<APP_SECRET>');
$session = new FacebookSession('<ACCESS_TOKEN>');
$api = new Api($session);

In v2.2.* the Api object can initiate itself. Be sure to replace the previous code with:

use FacebookAds\Api;

// Initialize a new Session and instantiate an Api object
Api::init('<APP_ID>', '<APP_SECRET>', '<ACCESS_TOKEN>');

// The Api object is now available trough singleton
$api = Api::instance();