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 v2.3 calls to v2.4
To upgrade to v2.4, developers should modify their Facebook Marketing APIs endpoint prefix, from https://graph.facebook.com/v2.3
to https://graph.facebook.com/v2.4
. You should have the API endpoint prefix set as a system constant or property, to make future version upgrades easier.
All details of upgrading to v2.4 are self-contained in the Marketing API changelog and links therein.
Upgrading from v2.2 calls to v2.3
To upgrade to v2.3, developers should modify their Facebook Marketing APIs endpoint prefix, from https://graph.facebook.com/v2.2
to https://graph.facebook.com/v2.3
. You should have the API endpoint prefix set as a system constant or property, to make future version upgrades easier.
Deprecation of objective
at ad level
Objectives are to be set only at ad campaign level in v2.3. Before v2.3, you could also set objectives at ad level, if the ad level objective is the same as it of the ad campaign, or if the objective of the ad campaign is NONE
.
One special case is that, if the creative used by the ad is about an app, the ad or the ad campaign must have an *_APP_*
objective. If the ad campaign has an objective of NONE
, before v2.3, you could specify an *_APP_*
objective at the ad level. With v2.3+, you will not have this option. For existing app ad campaigns in a NONE
objective campaign, ads will continue delivering. To add additional ads in this case, you must create a new campaign.
Change of time fields
Before v2.3, you could set the ad set's start_time
and end_time
values without timezone, such as "2015-03-12 23:59:59
", and the timezone of the ad account would be used. With v2.3+, you must specify the timezone when you create or update an ad set with those two fields. For example, you can use either "2015-03-12 23:59:59
-07:00" or "2015-03-12 23:59:59
PDT".
Chunked video upload
Before v2.3, you could only upload ad videos in whole. With 2.3+, you can upload an ad video chunk by chunk. This is the preferred method for all ad video uploads. You need to write a three step script to upload ad videos in this way. You can find more details and examples in our ad videos document.
promoted_object
for offer ads
Before v2.3, for OFFER_CLAIM
campaigns, the promoted_object
of an ad set took offer_id
. With v2.3, you should specify page_id
in promoted_object
during ad set creation instead. You do not need to update existing ad sets to use page_id
.
Pixels and Audiences
With v2.3 creating pixels using the /act_<AD_ACCOUNT_ID>/adspixels
endpoint will require the name
parameter.
For website custom audiences, before v2.3 pixel_id
was an optional paramater when creating website custom audiences using the /act_<AD_ACCOUNT_ID>/customaudiences
endpoint. With v2.3 you will need to specify the pixel_id
parameter to create a website custom audience.
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').
When a version of the Marketing API expires, all Marketing API calls made against that version will fail with an exception.
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:
Facebook can automatically infer the conversion specs for adgroups
Right now, for objectives likeMOBILE_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.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.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 withtarget_spec
, only allowing for one spec per prediction. - The new
target_spec
field returns an object wheretarget_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.
Make sure to check out the changelog for a comprehensive list of breaking changes specific to Marketing API v2.2.
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.
facebook/php-sdk-v4 and psr/log are not required anymore.
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();