Marketing API Version

Ad Preview

Preview your ad.

Limitations

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
  • Desktop app ad: DESKTOP_FEED_STANDARD
  • Mobile app install: MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD, MOBILE_BANNER, MOBILE_INTERSTITIAL

If you use Page Post with a link to an app on the Google Play Store or on the Apple App Store, we override and import these 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.

Reading

Preview of the ad

Graph API Explorer
GET /v2.10/{ad-id}/previews HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{ad-id}/previews'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{ad-id}/previews",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ad-id}/previews",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{ad-id}/previews"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

Developers usually request these permissions for this endpoint:

Marketing Apps
Permissions are not usually requested.
Page management Apps
No data
Other Apps
No data

Parameters

NameDescription
ad_format
enum{RIGHT_COLUMN_STANDARD, DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD, MOBILE_FEED_BASIC, MOBILE_INTERSTITIAL, MOBILE_BANNER, MOBILE_MEDIUM_RECTANGLE, MOBILE_FULLWIDTH, MOBILE_NATIVE, INSTAGRAM_STANDARD, AUDIENCE_NETWORK_OUTSTREAM_VIDEO, INSTANT_ARTICLE_STANDARD, INSTREAM_VIDEO_DESKTOP, INSTREAM_VIDEO_MOBILE, MESSENGER_MOBILE_INBOX_MEDIA, SUGGESTED_VIDEO_DESKTOP, SUGGESTED_VIDEO_MOBILE, MARKETPLACE_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_creative_spec
Object

Dynamic creative spec for dynamic ads.

Supports Emoji
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.

locale
string

Locale for the ad preview

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{SHOP_NOW, BOOK_TRAVEL, LEARN_MORE, SIGN_UP, DOWNLOAD, GET_DIRECTIONS, LIKE_PAGE, DONATE_NOW, CONTACT_US, VIEW_INSTAGRAM_PROFILE, MESSAGE_PAGE, SAVE, GO_LIVE, DONATE, SEND_TIP, 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, 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}

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
string
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
leadgen
Object
info_fields
list<Object>
policy_url
URL
fallback_test_url
URL
follow_up_title
string
follow_up_action_url
URL
follow_up_action_text
string
tcpa_compliant
boolean
need_split_flow
boolean
split_flow_use_post
boolean
landing_page_cta
string
offer_id
numeric string or integer
offer_view_id
numeric string or integer
advanced_data
Object
offer_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}
is_canvas_video_transition_enabled
boolean
whatsapp_number
string
preinput_text
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
278Reading advertisements requires an access token with the extended permission ads_read
272This Ads API call requires the user to be admin of the application
275Cannot determine the target object for this request. Currently supported objects include ad account, business account and associated objects.
274The ad account is not enabled for usage in Ads API. Please add it in developers.facebook.com/apps -> select your app -> settings -> advanced -> advertising accounts -> Ads API

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.