Dynamically Optimizing Language

This API is available on a limited basis as a beta release.

This is a new beta feature where you can try different texts in multiple languages in one ad and we optimize the text the to achieve the best results. Provide multiple languages in an ad's headline or body text. For more general information, see Ads Help Center, Advertise to a multilingual audience.

  • Reach a multilingual population by using creatives in different languages and deliver the right language to the right people.
  • Improve the return on ads spending by automating the work of finding the best creative across a multilingual population.

The high-level steps are as follows:

Restrictions

You can use this feature only with ads using the APP_INSTALLS objective. Other limitations include:

Asset feeds:

  • Maximum number of assets per type is six
  • Titles, descriptions, bodies text maximum length is 255.
  • No two assets of the same type can have the same language
  • At least two types assets should be present per group defined by a language
  • At least one group should be defined using a language. This is distinct from default_language.
  • Only languages from the list of available languages
  • Body assets must have values for all languages.

Images:

Create Asset Feed

An asset feed is a collection of different creative elements, such as image, titles, bodies, and so on. Create an asset feed for language optimization at this endpoint:

POST https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adlanguage_as

This example creates an asset feed with text fields grouped together by language, sharing the same link_url:

curl 
-F "image={'hash':'aaaaaaaa'}" 
-F "bodies=[{'text':'Begin Your Adventure', 'language': 'en_XX'}, {'text':'Commencez votre aventure', 'language': 'fr_XX'}]" 
-F "titles=[{'text':'Pokemon', 'language': 'en_XX'}, {'text':'Pokémon', 'language': 'fr_XX'}]" 
-F "descriptions=[{'text':'Play now', 'language': 'en_XX'}]" 
-F "link_urls=[{'website_url':'www.instagram.com', 'language': 'en_XX'}]" 
-F "default_language=en_XX" 
-F "access_token=ACCESS_TOKEN" 
https://graph.facebook.com/API_VERSION/act_ADACCOUNT_ID/adlanguage_assets

On success, you get a new Asset Feed ID:

  {"asset_feed_id":"ID"}

If this fails, you get an error. This means the asset feed does not conform to restrictions listed above.

To verify you can use your Asset Feed, read it:

curl -G 
-d "access_token=ACCESS_TOKEN" 
-d 'fields=images,titles,bodies,descriptions,ad_formats' 
https://graph.facebook.com/API_VERSION/ASSET_FEED_ID

The assets in an asset feed are grouped together based on a language field. These grouped assets always appear together in an ad impression. All assets, except call_to_action_type, should have the language field.

default_language is the default language we display in your ad, if there are no other language versions available for that asset type. For example, you can have body assets in six languages, but only one title asset that has the default set. We use this title with all the other language versions of the body in your ad.

You should provide at least one asset per asset type with language set to default_language.

Property NameDescriptionTypeRequired

images

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

array with list of {"url": "IMAGE_URL", "hash": "IMAGE_HASH", "url_tags": "<TAG>", "language_label": "<LABEL>"} where either url or hash required

Yes

bodies

Array of bodies containing primary message of ad.

array of list of {"text": "<BODY_TEXT>", "url_tags": "<TAG>", "language_label": "<LABEL>"}

Yes

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>", "language_label": "<LABEL>"}

Yes

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 as we do for link ads.

array of list of {"text": "<DESCRIPTION>", "url_tags": "<TAG>", "language_label": "<LABEL>"}

Yes. Use empty string with single space for blank description.

link_urls

Array of link URLs

array of list of {"website_url": "<URL>", "language_label": "<LABEL>"}

Required for LINK_CLICKS

call_to_action_type

Call-to-action-type

CALL_TO_ACTION

No

default_language

Specifies the default language

Required, string en_XX

Yes

Available Languages

Find languages available at the search endpoint. You can search for specific language names using the q parameter. Leave this parameter blank to get the list of all supported languages:

curl -G 
  -d "type=adassetsupportedlanguages" 
  -d "limit=2" 
  -d "q=en" 
  -d "access_token=ACCESS_TOKEN" 
  https://graph.facebook.com/VERSION/search

On success you will get a list of languages:

  {
  "data": [
    {
      "key": "en_XX",
      "language": "English"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD",
    }
  }
}

The keys from the search result should be used as languages for the assets in the asset feed.

Creating Ads

This example shows creation of a campaign.

curl 
-F "name=Dynamic language optimization - Sample Campaign" 
-F "objective=APP_INSTALLS" 
-F "access_token=ACCESS_TOKEN" 
https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/campaigns

This will give you a campaign ID.

{"id":"23842500259110001"}

Use this campaign ID and then select targeting. We recommend a multilingual audience of at least 2 million in size for best performance.

curl 
-F 'billing_event=EVENT' 
-F 'campaign_id=ID' 
-F 'lifetime_budget=500000' 
-F 'is_autobid=true' 
-F 'name="Dynamic language optimization - Adset"' 
-F 'promoted_object={"page_id":PAGE_ID}' 
-F 'status=PAUSED' 
-F 'optimization_goal=APP_INSTALLS' 
-F 'targeting={
    "publisher_platforms":["facebook"],
    "geo_locations":{"countries":["US"]},
    "age_min":18,
    "age_max":65
   }' \
-F 'end_time=1485618778' 
-F "access_token=ACCESS_TOKEN" 
https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/adsets

This returns a new adset ID:

{"id":"23842500259260001"}

You can create only one ad per ad set that uses a language asset feed. Note these additional restrictions on ad set when you use this feature:

Supported placements:

  • Facebook Feed: Desktop and Mobile. publisher_platform=[“facebook”], facebook_positions=[“feed”, “right_hand_column”]
  • Instagram Feed: instagram_positions=[“stream”]
  • Audience Network: audience_network_positions=[“classic”]

Associate Ad with Asset Feed

Finally, create an ad that uses your asset feed. Use the adset ID and asset feed ID to create your ad with language optimization:

curl 
-F 'adset_id=ADSET_ID' 
-F 'creative={
      "asset_feed_id":ASSET_FEED_ID, 
      "object_story_spec":{"page_id":PAGE_ID}
    }' 
-F 'name="Dynamic language optimization - Ad"' 
-F 'status=ACTIVE' 
-F "access_token=ACCESS_TOKEN" 
https://graph.facebook.com/API_VERSION/act_AD_ACCOUNT_ID/ads

You can view your campaign and ad sets in Ads Manager. Your ad is in Facebook Ad Review. Facebook checks that your ad meets Facebook Advertising Policies before it can run.

Check Review Status

After you create your campaign, ad set, and ad, check your ad review status:

curl -G 
-d 'fields=review_feedback' 
-d "access_token=ACCESS_TOKEN" 
https://graph.facebook.com/API_VERSION/AD_ID

The result includes dynamic creative ad review feedback:

{
  "review_feedback":"[]",
  "id":"AD_ID"
}

An empty array means your ad passed review and will display when your ad set reaches its start date. Otherwise, if one of your creative assets does not meet review, you see the following:

{
  "review_feedback": [
    {
      "id":23842500258220001,
      "text":"Body 1",
      "reason":["ALCOHOL"]
    },
    {
      "id":23842500258160001,
      "text":"Title 1",
      "reason":["ALCOHOL"]
    },
    {
      "id":23842500258170001,
      "text":"Title 2",
      "reason":["ALCOHOL"]}
    },
  ],
  "id": "AD_ID" 
}