Graph API Version

Ad Creative, Preview

Preview your ad's creative.

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.

Reading

The HTML Snippets for previewing this creative

When using a Page Post whose link points to an app on the Google Play Store e.g. (https://play.google.com/store/apps/details?id=com.my.app) or an app on the Apple App Store eg (https://itunes.apple.com/en/app/myapp/id1234567890) Facebook will override/import the following fields:

  • the name parameter of the Page Post will be overwritten with the name of the app from the Play Store/App Store.

  • the thumbnail icon of the app associated with the Page Post will be imported from the Play Store/App Store.

Only certain combinations of creatives and ad_format are supported:

  • Link ad not connected to a page: RIGHT_COLUMN_STANDARD
  • Page like ad: RIGHT_COLUMN_STANDARD, DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD
  • Event ad: RIGHT_COLUMN_STANDARD
  • Page like ad: RIGHT_COLUMN_STANDARD
  • Page post ad: RIGHT_COLUMN_STANDARD, DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD, INSTAGRAM_STORY
  • Desktop app ad: DESKTOP_FEED_STANDARD
  • Mobile app install: MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD, INSTAGRAM_STORY, MOBILE_BANNER, MOBILE_INTERSTITIAL

Examples

Create an ad preview of an existing ad creative

use FacebookAds\Object\AdCreative;

$creative = new AdCreative(<CREATIVE_ID>);
$creative->getPreviews(array(), array(
  AdPreviewFields::AD_FORMAT => AdPreviewAdFormatValues::DESKTOP_FEED_STANDARD,
));
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adpreview import AdPreview

creative = AdCreative(<CREATIVE_ID>)
params = {
    'ad_format': AdPreview.AdFormat.desktop_feed_standard,
}
ad_preview = creative.get_previews(params=params)
print(ad_preview)
APINodeList<AdPreview> adPreviews = new AdCreative(<CREATIVE_ID>, context).getPreviews()
  .setAdFormat(AdPreview.EnumAdFormat.VALUE_DESKTOP_FEED_STANDARD)
  .execute();
curl -G \
  -d 'ad_format=DESKTOP_FEED_STANDARD' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<CREATIVE_ID>/previews

Example

Graph API Explorer
GET /v5.0/<CREATIVE_ID>/previews?ad_format=DESKTOP_FEED_STANDARD&product_item_ids=%5B%22%3CPRODUCT_ITEM_ID%3E%22%5D HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/<CREATIVE_ID>/previews',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/<CREATIVE_ID>/previews",
    {
        "ad_format": "DESKTOP_FEED_STANDARD",
        "product_item_ids": "[\"<PRODUCT_ITEM_ID>\"]"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("ad_format", "DESKTOP_FEED_STANDARD");
params.putString("product_item_ids", "[\"<PRODUCT_ITEM_ID>\"]");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/<CREATIVE_ID>/previews",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"ad_format": @"DESKTOP_FEED_STANDARD",
  @"product_item_ids": @"[\"<PRODUCT_ITEM_ID>\"]",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/<CREATIVE_ID>/previews"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X GET \
  -d 'ad_format="DESKTOP_FEED_STANDARD"' \
  -d 'product_item_ids=[
       "<PRODUCT_ITEM_ID>"
     ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/<CREATIVE_ID>/previews
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

ParameterDescription
ad_format
enum{AUDIENCE_NETWORK_INSTREAM_VIDEO, AUDIENCE_NETWORK_INSTREAM_VIDEO_MOBILE, AUDIENCE_NETWORK_OUTSTREAM_VIDEO, AUDIENCE_NETWORK_REWARDED_VIDEO, DESKTOP_FEED_STANDARD, FACEBOOK_STORY_MOBILE, INSTAGRAM_EXPLORE_CONTEXTUAL, INSTAGRAM_EXPLORE_IMMERSIVE, INSTAGRAM_STANDARD, INSTAGRAM_STORY, INSTANT_ARTICLE_RECIRCULATION_AD, INSTANT_ARTICLE_STANDARD, INSTREAM_VIDEO_DESKTOP, INSTREAM_VIDEO_MOBILE, MARKETPLACE_MOBILE, MESSENGER_MOBILE_INBOX_MEDIA, MESSENGER_MOBILE_STORY_MEDIA, MOBILE_BANNER, MOBILE_FEED_BASIC, MOBILE_FEED_STANDARD, MOBILE_FULLWIDTH, MOBILE_INTERSTITIAL, MOBILE_MEDIUM_RECTANGLE, MOBILE_NATIVE, RIGHT_COLUMN_STANDARD, SUGGESTED_VIDEO_DESKTOP, SUGGESTED_VIDEO_MOBILE, WATCH_FEED_MOBILE}

Use this to select what placement on Facebook the ad preview should be for. The API returns an iframe, which is only valid for 24 hours.

Required
dynamic_asset_label
string

Provide a label for rendering specific variation of an asset customization ad

dynamic_creative_spec
Object

Dynamic creative spec for dynamic ads.

Supports Emoji
dynamic_customization
Object

For dynamic ads in multiple languages, specify the customization to be applied to the ad

end_date
datetime

Provide an end date for trip.* parameters in the creative

height
int64

Custom height of the resulting iframe, recommended at least 280 x 280 for the large right hand size height.
Note: the parameter affects only the size of the iframe containing the preview object. It has no affect on the actual size of the previewed ad.

place_page_id
Page ID

Place page ID to use when rendering a dynamic local ad preview

post
Object

Specs for a page post. This field is used when the creative field contains only a Page id as object_id in it. Not supported for ad_format = RIGHT_COLUMN_STANDARD

link
URL

Destination URL of the ad

Required
message
UTF-8 string

Post message

Supports Emoji
picture
URL

Image URL

name
UTF-8 encoded string

Post name

caption
UTF-8 encoded string

Post caption

description
UTF-8 encoded string

Post description

call_to_action
Object

Call to action

Supports Emoji
type
enum{BOOK_TRAVEL, CONTACT_US, DONATE, DONATE_NOW, DOWNLOAD, GET_DIRECTIONS, GO_LIVE, INTERESTED, LEARN_MORE, LIKE_PAGE, MESSAGE_PAGE, SAVE, SEND_TIP, SHOP_NOW, SIGN_UP, VIEW_INSTAGRAM_PROFILE, INSTAGRAM_MESSAGE, LOYALTY_LEARN_MORE, GET_MOBILE_APP, INSTALL_MOBILE_APP, USE_MOBILE_APP, INSTALL_APP, USE_APP, PLAY_GAME, WATCH_VIDEO, WATCH_MORE, OPEN_LINK, NO_BUTTON, LISTEN_MUSIC, MOBILE_DOWNLOAD, GET_OFFER, GET_OFFER_VIEW, BUY_NOW, BUY_TICKETS, UPDATE_APP, BET_NOW, ADD_TO_CART, ORDER_NOW, SELL_NOW, GET_SHOWTIMES, LISTEN_NOW, GET_EVENT_TICKETS, SEARCH_MORE, PRE_REGISTER, BOOK_TEST_DRIVE, CHECK_AVAILABILITY, CALL, MISSED_CALL, CALL_NOW, CALL_ME, APPLY_NOW, BUY, GET_QUOTE, SUBSCRIBE, RECORD_NOW, VOTE_NOW, GIVE_FREE_RIDES, REGISTER_NOW, OPEN_MESSENGER_EXT, EVENT_RSVP, CIVIC_ACTION, SEND_INVITES, REQUEST_TIME, SEE_MENU, WHATSAPP_MESSAGE, SEARCH, TRY_IT, TRY_ON, LINK_CARD, DIAL_CODE, FIND_YOUR_GROUPS}

The type of the action. Not all types can be used for all ads. Check Ads Product Guide to see which type can be used for based on the objective of your campaign.

Required
value
Object
Default value: Array

JSON containing the call to action data.

Supports Emoji
link
URL

app_link
string

page
numeric string or integer

link_format
enum {VIDEO_LEAD, VIDEO_LPP, VIDEO_NEKO, VIDEO_NON_LINK, VIDEO_SHOP}

application
numeric string or integer

link_title
string

Supports Emoji
link_description
string

Supports Emoji
link_caption
string

product_link
string

get_movie_showtimes
boolean

sponsorship
Object

link
URL

image
URL

video_annotation
Object

annotations
list<Object>

start_time_in_sec
int64

end_time_in_sec
int64

link
URL

link_title
string

link_description
string

link_caption
string

image_url
URL

header_color
string

logo_url
URL

post_click_cta_title
string

post_click_description_title
string

offer_id
numeric string or integer

offer_view_id
numeric string or integer

advanced_data
Object

offer_id
numeric string or integer

lead_gen_form_id
numeric string or integer

fundraiser_campaign_id
numeric string or integer

event_id
numeric string or integer

event_tour_id
numeric string or integer

app_destination
enum {MESSENGER, MESSENGER_EXTENSIONS, MESSENGER_GAMES, LINK_CARD, MARKETPLACE, WHATSAPP}

app_destination_page_id
numeric string or integer

is_canvas_video_transition_enabled
boolean

whatsapp_number
string

preinput_text
string

customized_message_page_cta_text
string

external_offer_provider_id
numeric string or integer

origins
enum {COMPOSER, CAMERA}

object_store_urls
array<string>

photo_replacement_preview_fbid

product_item_ids
list<string>

A list of Product Item IDs to use when rendering a dynamic ad preview.

start_date
datetime

Provide a start date for trip.* parameters in the creative

width
int64

Custom width of the resulting iframe, recommended at least 280 x 280 for the large right hand size widths.
Note: the parameter affects only the size of the iframe containing the preview object. It has no affect on the actual size of the previewed ad.

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of AdPreview nodes.

paging

For more details about pagination, see the Graph API guide.

Validation Rules

ErrorDescription
100Invalid parameter
80004There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting.

Creating

You can't perform this operation on this endpoint.

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.