Creative Page Post API

Recently we released a new field in the ad creative object called object_story_spec. This single field has a vast number of benefits for API developers:

• Allowing inline creation of page posts as part of the ad creative API: Previously, you had to create the page post in one API call, and then associate that post with a creative in a subsequent call. Now, you can create both simultaneously.
• Allowing creation of page posts without having to request manage_pages or publish_actions permission: Previously, you had to request both pages permissions to run page post ads - now you'll only need ads_management. However, the user associated with the access token must still have at least an advertiser role on the page.
• Supporting previews of creatives with inline page posts: Previously, you had to create the page post object first to generate the preview, even if you weren't done editing the post or weren't ready to finalize it into an actual object. Now, you can generate the preview without first having to create the post object.
• Introduction of an ad video library: Previously, for all video page posts, you had to upload the video each time you wanted to use it, even if it was the same video in multiple posts. Now, you can store the video within your ad account's video library and only have to upload it once. This is particularly beneficial for videos as you only have to process the video once, instead of each time you use it.
• Adding support for image hashes and video IDs associated with ad accounts when creating page posts: Previously, image hashes and video IDs were not compatible with the page post API (since this was stored in the ad account layer), but using object_story_spec you can now use image hashes and video IDs.

Ad Creative API

Page post photo, link (including links to app stores), video, text, and offer ads are all eligible to be created through the object_story_spec field. Please see the documentation for full specs. object_story_spec takes a page_id, and one of link_data, photo_data, video_data, offer_data, or text_data. In the below example, we'll walk through creating a page post photo ad using object_story_spec:

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

$creative = new AdCreative(null, $account->id);
$creative->setData(array(
AdCreativeFields::OBJECT_STORY_SPEC => array('page_id' => <PAGE_ID>, 'photo_data' => array('url' => <PHOTO_URL>, 'caption' => '<PHOTO_CAPTION>'))
));

$creative->create();

curl \  
-F "name=Photo Page Post Ad Creative" \  
-F "object_story_spec={'page_id':<PAGE_ID>,'photo_data':{'url':'<PHOTO_URL>','caption':'<PHOTO_CAPTION>'}}" \  
-F "access_token=<ADS_ACCESS_TOKEN>" \  
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/adcreatives"

When this call executes, it'll create an unpublished page post behind the scenes and immediately use the post object for the ad creative. Previously, you would have had to create both of these objects in two separate calls, using two separate access tokens, like so:

// COUNTEREXAMPLE
// Create the page post first  
curl \  
-F 'message=Book your trip to Alaska, http://bit.ly/alaska'\  
-F 'source=@alaska.jpg'\
-F 'published=0'\
-F 'access_token=<PAGE_TOKEN>'\
https://graph.facebook.com/<PAGE_ID>/photos

// Then create the ad creative and reference the page post ID
curl \
-F "object_story_id=<PAGE_ID>_<POST_ID>" \
-F "access_token=<ADS_ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/adcreatives"

By combining these calls together, you save on call volume, don't need to manage page access tokens alongside your ads access tokens, and also won't run into propagation issues where your page post object may not have yet propagated to the datacenter serving your ad creative creation call.

For full details, see ad creative documentation.

Ad Previews API

Previously to create previews of a page post, you had three options:

1. Using the ad group ID
2. Using the ad creative ID
3. Supplying a creative spec (only applicable for link ads)

Of the three, only the last option will allow you to create a preview without having an ad object already but unfortunately is only applicable for link ads. Now, the addition of object_story_spec will allow you to supply a creative spec that is applicable for photo, link, video, text, and offer ads.

Here's an example of how you may use this to generate a preview of a photo page post:

use FacebookAds\Object\Fields\AdPreviewFields;
use FacebookAds\Object\Values\AdFormats;

$account->getAdPreviews(
array(
AdPreviewFields::CREATIVE => array(AdCreativeFields::OBJECT_STORY_SPEC => array('page_id' => <PAGE_ID>, 'photo_data' => array('url' => <PHOTO_URL>, 'caption' => '<PHOTO_CAPTION>'))),
AdPreviewFields::AD_FORMAT => AdFormats::DESKTOP_FEED_STANDARD,
));

curl -G \  
-d "creative={'object_story_spec':{'page_id':<PAGE_ID>,'photo_data':{'url':'<PHOTO_URL>','caption':'<PHOTO_CAPTION>'}}}" \  
-d "ad_format=DESKTOP_FEED_STANDARD" \  
-d "access_token=<ACCESS_TOKEN>" \  
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/generatepreviews"

For full details, see ad previews documentation.

Ad Video Library API

Finally, to facilitate the creation of video ads, we're introducing an ad video library to allow you to upload videos to your ad account which can then be referenced in video ads created through object_story_spec. This API works in a manner similar to the ad images library. Namely, here's how you would upload a video to your ad account's video library:

curl \
-F "source=@/Desktop/test.mov" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph-video.facebook.com/act_<AD_ACCOUNT_ID>/advideos"

The response will be the video's ID. Then, when creating the ad creative, here's how you would specify it in object_story_spec:

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

$creative = new AdCreative(null, $account->id);
$creative->setData(array(
AdCreativeFields::OBJECT_STORY_SPEC => array('page_id' => <PAGE_ID>, 'video_data'=>array('video_id' => <VIDEO_ID>, 'title' => 'Story message', 'description' => 'A description', 'image_url' => '<IMAGE_URL>', 'call_to_action' => 'WATCH_MORE'))
));

$creative->create();

curl \  
-F "name=Video Page Post Ad Creative" \  
-F "object_story_spec={'page_id':page id,'video_data':{'video_id':<VIDEO_ID>, 'title':'Story message', 'description':'A description','image_url':'<IMAGE_URL>', 'call_to_action':'WATCH_MORE'}}" \  
-F "access_token=<ADS_ACCESS_TOKEN>" \  
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/adcreatives"

For full details, see ad video documentation.