Marketing API Version

Ad Previews

Preview existing ads and generate previews of ads you want to create. Generated previews are based on your ad creative. For ad preview provide a user access token, not a Page access token. For example, preview 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.10/<CREATIVE_ID>/previews

Or preview using creative spec for a domain ad for an external website:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdPreviewFields;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$account->getGeneratePreviews(array(), array(
  AdPreviewFields::CREATIVE => <CREATIVE_SPEC>,
  AdPreviewFields::AD_FORMAT => '<FORMAT>',
));
from facebookads.adobjects.adaccount import AdAccount

account = AdAccount('act_<AD_ACCOUNT_ID>')
params = {
    'creative': <CREATIVE_SPEC>,
    'ad_format': '<FORMAT>',
}
account.get_generate_previews(params=params)
APINodeList<AdPreview> adPreviews = new AdAccount(act_<AD_ACCOUNT_ID>, context).getGeneratePreviews()
  .setCreative(<CREATIVE_SPEC>)
  .setAdFormat(<FORMAT>)
  .execute();
curl -G \
  -d 'creative=<CREATIVE_SPEC>' \
  -d 'ad_format=<FORMAT>' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/generatepreviews

Generating Previews

There are a few ways to generate a preview, using:

To use an ad ID for an existing ad, use ad's previews.

https://graph.facebook.com/<API_VERSION>/<AD_ID>/previews

To use an existing ad creative's ID, use the ad creative's previews.

https://graph.facebook.com/<API_VERSION>/<AD_CREATIVE_ID>/previews

To use an ad creative spec, use

For Dynamic Ads pass the entire object_story_spec into the /generatepreviews endpoint, and also use product_item_ids described in Dynamic Ads, Preview.

Previews from an ad account are only visible to people who have a role on the ad account. Previews generated using generatepreviews edge are visible to anyone.

https://graph.facebook.com/API_VERSION>/act_<AD_ACCOUNT_ID>/generatepreviews
https://graph.facebook.com/API_VERSION>/generatepreviews

Any of the four endpoints above will return an ad preview object

Examples

Create a preview with page post details:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdPreviewFields;
use FacebookAds\Object\Values\AdPreviewAdFormatValues;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$previews = $account->getGeneratePreviews(array(), array(
  AdPreviewFields::CREATIVE => array(
    AdCreativeFields::OBJECT_ID => <PAGE_ID>,
  ),
  AdPreviewFields::AD_FORMAT => AdPreviewAdFormatValues::DESKTOP_FEED_STANDARD,
  AdPreViewFields::POST => array(
    'link' => '<URL>',
    'message' => 'Post message',
    'picture' => '<IMAGE_URL>',
    'name' => 'Post name',
    'caption' => 'Post caption',
    'description' => 'Post description',
  ),
));
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adpreview import AdPreview

creative = {
    'object_id': page_id,
}

post = {
    'link': '<URL>',
    'message': 'Make the world more open and connected',
    'picture': '<IMAGE_URL>',
    'name': 'Facebook',
    'caption': 'www.facebook.com',
    'description': 'Facebook is a social utility that connects people with '
                   'friends and others who work, study and live around them',
}

account = AdAccount('act_<AD_ACCOUNT_ID>')
params = {
    'ad_format': AdPreview.AdFormat.desktop_feed_standard,
    'creative': creative,
    'post': post,
}
ad_preview = account.get_generate_previews(params=params)
print(ad_preview)
APINodeList<AdPreview> adPreviews = new AdAccount(act_<AD_ACCOUNT_ID>, context).getGeneratePreviews()
  .setCreative(
    new AdCreative()
      .setFieldObjectId(<PAGE_ID>)
  )
  .setAdFormat(AdPreview.EnumAdFormat.VALUE_DESKTOP_FEED_STANDARD)
  .setPost("{\"link\":\"" + <URL> + "\",\"message\":\"Post message\",\"picture\":\"" + <IMAGE_URL> + "\",\"name\":\"Post name\",\"caption\":\"Post caption\",\"description\":\"Post description\"}")
  .execute();
curl -G \
  -d 'creative={"object_id":"<PAGE_ID>"}' \
  -d 'ad_format=DESKTOP_FEED_STANDARD' \
  --data-urlencode 'post={ 
    "link": "<URL>", 
    "message": "Post message", 
    "picture": "<IMAGE_URL>", 
    "name": "Post name", 
    "caption": "Post caption", 
    "description": "Post description" 
  }' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/generatepreviews

Create a preview using object_story_spec:

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdPreviewFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Values\AdPreviewAdFormatValues;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::MESSAGE => 'Message',
  AdCreativeLinkDataFields::NAME => 'Name',
  AdCreativeLinkDataFields::DESCRIPTION => 'Description',
  AdCreativeLinkDataFields::CALL_TO_ACTION => array(
    'type' => AdCreativeCallToActionTypeValues::SIGN_UP,
    'value' => array(
      'link' => '<URL>',
    ),
  ),
));

$story = new AdCreativeObjectStorySpec();
$story->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = new AdCreative();
$creative->setData(array(
  AdCreativeFields::OBJECT_STORY_SPEC => $story,
));

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$account->getGeneratePreviews(array(), array(
  AdPreviewFields::CREATIVE => $creative,
  AdPreviewFields::AD_FORMAT => AdPreviewAdFormatValues::DESKTOP_FEED_STANDARD,
));
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adpreview import AdPreview
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

link_data = AdCreativeLinkData()
link_data.update({
    AdCreativeLinkData.Field.link: url,
    AdCreativeLinkData.Field.message: "Message",
    AdCreativeLinkData.Field.name: "Name",
    AdCreativeLinkData.Field.description: "Description",
    AdCreativeLinkData.Field.call_to_action: {
        "type": "SIGN_UP",
        "value": {
            "link": url,
            "link_caption": "CTA caption",
        },
    },
})

story = AdCreativeObjectStorySpec()
story.update({
    AdCreativeObjectStorySpec.Field.link_data: link_data,
    AdCreativeObjectStorySpec.Field.page_id: '<PAGE_ID>',
})

creative = AdCreative()
creative.update({
    AdCreative.Field.object_story_spec: story,
})

account = AdAccount('act_<AD_ACCOUNT_ID>')
params = {
    'ad_format': AdPreview.AdFormat.desktop_feed_standard,
    'creative': creative.export_data(),
}
ad_preview = account.get_generate_previews(params=params)
print(ad_preview)
APINodeList<AdPreview> adPreviews = new AdAccount(act_<AD_ACCOUNT_ID>, context).getGeneratePreviews()
  .setCreative(
    new AdCreative()
      .setFieldObjectStorySpec(
        new AdCreativeObjectStorySpec()
          .setFieldLinkData(
            new AdCreativeLinkData()
              .setFieldCallToAction(
                new AdCreativeLinkDataCallToAction()
                  .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_SIGN_UP)
                  .setFieldValue(
                    new AdCreativeLinkDataCallToActionValue()
                      .setFieldLink(<URL>)
                      .setFieldLinkCaption("CTA Caption")
                  )
              )
              .setFieldDescription("Description")
              .setFieldLink(<URL>)
              .setFieldMessage("Message")
              .setFieldName("Name")
          )
          .setFieldPageId(<PAGE_ID>)
      )
  )
  .setAdFormat(AdPreview.EnumAdFormat.VALUE_DESKTOP_FEED_STANDARD)
  .execute();
curl -G \
  --data-urlencode 'creative={ 
    "object_story_spec": { 
      "link_data": { 
        "call_to_action": {"type":"SIGN_UP","value":{"link":"<URL>"}}, 
        "description": "Description", 
        "link": "<URL>", 
        "message": "Message", 
        "name": "Name" 
      }, 
      "page_id": "<PAGE_ID>" 
    } 
  }' \
  -d 'ad_format=DESKTOP_FEED_STANDARD' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/generatepreviews

Create an multi-product ad preview using object_story_id. To get object_story_id, first create a Multi-Product Ad.

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Fields\AdPreviewFields;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Values\AdPreviewAdFormatValues;

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$account->getGeneratePreviews(array(), array(
  AdPreviewFields::CREATIVE => array(
    AdCreativeFields::OBJECT_STORY_ID => <POST_ID>,
  ),
  AdPreviewFields::AD_FORMAT => AdPreviewAdFormatValues::DESKTOP_FEED_STANDARD,
));
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adpreview import AdPreview
from facebookads.adobjects.adcreative import AdCreative

account = AdAccount('act_<AD_ACCOUNT_ID>')
params = {
    'creative': {
        AdCreative.Field.object_story_id: '<POST_ID>',
    },
    'ad_format': AdPreview.AdFormat.desktop_feed_standard,
}
account.get_generate_previews(params=params)
APINodeList<AdPreview> adPreviews = new AdAccount(act_<AD_ACCOUNT_ID>, context).getGeneratePreviews()
  .setCreative(
    new AdCreative()
      .setFieldObjectStoryId(<OBJECT_STORY_ID>)
  )
  .setAdFormat(AdPreview.EnumAdFormat.VALUE_DESKTOP_FEED_STANDARD)
  .execute();
curl -G \
  -d 'creative={"object_story_id":"<POST_ID>"}' \
  -d 'ad_format=DESKTOP_FEED_STANDARD' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/generatepreviews

Create an app ad preview using object_story_spec. This is the only way to generate a preview for an app ad.

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdPreviewFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Values\AdPreviewAdFormatValues;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::LINK => '<URL>',
  AdCreativeLinkDataFields::PICTURE => '<IMAGE_URL>',
  AdCreativeLinkDataFields::MESSAGE => 'Message',
  AdCreativeLinkDataFields::NAME => 'Name',
  AdCreativeLinkDataFields::DESCRIPTION => 'Description',
  AdCreativeLinkDataFields::CALL_TO_ACTION => array(
    'type' => AdCreativeCallToActionTypeValues::USE_APP,
    'value' => array(
      'link' => '<URL>',
    ),
  ),
));

$story = new AdCreativeObjectStorySpec();
$story->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = new AdCreative();
$creative->setData(array(
  AdCreativeFields::OBJECT_STORY_SPEC => $story,
));

$account = new AdAccount('act_<AD_ACCOUNT_ID>');
$account->getGeneratePreviews(array(), array(
  AdPreviewFields::CREATIVE => $creative,
  AdPreviewFields::AD_FORMAT => AdPreviewAdFormatValues::MOBILE_FEED_STANDARD,
));
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adpreview import AdPreview
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

link_data = AdCreativeLinkData()
link_data.update({
    AdCreativeLinkData.Field.link: url,
    AdCreativeLinkData.Field.message: "Message",
    AdCreativeLinkData.Field.name: "Name",
    AdCreativeLinkData.Field.description: "My description",
    AdCreativeLinkData.Field.call_to_action: {
        "type": "USE_APP",
        "value": {
            "link": url,
            "link_caption": "CTA caption",
        },
    },
})

story = AdCreativeObjectStorySpec()
story.update({
    AdCreativeObjectStorySpec.Field.link_data: link_data,
    AdCreativeObjectStorySpec.Field.page_id: <PAGE_ID>,
})

creative = AdCreative()
creative.update({
    AdCreative.Field.object_story_spec: story,
})

account = AdAccount('act_<AD_ACCOUNT_ID>')
params = {
    'ad_format': AdPreview.AdFormat.desktop_feed_standard,
    'creative': creative.export_data(),
}
ad_preview = account.get_generate_previews(params=params)
print(ad_preview)
APINodeList<AdPreview> adPreviews = new AdAccount(act_<AD_ACCOUNT_ID>, context).getGeneratePreviews()
  .setCreative(
    new AdCreative()
      .setFieldObjectStorySpec(
        new AdCreativeObjectStorySpec()
          .setFieldLinkData(
            new AdCreativeLinkData()
              .setFieldCallToAction(
                new AdCreativeLinkDataCallToAction()
                  .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_USE_APP)
                  .setFieldValue(
                    new AdCreativeLinkDataCallToActionValue()
                      .setFieldLink(<URL>)
                      .setFieldLinkCaption("CTA Caption")
                  )
              )
              .setFieldDescription("Description")
              .setFieldLink(<URL>)
              .setFieldMessage("Message")
              .setFieldName("Name")
              .setFieldPicture(<IMAGE_URL>)
          )
          .setFieldPageId(<PAGE_ID>)
      )
  )
  .setAdFormat(AdPreview.EnumAdFormat.VALUE_MOBILE_FEED_STANDARD)
  .execute();
curl -G \
  --data-urlencode 'creative={ 
    "object_story_spec": { 
      "link_data": { 
        "call_to_action": {"type":"USE_APP","value":{"link":"<URL>"}}, 
        "description": "Description", 
        "link": "<URL>", 
        "message": "Message", 
        "name": "Name", 
        "picture": "<IMAGE_URL>" 
      }, 
      "page_id": "<PAGE_ID>" 
    } 
  }' \
  -d 'ad_format=MOBILE_FEED_STANDARD' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/generatepreviews

You can also pass the locale parameter to set the language for the preview, e.g. locale=en_US. Please find the locale here.