Localized Catalog for Dynamic Ads

Overview

Use this guide to set up your localized catalog for dynamic ads.

A Facebook product catalog is an object (or container) of information about your products and where you can upload your inventory.

How it Works

Facebook provides localized catalog functionality, enabling you to set up your product catalog to sell ads or do Instagram Shopping in different countries. Localizing the currency, price, translated name, and description are common cases. You can also use this functionality to navigate the customer to your country-specific website location. Learn more about how to set up your localized catalog.

Build a Template for Dynamic Ads

When building a template for dynamic ads, you can specify customizations to the creative that are in different languages. For example, you might want to show a different headline to viewers of your ad who speak another language.

In addition to the other fields in the creative's template data (within the object story spec), you can specify an array of customizations, in the customization_rules_spec field, where each customization has the following form:

Field NameDescriptionAccepts Template Parameters

customization_spec

type: object

Required.

Describes the language for the customization. Learn how to Create a Dynamic Ad for Multiple Languages and Countries, Ads Help Center.

Example: {'language' => 'en_XX'}

No

message

type: string

Optional.

Message for your ad, visible on Instagram.

Example: Test {{product.name | titleize}}

Yes

link

type: string

Optional.

Link to your website, used to generate the caption of the ad. This field is always replaced with the link field from your product feed, except the end card of Carousel Ads which will link to this. This cannot be a URL on Facebook.com.

Example: //link.com

No

name

type: string

Optional.

Name or title for your ad, visible on Instagram.

Example: Headline {{product.price}}

Yes

description

type: string

Optional.

Description for your ad. Not visible on Instagram.

Example: Description {{product. description}}

Yes

template_url_spec

type: object

Optional.

Can be used to provide a web deep link, as detailed in Click Tracking and Templates. Note: We only support the web deeplink.

Example: {'web' => {'url' => DEEP_LINK}}
Example: {'web' => {'url' => 'example://link/?id={{product. retailer_id}}'}}

Yes

When specifying the array of customizations, only one of the customizations should specify only the customization_spec. This identifies the language of the non-customized text that has been used in the template_data.

When the ad is rendered, the rendering language is chosen, based on the viewer's interface language and other signals. Facebook also uses product properties from the catalog language feed to match the rendering language, if available.

See also Build a Creative Template, Supported Fields for Dynamic Ads, and Supported Feed Formats for Dynamic Ads.

Examples

Preview Multi-Language or Country Dynamic Ads for a Different Language or Country


curl -X GET \ -d 'ad_format="DESKTOP_FEED_STANDARD"' \ -d 'product_item_ids=[ "<PRODUCT_ITEM_ID>" ]' \ -d 'dynamic_customization={ "language": "fr_XX", "country": "FR" }' \ -d 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v5.0/<CREATIVE_ID>/previews
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdCreative = bizSdk.AdCreative; const AdPreview = bizSdk.AdPreview; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_CREATIVE_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'ad_format' : 'DESKTOP_FEED_STANDARD', 'product_item_ids' : ['<productItemID>'], 'dynamic_customization' : {'language':'fr_XX','country':'FR'}, }; const previewss = (new AdCreative(id)).getPreviews( fields, params ); logApiCallResult('previewss api call complete.', previewss);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdCreative; use FacebookAds\Object\AdPreview; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_CREATIVE_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'ad_format' => 'DESKTOP_FEED_STANDARD', 'product_item_ids' => array('<productItemID>'), 'dynamic_customization' => array('language' => 'fr_XX','country' => 'FR'), ); echo json_encode((new AdCreative($id))->getPreviews( $fields, $params )->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adcreative import AdCreative from facebook_business.adobjects.adpreview import AdPreview from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_CREATIVE_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'ad_format': 'DESKTOP_FEED_STANDARD', 'product_item_ids': ['<productItemID>'], 'dynamic_customization': {'language':'fr_XX','country':'FR'}, } print AdCreative(id).get_previews( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_CREATIVE_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdCreative(id, context).getPreviews() .setAdFormat(AdPreview.EnumAdFormat.VALUE_DESKTOP_FEED_STANDARD) .setProductItemIds(\"[\\"<productItemID>\\"]\") .setParam(\"dynamic_customization\", \"{\\"language\\":\\"fr_XX\\",\\"country\\":\\"FR\\"}\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_CREATIVE_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_creative = FacebookAds::AdCreative.get(id) previewss = ad_creative.previews({ fields: { }, ad_format: 'DESKTOP_FEED_STANDARD', product_item_ids: ['<productItemID>'], dynamic_customization: {'language':'fr_XX','country':'FR'}, })

Create a Carousel Dynamic Ad Template With Multiple Languages


curl -X POST \ -F 'name="Dynamic Ad Template Creative Sample"' \ -F 'object_story_spec={ "page_id": "<PAGE_ID>", "template_data": { "message": "English Test {{product.name | titleize}}", "link": "http://www.example.com/englishurl", "name": "English Headline {{product.price}}", "description": "English Description {{product.description}}", "customization_rules_spec": [ { "customization_spec": { "language": "en_XX" } }, { "customization_spec": { "language": "fr_XX" }, "message": "French Test {{product.name | titleize}}", "link": "http://www.example.com/frenchurl", "name": "French Headline {{product.price}}", "description": "French Description {{product.description}}", "template_url_spec": { "web": { "url": "http://www.example.com/frenchdeeplink" } } } ] } }' \ -F 'product_set_id="<PRODUCT_SET_ID>"' \ -F 'template_url_spec={ "web": { "url": "http://www.example.com/englishdeeplink" } }' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/adcreatives
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdCreative = bizSdk.AdCreative; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<AD_ACCOUNT_ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Dynamic Ad Template Creative Sample', 'object_story_spec' : {'page_id':'<pageID>','template_data':{'message':'English Test {{product.name | titleize}}','link':'http://www.example.com/englishurl','name':'English Headline {{product.price}}','description':'English Description {{product.description}}','customization_rules_spec':[{'customization_spec':{'language':'en_XX'}},{'customization_spec':{'language':'fr_XX'},'message':'French Test {{product.name | titleize}}','link':'http://www.example.com/frenchurl','name':'French Headline {{product.price}}','description':'French Description {{product.description}}','template_url_spec':{'web':{'url':'http://www.example.com/frenchdeeplink'}}}]}}, 'product_set_id' : '<productSetID>', 'template_url_spec' : {'web':{'url':'http://www.example.com/englishdeeplink'}}, }; const adcreatives = (new AdAccount(id)).createAdCreative( fields, params ); logApiCallResult('adcreatives api call complete.', adcreatives);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdCreative; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<AD_ACCOUNT_ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Dynamic Ad Template Creative Sample', 'object_story_spec' => array('page_id' => '<pageID>','template_data' => array('message' => 'English Test array(array(product.name | titleize))','link' => 'http://www.example.com/englishurl','name' => 'English Headline array(array(product.price))','description' => 'English Description array(array(product.description))','customization_rules_spec' => array(array('customization_spec' => array('language' => 'en_XX')),array('customization_spec' => array('language' => 'fr_XX'),'message' => 'French Test array(array(product.name | titleize))','link' => 'http://www.example.com/frenchurl','name' => 'French Headline array(array(product.price))','description' => 'French Description array(array(product.description))','template_url_spec' => array('web' => array('url' => 'http://www.example.com/frenchdeeplink')))))), 'product_set_id' => '<productSetID>', 'template_url_spec' => array('web' => array('url' => 'http://www.example.com/englishdeeplink')), ); echo json_encode((new AdAccount($id))->createAdCreative( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adcreative import AdCreative from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Dynamic Ad Template Creative Sample', 'object_story_spec': {'page_id':'<pageID>','template_data':{'message':'English Test {{product.name | titleize}}','link':'http://www.example.com/englishurl','name':'English Headline {{product.price}}','description':'English Description {{product.description}}','customization_rules_spec':[{'customization_spec':{'language':'en_XX'}},{'customization_spec':{'language':'fr_XX'},'message':'French Test {{product.name | titleize}}','link':'http://www.example.com/frenchurl','name':'French Headline {{product.price}}','description':'French Description {{product.description}}','template_url_spec':{'web':{'url':'http://www.example.com/frenchdeeplink'}}}]}}, 'product_set_id': '<productSetID>', 'template_url_spec': {'web':{'url':'http://www.example.com/englishdeeplink'}}, } print AdAccount(id).create_ad_creative( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<AD_ACCOUNT_ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdCreative() .setName(\"Dynamic Ad Template Creative Sample\") .setObjectStorySpec( new AdCreativeObjectStorySpec() .setFieldPageId(\"<pageID>\") .setFieldTemplateData( new AdCreativeLinkData() .setFieldCustomizationRulesSpec(Arrays.asList( new AdCustomizationRuleSpec() .setFieldCustomizationSpec(\"{\\"language\\":\\"en_XX\\"}\") , new AdCustomizationRuleSpec() .setFieldCustomizationSpec(\"{\\"language\\":\\"fr_XX\\"}\") .setFieldDescription(\"French Description {{product.description}}\") .setFieldLink(\"http://www.example.com/frenchurl\") .setFieldMessage(\"French Test {{product.name | titleize}}\") .setFieldName(\"French Headline {{product.price}}\") .setFieldTemplateUrlSpec( new AdCreativeTemplateURLSpec() .setFieldWeb(\"{\\"url\\":\\"http://www.example.com/frenchdeeplink\\"}\") ) )) .setFieldDescription(\"English Description {{product.description}}\") .setFieldLink(\"http://www.example.com/englishurl\") .setFieldMessage(\"English Test {{product.name | titleize}}\") .setFieldName(\"English Headline {{product.price}}\") ) ) .setProductSetId(\"<productSetID>\") .setTemplateUrlSpec(\"{\\"web\\":{\\"url\\":\\"http://www.example.com/englishdeeplink\\"}}\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<AD_ACCOUNT_ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adcreatives = ad_account.adcreatives.create({ name: 'Dynamic Ad Template Creative Sample', object_story_spec: {'page_id':'<pageID>','template_data':{'message':'English Test {{product.name | titleize}}','link':'http://www.example.com/englishurl','name':'English Headline {{product.price}}','description':'English Description {{product.description}}','customization_rules_spec':[{'customization_spec':{'language':'en_XX'}},{'customization_spec':{'language':'fr_XX'},'message':'French Test {{product.name | titleize}}','link':'http://www.example.com/frenchurl','name':'French Headline {{product.price}}','description':'French Description {{product.description}}','template_url_spec':{'web':{'url':'http://www.example.com/frenchdeeplink'}}}]}}, product_set_id: '<productSetID>', template_url_spec: {'web':{'url':'http://www.example.com/englishdeeplink'}}, })