Simplifying Ad Creation

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:

• Campaign creation
• Campaign edit
• Ad set creation
• Ad set edit

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());
}

from facebookads.objects import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset[AdSet.Field.name] = 'LifeTimeBudgetSet'
adset[AdSet.Field.lifetime_budget] = 10000
adset[AdSet.Field.end_time] = 1380610800
adset[AdSet.Field.bid_type] = AdSet.BidType.cpc
adset[AdSet.Field.bid_info] = {
'CLICKS': 150,
}
adset[AdSet.Field.targeting] = {
'geo_locations': {
'countries': ['US'],
},
}
adset[AdSet.Field.status] = AdSet.Status.active
adset[AdSet.Field.campaign_group_id] = '<AD_CAMPAIGN_GROUP_ID>'
adset[AdSet.Field.execution_options] = ['validate_only']
adset.remote_create()

curl \
-F "name=LifetimeBudgetSet" \
-F "lifetime_budget=100000" \
-F "bid_type=CPC" \
-F "bid_info={'CLICKS':150}" \
-F "targeting={'geo_locations': {'countries': ['US']}}" \
-F "end_time=1380610800" \
-F "campaign_status=ACTIVE" \
-F "campaign_group_id=<AD_CAMPAIGN_ID>" \
-F "execution_options=['validate_only']" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/adcampaigns"

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};

from facebookads.objects import AdCreative

creative = AdCreative('<AD_CREATIVE_ID>')
fields = [AdCreative.Field.thumbnail_url]
params = {
'thumbnail_width': 150,
'thumbnail_height': 120,
}
creative.remote_read(fields=fields, params=params)

print creative[AdCreative.Field.thumbnail_url]

curl -G \
-d "fields=thumbnail_url" \
-d "thumbnail_width=150" \
-d "thumbnail_height=120" \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/adcreatives"