Dynamic Language Optimization

Customize different parts of ad creative such as the image, video, text, and body of an ad to reach speakers of different language. Facebook optimizes your ad to show the right language version to the right people.

This helps you to easily set up an ad in multiple languages and deliver the most relevant language version in your ad to a viewer while retaining a broad targeting for the ad. This enables you to have personalized content based on a viewer's spoken language while maintaining cost-efficient ads.

For general information on this feature, see Ads Help Center, Advertise to a multilingual audience. We support the following ad campaign abjectives:

  • Conversions
  • Mobile App Installs
  • Link Clicks

Get Started

Create an asset_feed_spec

Dynamic language optimization creatives are specified using asset feed specs. An asset feed is a collection of different creative elements, such as image, titles, bodies, and so on. You create an asset_feed_spec at /adcreative.

Parameters

To create an asset_feed_spec, provide an array of assets for each different language. Add a label to tag each asset to identify the language the asset belongs to. Facebook uses the labels in asset_customization_rules to group assets together by language. You should provide at least one asset per asset type. Parameters to provide in asset_feed_spec include:

Property Name Description Type Required

images

Images as url or hash. You should provide images which are in the ad account's image library.

Array of: {"url": "<IMAGE_URL>", "hash": "<IMAGE_HASH>", "url_tags": "<TAG>", "adlabels": [{name: "<LABEL>"}]}

Required for SINGLE_IMAGE ad format. Either url or hash is required

videos

Array of video_ids. Videos should be in the ad account's video library.

Array of: {"video_id": "<VIDEO_ID>","thumbnail_url": "{<THUMBNAIL_URL>}", "url_tags": "{<TAG>}", "adlabels": [{"name": "<LABEL>"}]}

Required for SINGLE_VIDEO ad format.

bodies

Array of bodies containing primary message of ad.

Array of: {"text": "<BODY_TEXT>", "url_tags": "<TAG>", "adlabels": [{"name": "<LABEL>"}]}

Yes, however url_tags are optional.

titles

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

Array of: {"text": "

", "url_tags": "", "adlabels": [{"name": ""}]}

Yes, however url_tags are optional.

descriptions

Array of secondary description text, displayed less prominently than bodies or titles.

Array of: {"text": "", "url_tags": "", "adlabels": [{"name": ""}]}

Yes. Use an empty string with a single space for blank description. url_tags are optional.

link_urls

Array of link URLs.

Array of: {"website_url": "", "adlabels": [{"name": ""}], "deeplink_url": "", "display_url": ""}

Yes. url_tags, display_url and deeplink_url are optional.

call_to_action_types

Array of call-to-action-type values.

List of supported call to actions: ["<CALL_TO_ACTION>"]

Yes.

ad_formats

Array of Facebook ad formats you want to create the ads in. Supported formats are: SINGLE_IMAGE, SINGLE_VIDEO

List of supported ad formats: ["{<AD_FORMAT>}"]

Yes.

asset_customization_rules

Array of asset customization rules.

See table below under Asset Customization Rules

Yes.

Asset Customization Rules

Help define the assets that appear together for viewers who speak a particular language. Each rule has a customization_spec which defines the locales of people who view these assets during ad delivery.

You should provide exactly one default rule. This rule must include the assets that Facebook displays if someone's preferred language does not match any locales specified in the asset feed. This helps prevent under-delivery of your ads.

Property Name Description Type Required

customization_spec

Define the locales where the assets in this rule should deliver

{"locales": [<LOCALE1>, <LOCALE2>]}

Yes. For supported locales, see Available Languages.

image_label

Label attached to one of the image assets in the asset feed.

{"name": "<LABEL>"}

Required for SINGLE_IMAGE ad format.

video_label

Label attached to one of the video assets in the asset feed.

{"name": "<LABEL>"}

Required for SINGLE_VIDEO ad format.

body_label

Label attached to one of the body assets in the asset feed.

{"name": "<LABEL>"}

Yes

title_label

Label attached to one of the title assets in the asset feed.

{"name": "<LABEL>"}

Yes

description_label

Label attached to one of the description assets in the asset feed.

{"name": "<LABEL>"}

Yes

link_url_label

Label attached to one of the link_url assets in the asset feed.

{"name": "<LABEL>"}

Yes

is_default

Boolean flag to identify the default rule.

boolean

Yes. You should set exactly one rule with is_default flag as true.

Available Languages

The locales you provide in customization_spec must be locale IDs supported in ads targeting. See Targeting and Placement, Locales. You can search for specific language using the /search endpoint. Use the q parameter to search for a specific language name. Leave this parameter blank to get the list of all supported languages:

curl -G 
  -d "type=adlocale"
  -d "q=en"
  -d "limit=2"
  -d "access_token=<ACCESS_TOKEN>" 
  https://graph.facebook.com/<API_VERSION>/search

On success you get a list of languages:

{
  "data": [
    {
      "key": 6,
      "name": "English (US)"
    },
    {
      "key": 24,
      "name": "English (UK)"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD",
    }
  }
}

You should use the keys in these search results as locales in your asset customization rules. For more information, see Targeting Search.

Create Ads using Asset Feed Specs

You can create an asset feed using the asset_feed_spec field in POST ad_account_ID/adcreatives:

curl 
  -F 'object_story_spec={
       "page_id": "<PAGE_ID>",
       "instagram_actor_id": "<INSTAGRAM_ACTOR_ID>",
     }'
  -F 'asset_feed_spec={
       "ad_formats": ["SINGLE_IMAGE"],
       "bodies": [
         {
           "text": "Try our delicious guacamole recipe!",
           "adlabels": [{"name": "english"}],
         },
         {
           "text": "Essayez notre délicieuse recette de guacamole!",
           "adlabels": [{"name": "french"}],
         },
       ],
       "titles": [
         {
           "text": "Jaspers Market",
           "adlabels": [{"name": "english"}],
         },
         {
           "text": "Jaspers Market",
           "adlabels": [{"name": "french"}],
         },
       ],
       "descriptions": [
         {
           "text": "The best avocados!",
           "adlabels": [{"name": "english"}],
         },
         {
           "text": "Les meilleurs avocats!",
           "adlabels": [{"name": "french"}],
         },
       ],
       "link_urls": [
         {
           "website_url": "www.jaspersmarket.com/en",
           "adlabels": [{"name": "english"}],
         },
         {
           "website_url": "www.jaspersmarket.com/fr",
           "adlabels": [{"name": "french"}],
         },
       ],
       "images": [
         {
           "hash": "J45p3r5m4RK374VOc4DO2",
         },
       ],
       "call_to_action_types": ["SHOP_NOW"],
       "asset_customization_rules": [
         {
           "customization_spec": {
             "locales": [24],
           },
           "title_label": {"name": "french"},
           "body_label": {"name": "french"},
           "description_label": {"name": "french"},
           "link_url_label": {"name": "french"},
         },
         {
             "is_default": true,
           "customization_spec": {
             "locales": [9, 44]
           },
           "title_label": {"name": "english"},
           "body_label": {"name": "english"},
           "description_label": {"name": "english"},
           "link_url_label": {"name": "english"},
         },
       ]
     }'
  -F 'access_token=<ACCESS_TOKEN>'
https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/adcreatives

On success, you get the ID for the ad creative:

{"id":"238474593777777"}

If your asset_feed_spec does meet the restrictions below, you see an error.

To create an ad with this ad creative ID, call POST act_AD_ACCOUNT_ID/ads. Alternatively, to display different languages in your ad, provide the asset_feed_spec and object_story_spec in the creative parameter for the ad.

To verify the new asset_feed_spec, you call GET on the ad ID or the ad creative ID:

curl -G
-d 'fields=object_story_spec,asset_feed_spec'
-d 'access_token=<ACCESS_TOKEN>'
https://graph.facebook.com/API_VERSION/<CREATIVE_ID>

Restrictions

The following are restrictions and limits on your asset feed.

Ad Formats:

  • Only one ad format per asset_feed_spec
  • For SINGLE_IMAGE format, you must provide at least one image.
  • For SINGLE_VIDEO format, you must provide at least one video

Assets, General:

  • You can provide at most six assets for every asset type except call_to_action_types.
  • You must provide exactly one call_to_action_type asset for all objectives.

Text Assets:

  • You must proivde at least one text asset, such as titles, bodies, descriptions and link_urls, for every language version in the asset feed.
  • All text assets should have the adlabels field.
  • Maximum length is 1024 characters for all text assets.

Image and Video Assets:

  • For recommended image sizes by placement and objective - see the Ads Guide.
  • You can use up to one image or video asset without an adlabel. We use this image or video for all the language versions.
  • If you provide additional videos or images, you must include adlabels and you should provide these labels in your asset customization rule.

Link URL Assets:

  • If you provide url_tags, we append them to the link_url as parameters for each asset in the ad.
  • If you use the APP_INSTALLS objective, your link_url should be the same as the ad set's promoted_object.object_store_url.

Asset Customization Rules:

  • You should provide an asset customization rule for every language variant in asset_feed_spec.
  • You should provide one default rule. This is an asset customization rule with is_default set to true. This acts as a backup rule and enables ads to display even when someone's locale does not match any of the languages in asset_feed_spec.

Supported Placements:

  • facebook_positions: feed
  • instagram_positions: stream
  • audience_network_positions: classic

Available Objectives and Destination Types:

  • LINK_CLICKS - Website only, no apps or Messenger.
  • APP_INSTALLS - Desktop or mobile apps.
  • CONVERSIONS - Website only, no apps or Messenger.

Supported Buying Types: