December 11 2014
April 30 2019
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:
publish_actionspermission: 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.
object_story_specyou can now use image hashes and video IDs.
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
text_data. In the below example, we'll walk through creating a page post photo ad using
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();
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 'firstname.lastname@example.org'\ -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.
Previously to create previews of a page post, you had three options:
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, ));
For full details, see ad previews documentation.
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
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();
For full details, see ad video documentation.