Introducing Facebook Graph API v15.0 and Marketing API v15.0

Today, we are releasing Facebook Graph API v15.0 and Marketing API v15.0. As part of this release, we are highlighting changes below that we believe are relevant to parts of our developer community. These changes include announcements, product updates, and notifications on deprecations that we believe are relevant to your application(s)’ integration with our platform.

For a complete list of all changes and their details, please visit our changelog.

General Announcements and Updates

Simplifying Custom Conversion Creation Criteria

To simplify the campaign creation process for advertisers, newly created custom conversions will require at least one associated rule with the release of Graph API v15.0. Custom conversions that don’t require rules should utilize custom event optimization, which allows ad campaigns to be optimized directly on the custom event. We’re actively working to transition our existing custom conversions from a single, all-in-one offering into multiple, value-specific products to better meet the needs and use cases of our advertisers. This change will drive advertisers from custom event based custom conversions to custom event optimization.

Platform Term Updates

We are updating the Platform Terms regarding when we may remove an app’s access to any Platform APIs, permissions, or features that your app has not used or accessed within a certain period of time. As of December 15, 2022, the Platform Terms will require activity within a 28-day period to be deemed active.

If you receive notice that your app has been inactive and you wish to reinstate your app, you can do so by going into your app admin role and reinstating it.

You can view the Platform Terms to see a full preview of these changes here.

Deprecations & Breaking Changes

Introducing Advantage Custom Audience

Beginning September 19, 2022, we will begin rolling out Advantage custom audience. Advantage custom audience uses an advertiser’s custom audience to guide delivery and help find more people who are likely to achieve their expressed optimization goal. This means we will deliver ads beyond their Custom Audience if it’s likely to improve performance. Advantage custom audience is part of our Advantage Targeting product suite, including Advantage detailed targeting and advantage Lookalikes. Our Advantage Targeting products leverage advanced automation and machine learning technology that helps improve advertiser campaign performance with less manual effort.

For advertisers who leverage Custom Audiences, they will be able to select Advantage custom audiences. With Advantage custom audiences, advertisers will continue to create Custom Audience (website, app activity, customer list or engagement) and apply relevant inclusions/exclusions, while benefiting from our advanced automation and machine learning technology which uses your custom audience as a source to guide delivery to reach more users who are likely to achieve your expressed optimization goal.

Advantage custom audiences will be automatically turned on when you create a new campaign that includes a website, mobile or engagement custom audience. You can choose to opt-out of this product by unchecking the “Advantage custom audiences” checkbox within the Custom Audience section of our ad creation tool.

Special Ad Audiences Deprecation

As part of our agreement with the US Department of Housing and Urban Development (HUD), we will be sunsetting Special Ad Audiences, a tool that lets advertisers expand their audiences for ad sets related to housing, employment, and credit. We’re removing the ability to create Special Ad Audiences via Marketing API beginning on September 15, 2022.

For advertisers and partners, the blocking of new Special Ad Audience creation on September 15, 2022 will present a breaking change as with this non-versioning change the prior values are deprecated. In 2019, in addition to eliminating certain targeting options for housing, employment and credit ads, we introduced Special Ad Audiences as an alternative to Lookalike Audiences. But the field of fairness in machine learning is a dynamic and evolving one, and Special Ad Audiences was an early way to address concerns. Now, our focus will move to new approaches to improve fairness, including the method previously announced.

Refer below to the list of impacted endpoints related to this deprecation:

For reading audience:

• endpoint gr:get:AdAccount/customaudiences
• field operation_status

For adset creation:

• endpoint gr:post:AdAccount/adsets
• field subtype

For adset editing:

• endpoint gr:post:AdCampaign
• field subtype

For custom audience creation:

• endpoint gr:post:AdAccount/customaudiences
• field subtype

For custom audience editing:

• endpoint gr:post:CustomAudience

Please refer to the earlier blog post and developer documentation for further details to support code implementation.

Advantage detailed targeting /Advantage lookalike Parity

This project brings parity for Detailed Targeting as a Signal (Advantage detailed targeting) for API users using adsets with Messages/App Installs as objectives (post Ads Manager release). We previously launched Advantage detailed targeting for API to adsets with Conversions as objective and Conversions/Value as optimization goals (VO/OC adsets).

Currently, when advertisers create adsets via API with messages or app installs as an objective, they pass two things as a part of the targeting criteria (L2). They pass a list of detailed targeting inputs (eg: cricket, football, dogs etc) and a flag indicating whether they want to expand beyond these inputs (called as Advantage detailed targeting). If the flag is enabled, then our systems deliver beyond their detailed targeting selections if it is likely to improve performance. If it is disabled, our systems limit delivery to the list of selections advertisers have provided.

Going forward (post-Ads Manager release), when advertisers create new campaigns with messages or mobile app installs as objectives, their detailed targeting inclusions will be used as an input (not a constraint) to guide ad delivery. As such, we are deprecating the DTE flag for these objectives and making targeting expansion a default behavior of the detailed targeting selections. When doing so, we may go beyond their detailed targeting inclusions if it is likely to improve performance. All other targeting selections and exclusions will remain unaffected. This change will not apply to special categories.

How it works:

In the past, advertisers would pass the targeting_optimization flag with a value of expansion_all or none to enable or disable Detailed Targeting Expansion. Given the change in the semantics of how detailed targeting will operate for these adsets, advertisers do not need to pass this flag when creating adsets with messages or app installs as an objective, since it will have no impact on their newly created adsets. All of these newly created adsets will always use detailed targeting inclusions as a signal to our backend systems, which may decide to deliver ads beyond these selections if it means better performance for the advertisers.

Given that the targeting_optimization flag will not have any effect on the newly created adsets, we are planning to deprecate this field for new campaigns with messages and/or app installs as an objective going forward.

• To this effect, if advertisers pass the targeting_optimization flag when creating new MAI/messages adsets or when inquiring the delivery estimates of these newly created adsets, we will throw an error message asking them to not send this parameter any more.
• A new field called targeting_as_signal will be set in the backend during new app installs/messages adset creations. This field is available on GET commands only to help advertisers verify if their adsets go beyond the detailed targeting inclusions.

NOTE: These changes to Detailed Targeting as a signal will only apply to newly created adsets with messages and/or app installs as an objective.

API Endpoints in Scope:

• gr:post:/act_XXXX/ adsets
• gr:get:/<adset_id>/delivery_estimate

Pages Tabs Deprecation

We are announcing that the Pages Custom Tab API features will no longer be available via GraphAPI. As we roll out the new Pages experience, there are some Pages API features that will be deprecated as we move forward. Pages Custom Tab features will not be available on the new Pages experience so we will be deprecating API support for these features. We are sharing these updates now to give developers and their clients enough time to communicate the deprecation of these features from their page(s) and make the necessary changes to their pages. This feature will be fully deprecated by 12/14/2022.

API Version Deprecations:

As part of Facebook’s versioning schedule for Graph API and Marketing API, please note the upcoming deprecations:

Graph API

• November 1, 2022: Graph API v8.0 will be deprecated and removed from the platform
• February 23, 2023: Graph API v9.0 will be deprecated and removed from the platform
• June 8, 2023: Graph API v10.0 will be deprecated and removed from the platform

To avoid disruption to your business, we recommend migrating all calls to the latest API version that launched today.

Facebook Platform SDK

As part of our 2-year deprecation schedule for Platform SDKs, please note the upcoming deprecations and sunsets:

• January 2023: Facebook Platform SDK v8.0 or below will be sunset
• June 2023: Facebook Platform SDK v9.0 or below will be sunset
• October 2023: Facebook Platform SDK v11.0 or below will be sunset