Tuesday, January 28, 2014

Upcoming Facebook API Changes

Here are some upcoming changes in the Roadmap from Facebook.

Ads API Breaking Changes

Due April 9th, 2014 at 10am PST
Please note that the new campaign structure changes are still due March 4, 2014.

Table of Contents

  • Targeting
    • Unified interests
    • Geotargeting
    • Advanced Demographic and Behaviors
  • Creative Data Model
    • Removal of type field
    • Renaming of various fields
    • Sunset sponsored stories
    • Sunset type 4 creation
    • Removal of object_id field for app ads, must specify tracking and conversion specs explicitly
  • Objectives
  • Ad Image cropping
  • Enum int->string changes
  • Sunset disapprove_reason_descriptions
Please note that in the below, deprecation means the field will no longer be supported by may still exist. Sunset means the field will officially be removed and no longer supported.


The overall concept of targeting has been redefined as having four key areas (locations, demographics, interests, behaviors). This organization creates more flexibility and precision in audience creation in terms of the and/or logic between groups.
Example: historically, if you selected "Parents" "Photography" "Photo uploader" within interests, the audience constructed was People who are Parents OR interested in Photography OR people who upload [many] Photos. However, the intended audience was: "Parents, who are interested in photography and upload pictures". Now, the specific audience will be targeted as intended.
During the period allotted for the breaking change, all advertiser accounts managed by PMDs will NOT be added to the new targeting types, unified interests (unless previously added by request), or demographic and behavioral changes. This is to prevent disparity between Facebook UI and PMD tools. Access to the new features will be turned on once the respective PMD has confirmed they have altered their API to support the changes bysubmitting a request.
If you have new ad accounts creating/editing ads in both Facebook interfaces and your tool between now and when the API integration is completed at your end, please submit a request to have the user IDs of the ad accounts restricted.
As you are done integrating the new API specs, let us know so we can add your clients to the updated Facebook targeting offering.

Unified Interests

Interest targeting has been redefined to create a unified definition for what indicates interest in a particular topic. Legacy targeting concepts such as Precise Interests (Keywords, #Topics) and Broad Categories have been unified and as a result have only one targeting segement for each term (no duplicate "Baseball" and "#Baseball"). The result is one, clear definition for each targeting segment.
  • Specifying keywords in targeting will be sunset in favor of interests
  • Use the new interest targeting library to query available values instead
  • Querying https://graph.facebook.com/search?type=adinterestcategory will be sunset in favor ofhttps://graph.facebook.com/search?type=adTargetingCategory&q=interests
  • Specifying values for interests as a string will be sunset in favor of a JSON object ofid and name
  • Max number of interests you can specify in an adgroup will be lowered to 1,000
If you are a member of the PMD News group, please refer to this existing post for more details

Geographic targeting

  • The new Geo-Targeting API adds targeting flexibility and incorporates inclusion/exclusion logic.
  • Select any combination of Country, Region, City or Zip without restrictions.
  • Exclude locations from your targeting parameters.
  • All previous capabilities, such as radius targeting on cities, continue to exist.
  • Geo-targeting logic is now "OR" and not "AND". For example, to target California, the previous logic would have required you to specify "US" as the country and "California" as the state. With the current logic, if you specify "US" as the country and "California" as the state, the targeting will result in the entire "US". To target "California", you now only need to specify "California".
  • With the new API, the keys have changed for regions and zip code targeting.
  • IMPORTANT NOTE: The Targeting Spec for any ad created with the new geo-targeting logic (e.g. via Create Flow or Power Editor) will not be editable via the current targeting API. All other parameters will remain editable.
If you are a member of the PMD News group, please refer to this existing posts: original andupdate

Advanced Demographic and Behaviors

Advanced Demographic targeting options will now be available. Key features include better coverage of workplace, education and job title types as well as expanded Relationship status types. There is also the added functionality of selecting the recency of change of a life event (3 months, 6 months, 1 year).
A new targeting type, Behaviors, has been added. These categories are specific to a user's particular actions or past purchase behavior, past purchase behavior, purchase propensity. This category is made up of some targeting segments previously categorized as Interests.
Facebook will begin alpha testing, in the US, of advanced Demographic and some Behavioral targets in early February. The new UI with these features will not be widely available until we have finished General Availability release in mid/late Q1.
See Advanced Demographics and Behaviors for documentation.
During the month of January, PMDs will only have access to the Advanced Demographics & Behaviors APIs via whitelisted test accounts for the purpose of building and testing. Submit a request to whitelist any test accounts. To ensure parity for advertisers across interfaces, the migration will be only become available in early February when Facebook begins testing, in the US, our new UIs.

Creative Data Model

In an effort to better align our Ads API with our Ads Simplification effort, we're making changes to simplify the creative data model to be more intuitive. The focus of creatives will be on the promoted object and the creative assets instead of the creative type, making them more consistent across promoted object types.
As part of a simplification of the ad creative object, we will be removing the field type and standardizing on field names. We will infer what type of ad you wish to create based on the other fields within the creative spec.
Some notable changes:
  • type will be sunset
  • The auto_update field will be sunset. Existing ads will continue to delivery, but will no longer update after 4/9.
  • See the ad creative documentation for exact mapping field name changes.
  • For type 12 premium ads, we will infer using the locations field. Premium standard ads will not look different than standard ads anymore (previously they were 110x80px vs. 100x72px for standard ads).
  • App ads will no longer require an object_id field, so you must explicitly specify a tracking and conversion spec.
  • Facebook will sunset the creation of sponsored stories
    • Page post and page like ads already automatically have the best social context (likes and comments) added. You may choose to add share social context by specifying social_prefs=['allow_shares'] on the adgroup. Existing page post and page like sponsored stories will continue to deliver so you must support fetching them.
    • Domain and open graph sponsored stories will no longer be allowed to be created. Existing domain and open graph sponsored stories will cease to have delivery after April 9th.
  • Facebook will sunset the creation of type 4 ads. Instead, create a canvas app install ad (type 32).
    • Please note that the image dimensions of a type 4 ad may differ from a type 32 – type 32 ads must be 1200x627. It’s recommended to resize the image if you need to reuse it.
    • image_hash is a required field of type 32 ads, whereas they were optional for type 4
    • Existing type 4 ads will continue running until they are naturally phased out, so you must still support fetching them.
    • You will not be allowed to update fields of an existing type 4 creative
    • Please see below for the mapping of type 4 fields to type 32 fields.
type 4 fieldtype 32 field
image_file or image_hashimage_hash


Adgroups will have an optional objectives field. While this field is optional to specify, editing an ad that already contains this field will fail if the adgroup no longer passes thevalidation requirements.

Ad Image Cropping

Facebook has added the option to specify image crops through the Ads API. Image crops are used to describe the way that an image should be displayed in each aspect ratio of the different ad placements. During rendering, the image will be cropped according to the specifications given and if no specification is provided for a certain aspect ratio, the image will be displayed in the default way.
This is optional but if you choose to specify an image crop, you should provide information for all possible aspect ratios in our platform. For more information, please check the docs.
You should also support passing through image crops for ads created outside of your tool. After the migration, if you do not pass through the image crop value, any image crops will be removed.

Enum int->string changes

This migration changes the response of certain fields from an int value to a string value. This applies to the following fields:
  • campaign_status field of ad campaigns
  • capabilities field of ad accounts
  • subtype field of custom audiences and lookalike audiences
As part of this change, we will also be removing the subtype_name field of custom audiences

Sunset disapprove_reason_descriptions

The field disapproval_reason_descriptions is being renamedadgroup_review_feedback. The format will be changed from an array of string to an object key-value-pair of reason enumeration and descriptive text. The previous response would be :
"disapprove_reason_descriptions": [
            "Descriptive text"
The new response will be :
"adgroup_review_feedback": {
            "REASON_ENUM": "Descriptive text"

No comments:

Post a Comment