Asset Feed Spec

Available Options for asset_feed_spec

You can use the following parameters to represent creative assets that display in your Dynamic Creative ad. Facebook explores combinations of these assets across eligible ad formats and optimizes delivery of the best combination and best format for each viewer. See also Reference, Asset Feed Spec.

The API for using multiple link_urls is under limited availability. Please contact your Facebook Representative to access it.

No

Property Name Description Type Required

images

Array of eligible images. Images provided in this array should be included in the ad account's image library

array of list of {"url": "{IMAGE_URL}", "hash": "{IMAGE_HASH}", "url_tags": "{TAG}"}
where either url or hash is required

Required for SINGLE_IMAGE and CAROUSEL_IMAGE format

videos

Array of video_ids. video_ids provided in this array should belong to the ad account

array of list of {"video_id": "{VIDEO_ID}", "thumbnail_url": "{THUMBNAIL_URL}", "url_tags": "{TAG}"}

Required for SINGLE_VIDEO format

bodies

Array of bodies. The primary message or copy of the ad.

array of list of {"text": "{BODY_TEXT}", "url_tags": "{TAG}"}

No

call_to_action_types

Array of call-to-action-type values

array of list of {"{CALL_TO_ACTION}"}. You can provide multiple values up to 5 values.

Required for all objectives except REACH and BRAND AWARENESS

titles

Array of titles. A short headline in the ad, generally shown next to a link, image or video.

array of list of {"text": "{TITLE}", "url_tags": "{TAG}"}

No

descriptions

Array of secondary description text, displayed less prominently than bodies or titles. Generally appears next to a link, image or video. If not specified, Facebook scrapes the link you provide to generate a description just as we do for link ads. Use empty string with single space for blank description if you do not want to use the scraped text.

array of list of {"text": "{DESCRIPTION}", "url_tags": "{TAG}"}

No

link_urls

Array of link URLs

array of list of {"website_url": "{URL}"}

Required. Typically you can provide only one URL. Those with access to the API enabling multiple link_urls can use up to five.

ad_formats

Array of Facebook ad formats we should create the ads in. Supported formats are: SINGLE_IMAGE, CAROUSEL_IMAGE, SINGLE_VIDEO

array of strings ["{AD_FORMAT}"]

Yes

optimization_type

Optimization type used in asset feed. Possible values are ASSET_CUSTOMIZATION, LANGUAGE, PLACEMENT, and REGULAR.

string

asset_feed_spec Restrictions

Ad Formats

  • Three ad_formats are supported: SINGLE_IMAGE, CAROUSEL_IMAGE, and SINGLE_VIDEO.
  • Only one ad_format is allowed in one asset feed.
  • ad_format counts as one asset in an asset feed.

Number of Assets:

  • Maximum of 30 total assets. 10 images + 5 bodies + 5 titles + 5 descriptions + 1 ad_format + 1 link_url + 1 call_to_action_types = 28 assets
  • Total number of images: < 10
  • Total number of videos: < 10. If you use Instagram as your placement, only square videos or landscape videos allowed.
  • Total number of bodies: <5
  • Total number of call-to-actions: < 5
  • Total number of titles: < 5
  • Total number of links: < 1. Those with access to the API which enables multiple link_urls can use up to five. This API is under limited availability. Contact your Facebook representative for access
  • Total number of descriptions: <5.

Image requirements:

  • Recommended image specs: 1.9:1
  • Recommended image size: 1,200 x 628 pixels
  • For CAROUSEL_IMAGE format, you must provide at least 2 images.
  • If you use Instagram as your placement, you should use square images for better performance

Text requirements:

  • Title and description text maximum length of 255 characters.
  • Body text maximum length of 1024 characters.
  • If you do not specify any description, we scrape the link you provide to retrieve a description as we do for standard link ads
  • For CAROUSEL_IMAGE, titles are optional.

url_tags are optional and only available for IMAGES, VIDEOS, BODIES, DESCRIPTIONS, and TITLES. Facebook appends url_tags to the link URL as parameters for each asset in an ad.

deeplink_url is also optional. If you do use deeplinks, you can only provide one deeplink_url per asset_feed_spec.

For example, a valid asset feed combination setup for SINGLE_IMAGE format is:

  • 5 images
  • 3 bodies
  • 3 titles
  • 3 descriptions
  • 1 format: SINGLE_IMAGE
  • 2 links, for those with access to the API enabling multiple link_urls
"link_urls=[{'website_url':'WEBSITE_URL'}, {'website_url':'WEBSITE_URL'}]" 

Use Deep Links

You can use deeplinks in asset feed specs in campaigns with the APP_INSTALLS, CONVERSIONS and LINK_CLICKS objectives. Add deeplink_url in link_urls when you create your asset_feed_spec. You must only specify one deeplink_url in asset_feed_spec.

curl 
-F 'object_story_spec={
       "page_id": "YOUR_PAGE_ID"
       "instagram_actor_id" : "INSTAGRAM_ACTOR_ID",
    }' 
-F "asset_feed_spec={'images': [{'hash':'image_hash'}], 'bodies': [{'text':'Body 1'}, {'text':'Body 2'}], 'titles': [{'text':'Title 1'}, {'text':'Title 2'}], 'descriptions': [{'text':' '}], 'ad_formats': ['SINGLE_IMAGE'], 'link_urls': [{'website_url':'App's object store URL','deeplink_url':'deeplink URL'}]}"
-F 'access_token=<ACCESS_TOKEN>'  
https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/adcreatives