Marketing API Version

Validation

Validation on the Marketing API occurs on a variety of objects, and between different objects:

Breaking Change: Event Ads, Link Ads not Associated with Valid Page

We recently announced an initiative to make the Facebook Advertising platform more transparent to Facebook users. Read more about this in the Facebook press release

To support this initiative, we are deprecating deprecating Event Ads and Link Ads that are not connected to a valid page from Marketing API.

This breaking change impacts all supported API versions, including the upcoming Marketing API version v2.11, and v2.10 and v2.9 which are available but will be deprecated. This breaking change will take effect the second week of November 2017.

You will no longer be able to create or edit Event Ads and Link Ads that are not connected to a valid page. Requests will do so return the error: ErrorCode::ADPRO2__AD_MUST_HAVE_PAGE (1885833)

The following ad options used together will fail:

  • Event Ads
  • Objective: EVENT_RESPONSES
  • Creative fields: body, object_id
  • Link Ads
  • Objective: LINK_CLICKS
  • Creative fields: title, body, object_url containing image_file or image_hash

You can still create Event Ads and Link Ads if you provide a valid actor_id in the ad creative's object_story_id or object_story_spec fields

These options used together are valid:

  • Event Ads
  • Objective: EVENT_RESPONSES
  • Creative fields: object_story_id or object_story_spec
  • Link Ads
  • Objective: LINK_CLICKS
  • Creative fields: object_story_id or object_story_spec

The nodes, edges and requests impacted are:

Any pre-existing Event or Link Ads continue to run but you cannnot modify these ad's creatives or create new ads with the invalid options once the change goes in effect.

buying_type and billing_event

buying_type is the way in which the advertiser pays for their delivery, defined on the campaign level. Most of the time we just use AUCTION, but there are a few special cases where we either bill based off of prediction (RESERVED), or use a fixed price means of negotiating the price an advertiser will pay (FIXED_CPM). Campaigns with buying_type require ad sets with a billing_event defined.

Valid billing_events for each buying_type:

AUCTION RESERVED FIXED_CPM

IMPRESSIONS

LINK_CLICKS

APP_INSTALLS

PAGE_LIKES

OFFER_CLAIMS

POST_ENGAGEMENT

VIDEO_VIEWS

Objectives and optimization_goal

optimization_goal defines what the advertiser is optimizing for. Certain campaign objectives support only certain ad set optimization_goals.

Campaign Objective Default optimization_goal Other valid optimization_goal

BRAND_AWARENESS

BRAND_AWARENESS. v2.11 and higher, AD_RECALL_LIFT

REACH. v2.11 and higher, none.

APP_INSTALLS (promoting Canvas app)

APP_INSTALLS

IMPRESSIONS, POST_ENGAGEMENT

APP_INSTALLS (promoting mobile app)

APP_INSTALLS

OFFSITE_CONVERSIONS, LINK_CLICKS, REACH, VALUE, VIDEO_VIEWS

CONVERSIONS

OFFSITE_CONVERSIONS

IMPRESSIONS, POST_ENGAGEMENT, REACH, SOCIAL_IMPRESSIONS, VALUE

EVENT_RESPONSES (promoting event)

EVENT_RESPONSES

IMPRESSIONS, REACH

EVENT_RESPONSES (promoting page post)

EVENT_RESPONSES

IMPRESSIONS, POST_ENGAGEMENT, REACH

LEAD_GENERATION

LEAD_GENERATION

LINK_CLICKS

LINK_CLICKS

LINK_CLICKS

IMPRESSIONS, PAGE_ENGAGEMENT, POST_ENGAGEMENT, REACH. LANDING_PAGE_VIEWS, which is under limited availability.

LINK_CLICKS (promoting Canvas app)

ENGAGED_USERS

APP_INSTALLS, IMPRESSIONS, POST_ENGAGEMENT, REACH

LINK_CLICKS (promoting mobile app)

LINK_CLICKS

IMPRESSIONS, REACH, OFFSITE_CONVERSIONS

MESSAGES

REPLIES

REPLIES (Click-to-Messenger), IMPRESSIONS (Sponsored Messages)

PAGE_LIKES

PAGE_LIKES

IMPRESSIONS, PAGE_ENGAGEMENT, POST_ENGAGEMENT, REACH

POST_ENGAGEMENT

POST_ENGAGEMENT

IMPRESSIONS, PAGE_ENGAGEMENT, REACH, VIDEO_VIEWS, LINK_CLICKS

PRODUCT_CATALOG_SALES

OFFSITE_CONVERSIONS

IMPRESSIONS, POST_ENGAGEMENT, OFFSITE_CONVERSIONS, REACH, LINK_CLICKS

REACH

REACH

IMPRESSIONS

VIDEO_VIEWS

VIDEO_VIEWS

PAGE_ENGAGEMENT, REACH

Optimization Goal and Billing events

For buying_type=AUCTION campaigns, with an optimization_goal set, we have restrictions on what billing_event you can choose for your ad set.

In the restrictions below, we assume you have an objective specified on the campaign level.

optimization_goal Valid ad set billing_event

APP_INSTALLS

IMPRESSIONS, APP_INSTALLS

BRAND_AWARENESS

IMPRESSIONS

ENGAGED_USERS

IMPRESSIONS

EVENT_RESPONSES

IMPRESSIONS

IMPRESSIONS

IMPRESSIONS

LEAD_GENERATION

IMPRESSIONS

LINK_CLICKS

LINK_CLICKS, IMPRESSIONS

OFFER_CLAIMS

IMPRESSIONS, OFFER_CLAIMS

OFFSITE_CONVERSIONS

IMPRESSIONS

PAGE_ENGAGEMENT

IMPRESSIONS

PAGE_LIKES

IMPRESSIONS, PAGE_LIKES

POST_ENGAGEMENT

IMPRESSIONS. As of v2.11 POST_ENGAGEMENT not an option.

REACH

IMPRESSIONS

REPLIES

IMPRESSIONS

SOCIAL_IMPRESSIONS

IMPRESSIONS

VIDEO_VIEWS

IMPRESSIONS

VALUE

IMPRESSIONS

LANDING_PAGE_VIEWS, which is under limited availability

IMPRESSIONS

Objectives and Creatives

If an ad's objective is specified, the ad is validated against the creative. Please refer to the ads guide for a list of creatives supported per objective.

In the API, the objective determines which creatives are valid.

Objective Creative Validation Creative fields

NONE

No restrictions

BRAND_AWARENESS

Cannot use mobile app ads


Page post ads


Cannot use both image and video ad creatives in the same ad set, except for Reach and Frequency ad sets.

APP_INSTALLS (promoting Canvas app)

Canvas app install ad

object_story_id or object_story_spec

APP_INSTALLS (promoting mobile app)

Mobile app install ads

object_story_id or object_story_spec

CONVERSIONS (conversions promoting mobile app)

Mobile app engagement ads

object_story_id or object_story_spec

LINK_CLICKS (promoting Canvas app)

Canvas app engagement ad

object_story_id or object_story_spec

LINK_CLICKS (promoting mobile app)

Mobile app engagement ads

object_story_id or object_story_spec

EVENT_RESPONSES. No longer valid as of November 2017. See Breaking Change.

Event ads

object_id
body. No longer valid as of November 2017. See Breaking Change.

EVENT_RESPONSES

Page post ads

object_story_id or object_story_spec

LEAD_GENERATION

Page post ads

object_story_id or object_story_spec

PAGE_LIKES

Page like ads

object_id
body

PAGE_LIKES

Page post ads

object_story_id or object_story_spec

POST_ENGAGEMENT

Page post ads


Cannot include link ads pointing to an app store

object_story_id or object_story_spec

LINK_CLICKS. No longer valid as of November 2017. See Breaking Change.

Link ads not connected to a page

title
body
object_url
(image_file or image_hash). No longer valid as of November 2017. See Breaking Change.

LINK_CLICKS

Link ads


Photo ads with a link in the message


Cannot include link ads pointing to an app store

object_story_id or object_story_spec

LINK_CLICKS

If you select this as both optimization goal and billing event, you must include call_to_action

call_to_action

CONVERSIONS

Link ads not connected to a page

title
body
object_url
(image_file or image_hash)

CONVERSIONS

Link ads


Photo ads with a link in the message


Cannot include link ads pointing to an app store

object_story_id or object_story_spec

VIDEO_VIEWS

Video ads

object_story_id or object_story_spec

MESSAGES

Carousel, Single Image, Single Video, Slideshow

object_story_spec

Ad Creative Validation

Within the ad creative object, validation occurs on the grouping of fields specified. For instance, the below call will create a valid ad:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::TITLE => 'my title',
  AdCreativeFields::BODY => 'my body',
  AdCreativeFields::OBJECT_URL => 'https://www.link.com',
  AdCreativeFields::LINK_URL => 'https://www.link.com',
  AdCreativeFields::IMAGE_HASH => '<IMAGE_HASH>',
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.title] = 'my title'
creative[AdCreative.Field.body] = 'my body'
creative[AdCreative.Field.object_url] = 'https://www.link.com'
creative[AdCreative.Field.link_url] = 'https://www.link.com'
creative[AdCreative.Field.image_hash] = '<IMAGE_HASH>'

creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setTitle("my title")
  .setBody("my body")
  .setObjectUrl("https://www.link.com")
  .setLinkUrl("https://www.link.com")
  .setImageHash(<IMAGE_HASH>)
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'title=my title' \
  -F 'body=my body' \
  -F 'object_url=https://www.link.com' \
  -F 'link_url=https://www.link.com' \
  -F 'image_hash=<IMAGE_HASH>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adcreatives

However, if the object_url is left out, the creative is now invalid:

curl \
-F 'name=Sample Creative' \
-F 'title=my title' \
-F 'body=my body' \
-F 'link_url=https://www.link.com' \
-F 'image_hash=<IMAGE_HASH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v2.5/act_<AD_ACCOUNT_ID>/adcreatives

It is advised to validate on the

grouping

of fields, not on any one field against another.

Objectives and Tracking Specs

Tracking specs are applied by default based on the objective specified, please see the full list of defaults by objective here.

There are two important scenarios to take into account:

  • Tracking pixels will not be applied by default, and you must specify it explicitly when your objective is CONVERSIONS
  • Mobile app ads will no longer track installs or app events by default.
You must explicitly specify to track installs or app events for mobile app ads otherwise your ad will not track.

To specify to track an install or app event, set the following in your ad:

tracking_specs=[{'action.type':['mobile_app_install'],'application':[{your_app_id}]},{'action.type':['app_custom_event'],'application':[{your_app_id}]}]

Certain objectives of ad campaigns requires the promoted_object to be set in ad sets. The validation around this field is documented here.

Objective and Placement Validation

Certain types ad placement are valid only for specific objectives or creatives. The table below illustrates which placements are compatible with which objectives or creatives. You can pick a combination of those compatible placements. Note that

  • audience_network cannot be selected by itself only.
  • With LEAD_GENERATION, device_platforms: desktop cannot be selected together with publisher_platforms: instagram.
Objective Creative Placement

BRAND_AWARENESS

all

publisher_platforms: facebook, instagram, audience_network, facebook_positions: feed,suggested_video, instant_article, instream_video, instagram_positions:stream, audience_network_positions: classic,instream_video

APP_INSTALLS (promoting Canvas app)

Desktop app ads

device_platforms: desktop

APP_INSTALLS (promoting mobile app)

Photo or video mobile app ads

device_platforms: mobile, publisher_platforms: facebook, feed, instagram, instant_articles, audience_network, facebook_positions: feed, suggested_video, instant articles, audience_network_positions: classic, rewarded_video

CONVERSIONS

Photo or video link ads from a page

all

CONVERSIONS

Link ads not connected to a page

facebook_positions: rightcolumn

CONVERSIONS (promoting mobile app)

Photo or video mobile app ads

device_platforms: mobile

EVENT_RESPONSES

Event ads

facebook_positions: rightcolumn

EVENT_RESPONSES

Page post ads

publisher_platforms: facebook

LEAD_GENERATION

Page post ads

device_platforms: mobile, desktop, publisher_platforms: facebook, instagram, facebook_positions: feed, instagram_positions: stream

LINK_CLICKS

Photo or video link ads from a page

all

LINK_CLICKS

Link ads not connected to a page

facebook_positions: rightcolumn

LINK_CLICKS (promoting Canvas app)

Desktop app ads

device_platforms: desktop

LINK_CLICKS (promoting mobile app)

Photo or video mobile app ads

device_platforms: mobile

PAGE_LIKES

Video creatives

publisher_platforms: facebook

POST_ENGAGEMENT

Page post ads (video or photo)

publisher_platforms: facebook, instagram

POST_ENGAGEMENT

Page post ads (text)

publisher_platforms: facebook

VIDEO_VIEWS

Video ads

publisher_platforms: facebook, instagram, audience_network, instant_articles

REACH

Reach ads

all

PRODUCT_CATALOG_SALES

dynamic ads

all

STORE_VISITS

store visit ads

publisher_platforms: facebook

Objective, Optimization Goal and attribution_spec

Use click-through and view-through attribution windows for ad set to track conversions then use for ads delivery optimization. This is different from the attribution window you use for ads reporting. With attribution_spec, select a combination of click-through or view-through windows of 1 day or 7 days. The combinations you can use depend on your ad set's optimization_goal and campaign's objective.

Recommended Default attribution_spec

You may not have provided attribution_spec when you created ads sets optimized for Value Optimization. This is an optimization available for conversions, app installs, and product catalog sales objectives. In the past, we defaulted to a 1-day click through attribution window.

When we released Value Optimization, you could pass an empty attribution_spec and by default we used a 7-day window. We later supported a default 1-day click through window. These changes in the default value caused unexpected switches in optimization windows. To avoid this confusion, you should always provide a value for attribution_spec.

Objective Optimization Goal Allowed Combination

CONVERSIONS, PRODUCT_CATALOG_SALES

OFFSITE_CONVERSIONS

1-day click


7-day click


1-day click and 1-day view


7-day click and 1-day view

APP_INSTALLS, LINK_CLICKS

OFFSITE_CONVERSIONS

1-day click


7-day click (LINK_CLICKS only)

APP_INSTALLS

APP_INSTALLS

1-day click


1-day click and 1-day view

For all other optimization_goal and objective combinations you can only use 1-day click for attribution_spec.