Segment Asset Customization

This solution allows you to customize ad assets according to geo targeting types. To customize assets for different placements, see Placement Asset Customization.

Segment Asset Customization is one of our three APIs that use asset customization rules. See Asset Customization Rules.

This API is currently being tested and may not be available for all advertisers. Reach out to your Facebook representative for more information.

Recommended Steps

Customization Options

The ad can be customized by geo locations. You do that by creating a rule with a customization spec. Supported customization type is:

  • Geo-locations - Supports countries, regions, cities, geo_markets, zips, and location_types.

The format to specify a customization spec is similar to the format for core targeting, see Targeting.

Asset Customization Rules

Asset Customization Rules allow you to group assets that appear together for a given geo location. Each rule has a customization_spec that defines the geo locations of the people who can view those assets at the time of ad delivery.

You can specify a priority for each rule during their creation. Otherwise, we give each rule a priority number based on its position in the list of rules provided. For example, the first rule on the list is assigned priority 1.

You should setup a default rule to avoid the delivery of random combination of assets to people who do not match any rules. To set this up:

  • Create an empty customization_spec. Use opening and closing curly braces at the end of your rule, like so {}.
  • Assign the lowest priority to the rule. This is the total number of rules, including the default one. If you have 10 rules plus a default, the priority of the default should be 11.

The default rule matches a creative asset to people who do not satisfy any preceding rules.

In your setup, non-default rules should match a high percentage of your targeted audience.

Asset Feed Spec Setup

Create an asset_feed_spec and add your customization rules to the field asset_customization_rules. You can add up to 50 customization rules.

For each rule, you need to specify the customization_spec, priority and the asset labels. Your customization_spec cannot have more than 50 conditions for a single rule.

Example of an asset feed setup:

curl \
-F 'object_story_spec={
       "page_id": "<YOUR_PAGE_ID>",
       "instagram_actor_id" : "<INSTAGRAM_ACTOR_ID>"
    }' \
-F 'asset_feed_spec={
 "images": [
   {"hash":"<IMAGE_HASH>", "adlabels":[{"name":"image1"}]}, 
   {"hash":"<IMAGE_HASH>", "adlabels":[{"name":"image2"}]}
 ], 
 "bodies": [
   {"text":"Motor City Mission Corps", "adlabels":[{"name":"body1"}]}
 ], 
 "titles": [
   {"text":"Link title 1 goes here", "adlabels":[{"name":"title1"}]}, 
   {"text":"Link title 2 goes here", "adlabels":[{"name":"title2"}]},
   {"text":"Link title 3 goes here", "adlabels":[{"name":"title3"}]}
 ], 
 "call_to_action_types":[
   "LEARN_MORE"
 ],
 "descriptions": [
   {"text":"Begin Your Adventure"}
 ], 
 "ad_formats": [
   "SINGLE_IMAGE"
 ], 
 "link_urls": [
   {"website_url":"https://www.example.com/"}
 ],
 "asset_customization_rules": [
   { 
     "customization_spec": {
        "geo_locations": {
          "countries": ["US"]
        }
     },
     "image_label": {"name": "image1"},
     "title_label": {"name": "title1"},
     "priority": 1
   },
   {
     "customization_spec": {
       "geo_locations": {
          "countries": ["GB"]
        }
     }, 
     "image_label": {"name": "image1"},
     "title_label": {"name": "title2"},
     "priority": 2
   },
   {
     "customization_spec": {
       "geo_locations": {
         "cities": [
           {"key": "2481714"},
           {"key": "2481868"}
         ]
       }
     },
     "image_label": {"name": "image1"},
     "title_label": {"name": "title3"},
     "priority": 4
   },
   {
     "customization_spec": {}, 
     "image_label": {"name":"image2"},
     "title_label": {"name":"title1"},
     "priority": 5
  }]}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

See all available options for Asset Feed Spec. See Asset Customization Rules for next steps.

Preview Your Ad

Preview the different targeting rule versions of your ad using the /generatepreview endpoint. You can also add a dynamic_asset_label field with rule priority number to view a specific language version.

For example, to preview a rule with priority 1:

curl -G --data-urlencode 
'creative={ 
  "object_story_spec": { 
    "page_id": "<PAGE_ID>" 
  },
  "asset_feed_spec": {
    ...
    "asset_customization_rules": [
      { 
        "customization_spec": { 
          "geo_locations": { 
          "countries": ["US"] 
          } 
        },
        "image_label": {
          "name": "image1"
        },
        "title_label": {
          "name": "title1"
        },
        "priority": 1
    },
    ...
    ]
  }
}' 
-d 'ad_format=DESKTOP_FEED_STANDARD' 
-d 'dynamic_asset_label=1'
-d 'access_token=<ACCESS_TOKEN>' 
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/generatepreviews

Restrictions

Special Ad Category — Advertisers running housing, employment and credit ads, who are based in the United States or running ads targeted to the United States have different sets of restrictions. Those advertisers must adhere to Special Ad Category restrictions on asset_feed_spec. Learn more about Special Ad Category.

Campaign objectivesAPP_ENGAGEMENT is not supported.

Supported Placements — All placements are supported.

Buying typeReach and frequency or AUCTION.

Placement Customization — If placement customization is used in any of rules, all rules should include placement customization.

asset_feed_spec restrictions are the same as those for asset feed-based ads without customization rules. Except for the following:

  • Each image or video must have a label attached.
  • Only one image or video is eligible for display per asset_customization_rule.
  • Ad Formats: Two ad_formats are supported: SINGLE_IMAGE and SINGLE_VIDEO. Only one ad_format is allowed per asset feed.
  • You can only provide one item in call_to_actions_types.
  • For each placement setting in an ad set's targeting, you should provide at least one asset_customization_rule for it.