Automated App Ads API

Automated App Ads use machine learning and automated systems to drive more results for your app install ads. This solution helps you scale campaigns and, ultimately, it makes your work more efficient.

To use Automated App Ads, your ad campaigns need to be set up in a 1:1:1 structure: 1 ad campaign, 1 ad set, and 1 ad. See the comparison between regular App Ads and Automated App Ads:

Before You Start

To use Automated App Ads, you need:

• A Facebook developer account
• A Facebook app
• The following permissions: ads_management and ads_read

You must be authorized to make GET and POST calls to the ad account used to fund your ads.

Step 1: Create Campaign

Send a POST request to /act_{ad_account_id}/campaigns with the following required, and optional, parameters:

Campaign Creation Call Example

curl -X POST \
  -F 'name=Automated App Ads Sample Campaign' \
  -F 'objective=APP_INSTALLS' \
  -F 'status=ACTIVE' \
  -F 'special_ad_categories=[]' \
  -F 'smart_promotion_type=SMART_APP_PROMOTION' \
  -F 'access_token={access-token}' \
https://graph.facebook.com/v12.0/act_{ad-account-id}/campaigns

If you already have a campaign and want to update it, see After Launch, Update Campaign.

Step 2: Verify Campaign Creation (Optional)

As an option, you can check if you have successfully created an Automated App Ad Campaign. To do that, make a GET request to /{ad-campaign-id} with the field smart_promotion_type. A valid Automated App Ad Campaign returns SMART_APP_PROMOTION.

Campaign Verification Call Example

curl -X GET -G \
  -d 'fields="smart_promotion_type"' \
  -d 'access_token={access-token}' \
https://graph.facebook.com/v12.0/{ad-campaign-id}

Example response, if a valid Automated App Ad Campaign was created:

{
  "smart_promotion_type": "SMART_APP_PROMOTION",
  "id": {ad-campaign-id}
}

Step 3: Create Ad Set

Once you have an ad campaign, create your ad set. An ad set is a group of ads that share the same daily or lifetime budget, schedule, bid type, bid info, and targeting data.

To create an ad set, make a POST request to /act_{ad_account_id}/adsets. You may include the following parameters:

{
   "geo_location": {
     "countries": [“US”]
     },
   "locales": [8]
}

Targeting Fields

Ad Set Creation Call Example

curl -X POST \
  -F 'name=Automated App Ads Sample Ad Set' \
  -F 'campaign_id={campaign-id}' \
  -F 'optimization_goal=APP_INSTALLS' \
  -F 'promoted_object={ "application_id": "{app-id}", "object_store_url": "{store-object-id} }' \
  -F 'daily_budget=<num>' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'targeting={"geo_locations": {"countries": ["US"]}}' \
  -F 'access_token={access-token}' \
https://graph.facebook.com/v12.0/act_{ad-account-id}/adsets

If you already have an ad set and want to update it, see After Launch, Update Ad Sets.

Optimization Compatibility

At the ad set level, you must specify optimization goal, bid strategy and custom event type. The following table outlines valid combinations of these fields.

SKAdNetwork Set Creation Call Example

curl -X POST \
  -F 'name=Automated App Ads Sample Campaign' \
  -F 'objective=APP_INSTALLS' \
  -F 'status=ACTIVE' \
  -F 'special_ad_categories=[]' \
  -F 'smart_promotion_type=SMART_APP_PROMOTION' \
  -F 'is_skadnetwork_attribution=true' \
  -F 'promoted_object={ "application_id": "{app-id}", "object_store_url": "{object-store-url}" }' \ 
  -F 'access_token={access-token}' \
https://graph.facebook.com/act_{ad-account-id}/campaigns

Step 4: Provide Creative and Create Ads

Once you have an ad set, you can create your ad by posting to the /act_{ad_account_id}/ads endpoint. You may include the following parameters:

{
  "creative": {
    \"name\": \"<NAME>\", 
    \"object_story_spec\": <SPEC>
  }
}

Creative Fields

Ad Creation Call Example

If you provide your creative formatted as creative spec:

curl -X POST \
  -F 'name=Automated App Ads Sample Ad' \
  -F 'adset_id={adset-id}' \
  -F 'creative={"name": {name}, "object_story_spec": {specifications}}' \
  -F 'access_token={access-token}' \
https://graph.facebook.com/v12.0/act_{ad-account-id}/ads

If you already have an ad and want to update it, go to After Launch, Update Ads.

After Launch

After you launch your Automated App Ads, you may need to update or read your ad objects —see how to perform those actions below. For ad insights information, see our Asset Feed Spec, Insights documentation.

Update Campaigns

If you need to update an Automatic App Ads campaign, make a POST request to /{campaign_id}. You can use the following parameters in your API call:

Campaign Update Example

curl -X POST \
-F 'name=Automated App Ads Update Sample Campaign' \
-F 'status=PAUSED' \
-F 'access_token={access-token}' \
https://graph.facebook.com/v12.0/{campaign-id}

Update Ad Sets

If you need to update an Automatic App Ads ad set, make a POST request to /{ad_set_id}. You can use the following parameters in your API call:

Ad Set Update Example

curl -X POST \
  -F 'name=Automated App Ads Sample Updated Ad Set' \
  -F 'bid_strategy=LOWEST_COST_WITH_BID_CAP' \
  -F 'bid_amount=200' \
  -F 'access_token={access-token}' \
https://graph.facebook.com/v12.0/{ad-set-id}

Update Ads

If you need to update an Automatic App Ads ad, make a POST request to /{ad_id}. You can use the following parameters in your API call:

{
  "creative": {
    \"name\": \"<NAME>\", 
    \"object_story_spec\": <SPEC>
   }
}

Ad Update Example

curl -X POST \
-F 'name=Automated App Ads Sample Update Ad' \
-F 'creative={"name": {name}, "object_story_spec": {specifications}}' \
-F 'access_token={access-token}' \
https://graph.facebook.com/{ad-id}

See Ad Asynchronous Batch Requests to update ads with multiple videos or images.

Troubleshooting

While uploading a high quantity of videos to your Automated App Ad creative spec, you may encounter one of the following errors:

• Error Code 1: An unknown error occurred
• Service temporarily unavailable
• Error Code 2: An unexpected error has occurred. Please retry your request later.

If you see one of these errors, you can try one of the following solutions:

Solution 1: Use Async Batch Requests

Use asynchronous batch requests to make multiple Graph API calls in a single HTTP request —learn more about Asynchronous Batch Requests.

Use Async To Create Ads

Below is an example of an async batch request being used to create an Automated App Ads campaign ad with multiple videos:

curl -F 'access_token=<ACCESS_TOKEN>' \  
     -F 'asyncbatch=[{
          "method":"POST",
          "relative_url":"act_{ad_account_id}/ads",
          "body":"name":"Example Async Update Ad",
                 "creative={
                   "object_story_spec": {
                     "page_id": "<PAGE_ID>",
                    },
                  "asset_feed_spec": {
                    "videos": [
                      {
                       "url_tags": "example_url_tag_123",
                       "video_id": "<VIDEO_ID>",
                       "thumbnail_url": "https://www.facebook.com/ads/image/?d=<HASH>",
                       "thumbnail_hash": "1a2b3c4d"
                      },
                     ],
                 }
              }
         }]' \
https://graph.facebook.com/v12.0

The response returns an async_session_id, which you can then use to fetch the query results.

Use Async To Update Ads

To update an existing ad, change the relative_url to the "{ad_id}". Learn more about using an async request to update an ad here.

Solution 2: Use Ad Images

Using external thumbnail_urls for a large quantity of creatives can also cause potential timeout issues. To prevent this from happening, you can upload and manage images to later use in ad creative via Ad Images.

To use this solution, make a POST request to /adimages edge from the following path /act_{ad_account_id}/adimages.

When you post to this edge, an AdImage is created, returning an url and hash, which you can then use to create your video within the ad creative asset feed of your ad like so:

"asset_feed_spec": {
  "videos": [
    { 
     "url_tags": "{example-url-tag}",
     "video_id": "{video-id}",
     "thumbnail_url": "{thumbnail-url}",
     "thumbnail_hash": "{thumbnail-hash}"
    },
  ],
}