April 9, 2014

Ads API

Targeting

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.

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 of https://graph.facebook.com/search?type=adTargetingCategory&q=interests
• Specifying values for interests as a string will be sunset in favor of a JSON object of id 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 and update

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.

See Advanced Demographics and Behaviors for documentation.

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 field	type 32 field
object_id	object_id
body	body
name	name
title	title
link_url	link_url
image_file or image_hash	image_hash
	url_tags

Objectives

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 the validation 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 renamed adgroup_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"
         }