July 2, 2014

Ads API

New Campaign Structure

Previously, only client-facing ad interfaces were required to be ready to implement the new campaign structure on March 4, 2014. Now, all API developers will need to implement the new campaign structure by July 2, 2014.

The new campaign structure makes it easier for advertisers of every size to organize, optimize and measure their ads. Up until now, Facebook’s campaign structure consisted of two levels — campaigns and ads. Our new campaign structure consists of three levels: campaigns, ad sets and ads.

Details:

• We have added a third level to our campaign structure that is now called "campaign" in the interface. The campaign level now sits above the ad set level, and each new campaign has one or more ad sets. The new campaigns have run status, reporting and an optional objective setting that allows only ads of the selected objective to be created within the campaign. You are now able to get all the ad report stats at the new campaign level, including reach. The new end point in the ads API for accessing this object is /adcampaign_groups
• What was called a "campaign" in our two-level structure is now called an "ad set." Ad sets have the same features that campaigns had previously, including budgets and schedules. The end point in the ads API for accessing these objects remains /adcampaigns but refer to ad set in our interfaces.
• The ad group end point will not change at this time, and it will continue to refer to ‘ad’ as the first level object in our campaign structure.
• To minimize disruption for our advertisers, we automatically migrated all existing campaigns to the new structure. Existing campaigns have become ad sets, and a new campaign object is created for each of them. That new campaign object, now at level 3, has inherited the original campaign's name, is set to active and its objective was automatically set to "none". The ad set has been automatically renamed depending on the targeting properties of its ads and it has the original campaign's budget, schedule and status settings. The ad set contains the exact same ads as the original campaign.
• You will be required to use our updated API as part of this platform migration.

Development and testing should only be conducted in a test/staging app ID environment, which can be added to the allow list for the new campaign structure APIs by flipping the migration toggle in your test/staging app ID.

When you are ready to migrate, enable the 'New Campaign Structure" migration toggle for your production app. All ad accounts already have the new campaign structure enabled, so there is no action to take on the account level.

Mobile and Desktop App ad format change

As we previously announced Facebook is simplifying its ad offerings and making ad units look consistent. Today, app ads are unique amongst Facebook's ad offerings as they carry no social context (e.g. Mark likes this Page) or have like, comment, or share buttons on the ad unit. We are removing this inconsistency by adding social context and like, comment, or share buttons on app ads. This will offer you consistency amongst all your Facebook ads so you will always know how your ad looks in News Feed.

This consistent experience across News Feed ads has an intent to improve ad effectiveness through social context and ad pricing efficiency through like, comment, share interactions on your ads. Two important takeaways about this which you should know:

• Previous research on how much performance lift social context gives Facebook ads showed that ads with social context have 50% higher recall and can drive 35% better online sales. To receive this benefit, mobile app ads will need to be connected to a Facebook Page exactly like any Page post ads you buy today.
• You will not pay for likes, comments, and shares on your mobile app ads or pay for Page likes that happen from your mobile app ads. You will only pay for clicks to app stores if you're bidding CPC. oCPM and CPA bidding does not charge on a click basis and these bidding types will still optimize for getting you installs. This can lead to ad pricing efficiency as likes, comments, and shares on your mobile app ads are signals of your ad's relevancy to your targeted audience.

API details

Now, instead of creating an app ad using the below fields:

You should create an app ad for either mobile or desktop, install or engagement using a link page post where the link is the desktop app URL, iTunes store URL, or Google Play URL. See details here.

Additionally you must add the following to your adgroup:

• Must specify an objective of either MOBILE_APP_INSTALLS, MOBILE_APP_ENGAGEMENT, CANVAS_APP_INSTALLS, or CANVAS_APP_ENGAGEMENT
• Explicitly specify the tracking or conversion spec with the Facebook app ID
• Desktop destinations must specify a page_type placement

To translate the fields between the post-Creative Data Model API and the page post API, see the field mappings below. Fundamentally, the mobile install and engagement units will now only be differentiated by the call to action and existance of a deep link. If INSTALL_MOBILE_APP is set on the call to action, the page post cannot be associated with an ad or campaign that has objective MOBILE_APP_ENGAGEMENT.

If you have extended the Creative Data Model app ad changes until July 2nd, you must now complete those. Ads that were created pre-Creative Data Model will be automatically migrated to their post-Creative Data Model formats, which are specified in the above table.

All existing ads will continue to be returned using the post-Creative Data Model format specified above. At some point after July 2nd Facebook will automatically migrate these into a page post link format.

By July 2nd or when you finish migrating, there will only be two formats to support, post-Creative Data Model for existing ads, and Page Post Link format for newly created ads.

New Graph API framework conversion

For the following endpoints, OAuthInsufficientScopeException will now be replaced by a GraphMethodException. count, offset, limit will no longer be returned and you must instead use a cursor-based approach to paging. Finally, total_count is only returned when the flag summary=true is set.

• /act_{ad_account_id}/adcampaign_groups
• /act_{ad_account_id}/adcampaigns
• /act_{ad_account_id}/adgroups
• /act_{ad_account_id}/adcreatives
• /act_{ad_account_id}/adimages
• /act_{adaccount_id}/generatepreviews
• /{campaign_id}
• /{campaign_id}/adcampaigns
• /{campaign_id}/adgroups
• /{set_id}
• /{set_id}/adgroups
• /{set_id}/adcreatives
• /{adgroup_id}
• /{adgroup_id}/adcreatives
• /{adgroup_id}/previews
• /{creative_id}
• /{creative_id}/previews

Ad account object

We will be removing the ability to filter adgroups by the adgroup_ids param when fetching using https://graph.facebook.com/act_{ad_account_id}/adgroups

We will be removing the ability to filter adsets by the campaign_ids param when fetching using https://graph.facebook.com/act_{ad_account_id}/adcampaigns

Instead, you should filter using the ids param like so: https://graph.facebook.com/act_{ad_account_id}/?ids=[adgroup_id_1,adgroup_id_2,campaign_id1,campaign_id2]

Ad campaign object

id, account_id output field types will become a numeric string value.

Ad set object

id, account_id, campaign_group_id output field types will become a numeric string value.

Ad object

id, account_id, campaign_group_id, campaign_id output field types will be a numeric string value. creative_ids output field type will be an array of numeric strings.

Ad creative object

All IDs will be a string value, and object_id and actor_id will become numeric string values.

We will be removing the preview_url field of the ad creative. Instead, you should leverage the new ad preview API.

Ad Image

The response data array no longer keys based on the hash

Ad preview API

The field page_type, that is used in ad preview API, is being replaced by a new field named ad_format. Valid values for ad_format are RIGHT_COLUMN_STANDARD, DESKTOP_FEED_STANDARD and MOBILE_FEED_STANDARD.

With the new iframe-based preview API, the preview css is no longer needed. Therefore, if the user is in the graph node migration, the endpoint below will return an error.

https://graph.facebook.com/act_{ad_account_id}/adpreviewscss

Finally, the ad preview iframe will now only be valid for 24 hours.

Right hand side image size change

In the coming months, we'll be rolling out an updated design for ads in the right-hand column on Facebook. The new look will showcase larger images, offering a bigger creative canvas for your marketing and provide consistency with the ads in desktop News Feed. Early tests have shown up to 3X more engagement with this new design, with higher click-through rates and fewer hides than our current right-hand column ads.

To simplify the ads creation process, the new image dimensions for ads in the right column will use the same aspect ratio as ads in desktop News Feed so you only need one image asset to run in either placement. Starting late April, we will be updating our self-serve interfaces to accept larger images that fit in the new design so you will no longer have to upload separate creative assets to run ads in News Feed and in the right column of Facebook. As a result of the new design, people will see fewer ads in the right column. Since fewer ads may lead to increased competition for the right-hand column, we encourage you to carefully monitor your bidding strategy to ensure your ads receive adequate exposure.

We encourage you to update your tools for the new image sizes and continue supporting the brands you work with through this transition. All ads will be rendered in the new design by July and ads with smaller sizes will cease to have delivery soon after. We encourage you to recreate ads with incorrect image sizes in the new sizes.

Please be assured that we will continue to update you as these changes go into effect.

The dimensions are as follows:
Page post photo, Page post link, Offer, Desktop App, and Doman ads:
Image dimensions: 254x133 px
Consistent aspect ratio: 1.91:1

Page post video
Image dimensions: 254x143 px
Consistent aspect ratio: 16:9

Page like ad, Event ad
Image dimensions: 254x94 px
Consistent aspect ratio: 2.7:1

Ad Campaign object changes

Enforce buying_type

We are introducing a new optional 'buying_type' field for ad campaigns (adcampaign_groups). The two options for buying_type are: AUCTION or FIXED_CPM (know as Fixed Price in Power Editor). Making buying types explicit at the API level will allow us to add more buying types in the future, and differentiate between them easily - without the need to infer buying types from ad set properties.

If 'buying_type' is not specified, the default value will be AUCTION. All ad sets must validate against the campaign 'buying_type'. For example: all ad sets within a campaign having 'buying_type' of FIXED_CPM must have a 'daily_imps' or a 'lifetime_imps' setting and the bid type must be set to premium; all ad sets within an AUCTION campaign may NOT have 'daily_imps' or 'lifetime_imps' settings and the bid type must NOT be set to premium. 'Buying_type' can only be set at campaign creation, you cannot edit 'buying_type'.

We have automatically set your buying_type for each of your campaigns based on what we could infer from each of your ad sets. If your campaign contained ad sets with different buying types, we set your campaign's 'buying_type' as mixed. When you enable the Enforce 'buying_type' migration, you will NOT be able to create additional ad sets in a mixed 'buying_type' campaign. You will see an error specifying mixed buying types.

This new 'buying_type' field will also help us make future optimizations to delivery, pricing, and limits.You can access more information through our ad campaign documentation.

Only allow string values for "campaign_status"

In a previous migration we moved campaign_status from an int to a string value, but did not perform the same migration when using campaign_status to filter an API call, e.g.

https://graph.facebook.com/{campaign_id}/?campaign_status=['1']

Now, we will enforce that you must use strings when filtering, e.g.

https://graph.facebook.com/{campaign_id}/?campaign_status=['ACTIVE']

All other uses of campaign_status continue to accept string values only.

Ad Set object changes

Daily budget prorating and budget type limitations for short duration ad sets

For ad sets using daily budgets, we prorate the ad set delivery on the first and last days. The prorating takes into account the remaining time in the day and adjusts the target daily spend pro rata. For example, if the start time of an ad set is noon, then we target spending 50% of the daily budget amount for that day. Note, this only affects ad sets with daily budgets.

To help ensure that ad sets deliver in consistent and expected ways, we are limiting the budget type that ad sets can use when the duration (difference between end_time and start_time) is less than 24 hours. For ad sets with durations less than 24 hours, the ad set must use a lifetime_budget.

After the breaking change, if an ad set is created or edited using daily_budget and the ad set duration is less than 24 hours, then an error message will be returned.

During the period allotted for the breaking change, if an ad set is created or edited using daily_budget and the ad set duration is less than 24 hours, then the target daily spend for the first and last days will be prorated based on the number of scheduled hours in each day. This will result in a target daily spend amount that is less than the daily budget amount since there are fewer than 24 hours in the ad set schedule.

Remove support for include_deleted as a filter param

You will no longer be able to view deleted ad sets by making an HTTP GET call to

https://graph.facebook.com/act_{ad_account_id}/adcampaigns

with the flag include_deleted. Instead, you must make an HTTP GET call and specify the field campaign_status=['DELETED']

Ad Object object changes

Rename ADGROUP_PAUSED to PAUSED

Facebook will be renaming the adgroup_status value ADGROUP_PAUSED TO PAUSED to be consistent with the rest of the object's APIs.

PAUSED will now always refer to the current object, and the {object}_PAUSED status will refer to the paused status of other objects.

Limit on ads in an ad set

We are introducing a new limit to the number of ads you can create in an ad set. The new limit will be 50 non-deleted ads per ad set.

Ad sets with more than 50 non-deleted ads will continue delivering as they were before. After your app is migrated, when you try to create a new ad in an ad set that already has 50 or more non-deleted ads, you will see an error message that you have exceeded your limit and that ad will not be created. The existing ads in that set will not be affected. To create a new ad within that set you will have to delete ads within that ad set, or create a new ad set.

Our delivery system optimizes to serve the best performing ad within an ad set. We suggest that you try multiple creative variations within an ad set so we can use our optimization engine to find the best one. The maximum number of ads per ad set should be correlated with ad set reach. Larger reach can support more creative variations. However, too many variations will produce unhelpful results. 50 is the maximum number of ads supported within an ad set. If you want to test multiple audiences, we suggest that you create different ad sets for each audience.

Remove include_deleted flag

You will no longer be able to view deleted ads by making an HTTP GET call to

https://graph.facebook.com/act_{ad_account_id}/adgroups

with the flag include_deleted. Instead, you must make an HTTP GET call and specify the field adgroup_status=['DELETED']

oCPM and CPA

CPA for Link Click only allowed for page posts and oCPM and CPA for link click conversion spec requires post_id

We've seen under-delivery on offsite link click CPA and oCPM ads due to a flaw in the design of the current object ID based offsite link click conversion spec. When the destination URLs in the ads change or the links in the page post ads are edited, the conversion spec is not updated, which impacts delivery.

To address this problem, we will change the default conversion spec for CPA and oCPM for offsite link click will change from object ID based to post ID based for page post ads, e.g. from {"action.type":"link_click", "object": "http://mydomain.com/mypage”} to {"action.type":"link_click", "post_id": "POST_ID", "post.wall": "PAGE_ID"}.

Enabling the migration will enforce the default spec change. Since the spec requires a POST_ID, only page post ads will be eligible for CPA for link click. Existing domain ads with CPA will continue to have delivery and you can continue to change the status or update the bid and budget.

You may have previously submitted a request to enable this migration early. If so, there is no action necessary and the migration toggle will not show up for you as it's already pre-enabled.

Deprecate page_story, post_story, and app_storyconversion spec

We are deprecating all *_story meta specs because the newer ones, *_engagement contain more actions and should provide a better picture of the engagement produced by the ad. For example, post_engagement includes video plays and photo views on the post while post_story does not.

Only allow one conversion spec for oCPM ads

We are going to enforce that all oCPM ads can only have one conversion spec associated with the ad, e.g. only one goal to optimize on, to ensure the most optimal setup for your ad.

Existing ads with >1 conversion spec will continue to deliver after July 2nd, but upon editing, you must comply by the one conversion spec per ad restriction.

Custom Audiences

When deleting a custom audience with lookalikes, error will be thrown

To maintain the effectiveness of a lookalike cluster, we modify and refresh the underlying model over time. Hence we want to enforce that the source of a lookalike cluster (the original custom audience) be available if a lookalike cluster is to be used. This migration will enforce that a deletion of the custom audience with existing lookalike audiences will throw an error.

To make the process easier, we are also providing an option to delete a custom audience as well as all of its lookalikes in one API call, the flag is called force_delete_lookalikes.

Remove origin_audience_id and origin_audience_name

We are introducing a more unified way to provide information about a lookalike cluster in the new lookalike_spec field returned on a READ. origin_audience_id and origin_audience_name are being deprecated in favor of the origins field in lookalike_spec which will contain the origin ID, name, and type.

Ad previews

Deprecate 'page_type' for ad preview plugin

The field page_type, that is used in ad preview plugin, is being replaced by a new field named ad_format. Valid values for ad_format are RIGHT_COLUMN_STANDARD, DESKTOP_FEED_STANDARD and MOBILE_FEED_STANDARD.

Reachestimate API

Deprecated imp_estimates field in API response

We will be removing the imp_estimates field of the reach estimate API. Instead, use the users field.

Pages API Breaking Changes

Removal of PTAT metric

Migration name: Deprecate PTAT (People Talking About This)

Facebook will be removing the People Talking About This metric (PTAT) from Page Insights.

To better see how people interact with a pages content, the PTAT metrics have been split into separate elements: Page Likes, People Engaged (the number of unique people who have clicked on, liked, commented on, or shared your posts), Page tags and mentions, Page checkins and other interactions on a Page.

We recommend that you use these metrics moving forward to evaluate your Page posting strategy and engagement.

Require message field in offers API

Migration name: Offers Message field will be required after July 2, 2014.

The message field, which was once optional, will now be required when creating any offer.

Mobile Measurement API Breaking Changes

New Campaign Structure

The new campaign structure will be enforced in the Mobile Measurement API. Please see this document for migration steps.

This migration is already enabled and you should be seeing the two new fields, campaign_group_id and campaign_group_name in your API response when the install is attributable to Facebook.

Tracking flag is required

Migration name: Tracking Flags required

The two tracking flags, advertiser_tracking_enabled and application_tracking_enabled will now be a required field for both install and conversion pingbacks.