Creative Specs
In this document:
Overview
Creative specs are used to define what the creative of an Ad group looks like. Creative Specs are used in Ad Creative object. Creative Specs can also be used to generate previews of what a creative will look like when used in an Ad group.
After you create an ad creative, you should specify the creative_id in the adgroup creation call.
Create
To create an ad creative, make an HTTP POST call to
https://graph.facebook.com/act_{ad_account_id}/adcreatives
and specify type, and accompanying parameters
| Ad Type | Description | Required Parameters | Optional Parameters | Note |
|---|---|---|---|---|
| 1 | Basic ad for an external website. Type 1 is default ad type that is used if no ad type is specified | title bodylink_urlimage_file (or image_hash). |
name related_fan_page |
Our ads can show images of size 100x72 up to 100x80, so keep the size of your image between these values |
| 2 | Social ad for a Facebook Page/Place (including page tab applications). Encourages users to like a place. | object_idbody |
name link_urlimage_file (or image_hash)title |
link_url is used to identify a specific landing tab on the page (e.g. a page tab application) by the page tab's URL. See connection objects for retrieving Page tabs' URLs. app_data parameters may be added to the url to pass data to a tab app. |
| 3 | Social ad for an event RSVP. Encourages users to respond to an event. | object_id body |
name image_file (or image_link)title |
Type 3 objects only |
| 4 | Social ad for a Facebook application (lands on the application's profile page). Encourages users to install a Facebook application. | object_idbody |
namelink_urlimage_file (or image_hash)title |
Type 2 objects only, Note only app link_urls are valid for type 4 ads. These urls may be used to pass parameters to canvas apps |
| 12 | Homepage Standard Ad Unit. For Homepage ads through self serve accounts, please use this type instead of type 1. | title bodylink_urlimage_file (or image_hash). |
name related_fan_page |
For Homepage ads in self serve accounts |
| 25 | Sponsored stories for promoting actions taken by a user as defined by an Action Spec. Please see Action Specs for Sponsored Stories below | action_spec |
url_tagsname |
|
| 27 | Page Ads for a Page post. Enables page owners to boost stories to their page's fans. See note below. | object_idauto_updateOR story_id |
url_tagsname |
Type 1 or 6 objects only When using type 27 Ad Creatives to promote a page post which has been targeted by locale the AdGroup targeting must include the same (or a subset of) locale targeting as the page post. E.g. if the Page Post is targeted at locales 6 (US English) and 24 (UK English), then the Ad Group must be targeted at one or more of the same locales. See this for larger link page post image details. |
| 31 | Sponsored Results to embed ads in the list of typeahead search results. | bodyobject_id |
link_urlurl_tags |
Only appears in desktop search results, not on mobile and not on the "more results" page |
| 32 | Mobile App Install Ads to promote mobile apps in mobile news feed | app_platform_type=3object_id |
image_hash body |
Only appears in mobile news feed. Should be used in conjunction with new targeting spec fields user_device and user_os |
Below is a description of each of the parameters:
| Name | Type | Description |
|---|---|---|
| name | string | The name of the creative in the creative library |
| type | string | The number of the ad type, which identifies the type of Sponsored story or ad |
| object_id | int | The Facebook object ID that is relevant to the ad and ad type. See connection objects) |
| body | string | The body of the ad, not applicable to Sponsored stories |
| image_hash | string | Image ID for an image you can use in creatives and thus in ads. |
| image_url | string | A URL for the image for this creative. |
| creative_id | int | Required in order to use an existing creative from the creative library |
| title | string | Title for a default ad |
| run_status | int | Indicates whether the creative is active (1) or deleted (3) |
| link_url | string | A URL for the ad |
| url_tags | string | A string which will be appended to urls clicked from type 25, 27, and 31 creatives. Note Optional URL Tags are not supported for Open Graph Sponsored Stories in the news feed. |
| preview_url | string | The URL to preview the ad, only for the current session user |
| related_fan_page | string | Provides social context to a type 1 ad. Possible values are:0: Indicates that no social context should be provided.1:Indicates that Facebook should automatically match and include social context from a Facebook page (or Facebook app). Specifying 1 is equivalent to checking the "Show stories about people interacting with this page" checkbox in the Ad Manager web interface. This is the default value.{object ID of a Facebook page or app}: The object ID of a Facebook page (or Facebook app). If Facebook's information shows a match between the object ID and the specified link_url value, Facebook will apply the object's social context to the ad given the validation criteria below. If you specify a page other the one Facebook has detected as being associated with the URL, we will apply no social context to the ad, but the adgroup creation will still succeed. Pages must have a minimum of 10 fans before social context will be applied. |
| follow_redirect | boolean | When adding social context to a type 1 ad, indicates that Facebook should follow any HTTP redirects encountered at the link_url in order to find the Facebook object to apply social context from |
| auto_update | boolean | Boolean true to constantly promote the latest page post and ignore story_id parameter. Boolean false to promote a specific page post by story_id. Required for type 27 ads only. |
| story_id | string | The fbid of a page post to use in a type 25 or type 27 ad. This ID can be retrieved by using the graph API to query the posts of the page. Note: The ID of the post is returned in the following format: <Page_ID>_<Story_ID>. Only the "Story_ID" element should be supplied as the story_id. |
| action_spec | JSON String | A JSON string defining an action performed by a user for use in a type 25 ad. See action spec reference for more details. |
Action Specs for Sponsored Stories
You can create Sponsored Stories using the Action Spec framework with type 25 Ad Creatives.
All legacy Ad Creative Types for Sponsored Stories can be defined using Action Spec. The following table lists such legacy types and their associated Action Spec definitions. However, note that Action Spec framework enables you to create many other Sponsored Stories beyond the legacy types below. To see other examples, go here.
| Legacy Creative type | Description | Equivalent Action Spec |
|---|---|---|
| 8 | Promotes stories published through an app. | {'action.type':'post', 'application':APP_ID} |
| 9 | Promotes stories about a user liking a page/place. | {'action.type':'like', 'page': PAGE_ID} |
| 10 | Promoting stories about a user checking into a place. | {'action.type':'checkin','page':PAGE_ID} |
| 10 | Promoting stories about a user checking into any child place of this page. | {'action.type':'checkin', 'page.parent':PAGE_ID} |
| 16 | Promotes stories about a user using an app | {'action.type':'game.plays', 'application':APP_ID} |
| 17 | Promotes stories about a user liking any post from a page that was published by page's admin. | {'action.type':'like', 'post.author':PAGE_ID,'post.wall':PAGE_ID} |
| 19 | Promotes stories about a user liking a domain. | {'action.type':'like', 'object.domain':DOMAIN_ID} |
| 19 | Promotes stories about a user sharing something from a domain. | {'action.type':'post', 'object.domain':DOMAIN_ID} |
Open Graph sponsored stories for timeline apps
In addition to on Facebook Activity sponsored stories, Custom Open Graph activity, which is generated by a timeline app, can also be used to generate Sponsored Stories. Open Graph sponsored stories are defined in the same way as on Facebook Activity Sponsored Stories, i.e. as type 25 creative type with an action spec to define the activity to boost into a sponsored story.
URL Validation
Our system looks at a combination of the Page's name and the URLs it which are listed within the "Websites" field of the Page to match Pages to URLs. This matching is quite conservative, to protect against advertisers from using the social context from pages not directly associated with the URL they're advertising.
In order to help ensure your ad URL will match your Page, you may want to make adjustments to the URL you have listed on the Page. Ideally the website listed on the page will match the landing URL exactly, but depending on how your campaigns work this may not be possible. The rules below are not the only criteria we use, and the link between a URL and a page is 1:1, so having multiple pages 'linked' with a domain is not possible, but if each page links to a different subdirectory/path the links should be detected correctly.
For example:
If the Page lists the URL "www.mybrand.com",
- Ads pointing to www.mybrand.com will be eligible to receive social context.
- Ads pointing to www.mybrand.com/?=query will also be eligible - our system will omit any query after a ? in the URL.
- Ads pointing to www.mybrand.com/somevalue will not. Our system will not accept subdomains, file paths or directories within the domain listed.
If the Page lists the URL "www.mybrand.com/path",
- Ads pointing to www.mybrand.com/path will be eligible to receive social context.
- Ads pointing to www.mybrand.com/path?=query will also be eligible - our system will omit anything after a ? in the URL.
- Ads pointing to www.mybrand.com/path/more-path will not be eligible.
- Ads pointing to www.mybrand.com/ will not be eligible.
If the name of the Page doesn't match the domain of the ad URL, it's also possible that those ads will not match the URL you've entered even if the listed Website matches; the matching is quite conservative.
Obtaining Objects
Many ad creatives such as Sponsored stories and social ads for Facebook page require object_id of relevant Facebook object or URL of a page tab. You can obtain a list of object IDs using the Graph API with
https://graph.facebook.com/act_{ad_account_id}/connectionobjects
which returns the objects for the session user. Learn more about connection objects here
Obtaining Page Posts
You can use Graph API for obtaining posts of a page (see Page):
To retrieve a list of page's own posts (for type 25 or type 27 ad) call
curl \
-F "access_token=_____" \
"https://graph.facebook.com/<PAGE_ID>/posts?"
with any valid page access_token or user access_token.
The response is an ID of the format: <Page_ID>_<Story_ID>. Only the "Story_ID" element should be supplied as the story_id field in the creative spec.
Obtaining Page Events
You can use Graph API for obtaining events of a page (see Page):
To retrieve a list of page's own events (for type 25 ad) call
curl \
-F "access_token=_____" \
"https://graph.facebook.com/<PAGE_ID>/events"
with any valid access_token or user access_token.
Limits
The following are the limits on the fields in a Creative Spec.
- The maximum amount of characters that can be in an ad’s title : 25 characters
- The maximum amount of characters that can be in an ad’s body : 90 characters
- The maximum amount of characters that can be in a URL : 1024 characters
- The maximum allowable length of an individual word in an ad’s text or title : 20 characters
- The minimum amount of characters that can be in an ad’s title : 1 character
- The minimum amount of characters that can be in an ad’s body :1 character
News Feed Placement
The following creative types cannot be targeted to News Feed or Mobile News Feed placements: 1, 2, 3, 4, 12, 31 - you will receive an error if you attempt to create such ads.
Tracking
For ads that lead to content off Facebook, it may be useful to distinguish whether clicks coming to your Facebook application of website are from an ad or a news feed story. Several ad types support adding query parameter to ads destination URL for purpose of tracking.
- For type 1 ads, you can simply append a query parameter to a website URL when specifying
link_url. - For type 2 ads that land on an
iframepage tab application, you can append a special query parameterapp_datato the page tab URL when specifyinglink_url(see Obtaining Objects for obtaining page tab URLs). You can retriveapp_idfromsigned_requestparameter that Facebook platform appends to the application's tab URL when the tab is loaded (see Signed Request). - For type 4 ads, you can simply append a query parameter to n app URL when specifying
link_url. - For type 25 ads you can use
url_tagsto specify a list of query parameters for the following action spec formats: {'action.type':'post', 'application':APP_ID}, {'action.type':'app_use', 'application':APP_ID}, {'action.type':'post', 'object.domain':DOMAIN_ID}, and {'action.type':'post', 'object':URL}. These query parameters will be appended to the ad's URL, which points to an external website or a Facebook canvas application. (see optional tracking tags) - For type 27 ads, you can use
url_tagsto specify a list of query parameters. These query parameters will be appended to the ad's URL, which points to an external website or a Facebook canvas application. (see optional tracking tags).
Examples
The following example creates a type 1 ad group with a related link_url value corresponding to the related_fan_page. Facebook will provide social context for the ad, based on the related_fan_page, if Facebook matches the related_fan_page to the specified link_url value:
// First, upload the ad image that you will use in your ad creative
curl \
-F "image.jpg=@myimage.jpg" \
-F "access_token=_____" \
"https://graph.facebook.com/act_12345678/adimages"
// Then, create an ad creative by referencing the image hash returned in the previous call
curl \
-F "type=1" \
-F "title=test_ad" \
-F "body=test_ad" \
-F "link_url=http://www.cnn.com" \
-F "related_fan_page=5550296508" \
-F "image_hash=5d5f13d38da1da74977dc4f86fad3a88" \
-F "access_token=_____" \
"https://graph.facebook.com/act_12345678/adcreatives"
// Finally, create your adgroup by referencing the ad creative
curl \
-F "name=my ad" \
-F "campaign_id=6009344813748" \
-F "bid_type=1" \
-F "max_bid=30" \
-F "targeting={'countries':['US']}" \
-F "creative={'creative_id':6010919609548}" \
-F "access_token=_____" \
"https://graph.facebook.com/act_12345678/adgroups"
Creating a type 2 ad creative for a page
curl \
-F "name=sample creative" \
-F "type=2" \
-F "object_id=5550296508" \
-F "body=like my page" \
-F "access_token=___" \
"https://graph.facebook.com/act_12345678/adcreatives"
Creating a type 27 page post ad creative for the most recent post
curl \
-F "name=sample creative" \
-F "type=27" \
-F "object_id=374135362667307" \
-F "auto_update=true" \
-F "access_token=_____" \
"https://graph.facebook.com/act_12345678/adcreatives"
Creating a type 25 sponsored story creative for posts coming from app ID 424123577639674
curl \
-F "name=sample creative" \
-F "type=25" \
-F "action_spec={'action.type':'post', 'application':424123577639674}" \
-F "access_token=_____" \
"https://graph.facebook.com/act_12345678/adcreatives"
Updated on Monday