Today we are announcing three new updates to simplify ad creation through the API.
Ability to validate a call
This will help in validating the fields and serve a corrective error message before actually making the final API call to Facebook. The following operations can be validated through this call:
The flag indicates that we will not perform the actual mutation, but we will do the standard normalization and validation as in the real execution.
Documentation for Campaign and Ad set
Example
Creating an ad set with a lifetime budget using validation
use FacebookAds\Objects\AdSet;
$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->name = 'LifetimeBudgetSet';
$adset->lifetime_budget = 100000;
$adset->end_time = 1380610800;
$adset->bid_type = BidTypes::BID_TYPE_CPC;
$adset->bid_info = array(
'CLICKS' => 150,
);
$adset->targeting = array(
'geo_locations' => array(
'countries' => array('US'),
),
);
$adset->campaign_status = AdSet::STATUS_ACTIVE;
$adset->campaign_group_id = '<AD_CAMPAIGN_GROUP_ID>';
try {
$adset->validate();
$adset->create();
} catch(Exception $e) {
var_dump($e->getMessage());
}
More actionable error messages with blame_field_specs
blame_field_specs
is an array, where each element of the array is a blame_field_spec
which indicates a single field from the API spec that is at fault.
Documentation for blame_field_specs
Example
Single field at fault
{ "error":{ "type":"Exception", "message":"The budget for your Ad-Set is too low. It must be at least $1.00 per day.", "code":1487901, "is_transient":false, "error_data":{ "blame_field_specs":[ ["daily_budget"] ] } } }
Indicates that the daily_budget
field of the API spec is at fault and in this case it was too low.
Multiple fields at fault
"blame_field_specs":[ ["targeting_spec", "interested_in"], ["bid_info", "impressions"] ]
Indicates that there is an error related to the interested_in
subfield within the targeting_spec
field of the API spec, and the error is also related to field impressions
within the bid_info
field of the API spec.
Thumbnail API
We now return a thumbnail_url field when querying a creative. It is a read-only field that provides the URL to a thumbnail. You can optionally request dimensions of this thumbnail by providing the thumbnail_width and thumbnail_height parameters. This can help build a library interface where a person can easily select an image for ad creation.
Documentation for Creative
Example
Requesting thumbnail URL and specifying thumbnail dimensions
use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
$creative = new AdCreative('<AD_CREATIVE_ID>');
$fields = array(
AdCreativeFields::THUMBNAIL_URL
);
$params = array(
'thumbnail_width' => 150,
'thumbnail_height' => 120,
);
$creative->read($fields, $params);
echo $creative->{AdCreativeFields::THUMBNAIL_URL};