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:
| Manual App Ads | Automated App Ads |
|---|---|
1 Campaign Multiple ad sets Multiple ads | 1 campaign 1 ad set 1 ad |
Reliance on manual adjustments. | Reliance on machine learning adjustments. |
Manually test up to 50 creative combinations. | Dynamically test up to 50x5x5 creative combinations. |
Automated App Ads SKAdNetwork Campaigns targeting iOS 14 users are now available.
Before You Start
To use Automated App Ads, you need:
- A Facebook developer account
- A Facebook app
- The following permissions:
ads_managementandads_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:
| Parameter | Description |
|---|---|
adlabelslist of objects | Ad Labels associated with the Automated App Ads campaign. Optional. |
buying_typestring | Currently, Automated App Ads only supports the |
execution_optionslist of enums | Default value:
If the call passes validation or review, the response will be |
is_skadnetwork_attributionstring | Identifies a SKAdsNetwork Campaign. Optional |
namestring | Name for the Automated App Ads campaign. |
objectiveenum | This is the campaign goal. Specify |
promoted_objectobject | The object this ad set is promoting across all its ads. For Automated App Ads, provide:
Required if is_skadnetwork_attribution is set to true. |
smart_promotion_typelist of objects | To specify this is an Automated App Ads campaign, smart promotion type should be set to |
special_ad_categorieslist of objects | Automated App Ads currently does not support special ad categories. Please specify this as an empty list, like so |
statusenum | Valid options are: If this status is |
topline_idnumeric string or integer | Topline ID. Optional. |
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/v10.0/act_{ad-account-id}/campaignIf 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/v10.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:
| Parameter | Description |
|---|---|
billing_eventenum | The billing event that this ad set is using. For Automated App Aps, specify |
campaign_idnumeric string or integer | The ID for a valid Automated App Ads ad campaign you wish to add this ad set to. Required. |
namestring | Name for the Automated App Ads ad set. Required. |
optimization_goalenum | What the ad set is optimizing for. Automated App Ads supports the following optimization goals:
|
promoted_objectobject | The object this ad set is promoting across all its ads. For Automated App Ads, provide:
Required for all campaigns except SKAdNetwork Campaign. Optional for SKAdNetwork Campaign. |
targeting object | An Automated App Ad ad set’s targeting structure.
Valid targeting options are For example:
{
"geo_location": {
"countries": [“US”]
},
"locales": [8]
}Automated App Ads do not support operating system targeting, however SKAdsNetwork Automated App Ad campaigns will only target iOS14.5+ users. Required. |
enum | Choose a bid strategy for this ad set to suit your specific business goals. Each strategy has tradeoffs and may be available for certain For Automated App Ads, the following strategies are available:
|
list of objects | Required if Similar to an ad set budget, minimum Return on Ads Spend (ROAS) bidding uses this to provide the ROAS floor, but you cannot use |
integer | Required if Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your If an ad level The bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount is for each occurrence, and has a minimum value 1 US cents. The minimum bid amounts of other currencies are of similar value to the US Dollar values provided. |
enum | Only |
int64 | The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between Either |
int64 | Lifetime budget, defined in your account currency. If specified, you must also specify an Either |
datetime | Required when When creating an ad set with a For example: |
list of objects | Specifies list of labels to be associated with this object. Optional. |
datetime | The start time of the set. For example: |
datetime | Time to stop running this ad set. |
datetime | Time to start running this ad set. |
Targeting Fields
| Parameter | Description |
|---|---|
array | Used to limit the audience of the ad set via the required argument countries. Valid value: |
array | Target people with language other than common language for a location. To use this field, provide an ID for the language, such as 5 for German. See Targeting Search, Locales for more information. |
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/v10.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.
| Optimization Goal | Bid Strategy | Custom Event Type |
|---|---|---|
|
| Not applicable. |
|
| All standard app events, including |
|
|
|
|
|
|
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}/campaignStep 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:
| Parameter | Description |
|---|---|
string | Name of the ad. Required. |
int64 | The ID of the ad set. Required. |
AdCreative | The creative spec of the ad creative to be used by this ad. Valid fields are Provide a creative spec:
{
"creative": {
\"name\": \"<NAME>\",
\"object_story_spec\": <SPEC>
}
} |
AdCreative type: enum | Valid options during creation: |
list of objects | Ad labels associated with this ad. Optional. |
list of enums | Default value:
If the call passes validation or review, the response will be |
Creative Fields
| Parameter | Description |
|---|---|
AdCreativeObjectStorySpec | Use if you want to create a new unpublished page post and turn the post into an ad. The Page ID and the content to create a new unpublished page post. Required.Available fields:
|
AdAssetFeedSpec | Used for Dynamic Creative to automatically experiment and deliver different variations of an ad's creative. Specifies an asset feed with multiple images, text and other assets used to generate variations of an ad. Formatted as a JSON string. Available fields:
|
AdCreative | If set to |
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={"creative": {"name": {name}, "object_story_spec": {specifications}}}' \
-F 'access_token={access-token}' \
https://graph.facebook.com/v10.0/act_{ad-account-id}/adsIf 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.
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:
| Parameter | Description |
|---|---|
string | New name you would like to give to your Automated App Ads campaign. |
list of object | Ad Labels that should be associated with the Automated App Ads campaign. |
list of enums | Default value:
If the call passes validation or review, the response is |
numeric string or integer | Topline ID. |
enum | You can use the following status for an update API call:
If an ad campaign is set to |
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/v10.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:
| Parameter | Description |
|---|---|
list of objects | Specifies list of labels to be associated with this object. Optional. |
enum | Choose a bid strategy for this ad set to suit your specific business goals. Each strategy has tradeoffs and may be available for certain To update Automated App ad sets, the following strategies are available:
If you enable Campaign Budget Optimization, set |
integer | Required if Bid cap or target cost for this ad set. The bid cap used in a lowest cost bid strategy is defined as the maximum bid you want to pay for a result based on your If an ad level The bid amount's unit is cents for currencies like USD, EUR, and the basic unit for currencies like JPY, KRW. The bid amount is for each occurrence, and has a minimum value 1 US cents. The minimum bid amounts of other currencies are of similar value to the US Dollar values provided. |
int64 | The daily budget defined in your account currency, allowed only for ad sets with a duration (difference between |
datetime | End time, required when When creating an ad set with a daily budget, specify |
list of enums | Optional. Default value:
If the call passes validation or review, the response is |
object | Required with certain campaign objectives. The object this ad set is promoting across all its ads. Available options are:
|
datetime | The start time of the set. Must be provided in UTC UNIX timestamp. For example: |
enum | Available options for updates:
|
int64 | Lifetime budget, defined in your account currency. If specified, you must also specify an |
datetime | Time to start running this ad set. |
datetime | Time to stop running this ad set. |
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/v10.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:
| Parameter | Description |
|---|---|
string | Name of the ad. |
list of objects | Ad labels associated with this ad. |
list of enums | Optional. Default value:
If the call passes validation or review, the response is |
enum | Options are:
During testing, it is recommended to set ads to a |
AdCreative | The creative spec of the ad creative to be used by this ad. Valid fields can be found on Creative Fields. Provide the creative spec as follows:
{
"creative": {
\"name\": \"<NAME>\",
\"object_story_spec\": <SPEC>
}
} |
Ad Update Example
curl -X POST \
-F 'name=Automated App Ads Sample Update Ad' \
-F 'creative={"creative": {"name": {name}, "object_story_spec": {specifications}}}' \
-F 'access_token={access-token}' \
https://graph.facebook.com/v10.0/{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/v10.0The 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_tag_123",
"video_id": "123456789",
"thumbnail_url": "<url>",
"thumbnail_hash": "<hash>"
},
],
}