Dynamic Language Optimization

This API is available on a limited basis as a beta release. Dynamic language optimization: Place ads in multiple languages from one ad set, such as in headline and body text. Facebook optimizes your ad to show the right language to the right people. For more general information, see Ads Help Center, Advertise to a multilingual audience.

The high-level steps are as follows:

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_assets
    

Limitations

Restrictions and limits on your asset feed are below.

General:

  • Maximum number of assets per type is 6
  • 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 which is distinct from the default_language
  • language must be selected from the list of available languages
  • Body assets should have values for all languages.

Text: Titles, descriptions, body text maximum length is 255 characters.

Images:

Available Ad Objectives:

  • LINK_CLICKS
  • MOBILE_APP_INSTALLS
  • WEBSITE_CONVERSIONS

Parameters for Assets

We group together assets from an asset feed based on the language field. These grouped assets always appear together in an ad impression. All the assets, except call_to_action_type, must have the language field.

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

You should provide least one asset per asset type with its language set as the default_language.

Property NameDescriptionTypeRequired

images

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

Structured as: {"url": "IMAGE_URL", "hash": "IMAGE_HASH", "url_tags": "<TAG>", "language": "<LANGUAGE>"} where either url or hash required, however language is optional

Yes. You must provide either an 'image' or a 'video'.

video

Videos which are in the ad account's video library

Structure as: {"video_id": "<VIDEO_ID>", "language": "<LANGUAGE>"} where language is optional.

Yes

bodies

Array of bodies containing primary message of ad.

array of list of {"text": "<BODY_TEXT>", "url_tags": "<TAG>", "language": "<LANGUAGE>"}

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": "<LANGUAGE>"}

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": "<LANGUAGE>"}

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

link_urls

Array of link URLs

array of list of {"website_url": "<URL>", "language": "<LANGUAGE>"}

Yes. For the APP_INSTALL objective, you must provide the app store destination paths for website_url.

call_to_action_type

Call-to-action-type

CALL_TO_ACTION

No

default_language

Specifies the default language

Required. Provide as string, such as 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 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 Asset Feeds

This example creates an asset feed with text fields grouped together by language, where each text field has the same link_url:

curl \
-F "image={'hash':'6aa335e3cb84870d737b5743b11f229b'}" \
-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 meet the 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>

Creating Ads with Languages

After you set up your asset feed with languages, you can create a campaign, ad set and then ads which your languages. For example, create a APP_INSTALLS 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 returns a new campaign ID:

{"id":"1111111111110001"}

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

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”]

You can create only one ad per ad set that uses a language asset feed.

For example, create an ad set for mobile app installs:

curl \
-F 'billing_event=IMPRESSIONS' \
-F 'campaign_id=23842500259110001' \
-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 'promoted_object={
    "application_id":"<APPLICATION_ID>",
    "object_store_url":"<APP_STORE_URL>"
    }' \
-F 'end_time=1505220533' \
-F "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adsets

This returns a new adset ID:

{"id":"22222200222220001"}

Finally, create an ad that uses your asset feed. Specify your ad set ID and asset feed ID:

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":11111100258220001,
      "text":"Body 1",
      "reason":["ALCOHOL"]
    },
    {
      "id":22222200258160001,
      "text":"Title 1",
      "reason":["ALCOHOL"]
    },
    {
      "id":33333300258170001,
      "text":"Title 2",
      "reason":["ALCOHOL"]}
    },
  ],
  "id": "<AD_ID>" 
}