App Ads
Updated: May 21, 2026
This document describes various ad units designed to drive installs and engagement for desktop and mobile apps.
You should use this ad unit to drive people to your desktop or mobile app for the purpose of either install or engagement using photo, video, carousel, or Playable creatives.
Conceptually this allows for the following ads:
| Photo | Video | Carousel | Playable | |
|---|---|---|---|---|
Mobile Install Ad | ✓ | ✓ | ✓ | ✓ |
Mobile Engagement Ad | ✓ | ✓ | ✓ | |
Desktop Install Ad | ✓ | ✓ | ✓ | |
Desktop Engagement Ad | ✓ | ✓ | ✓ | |
Desktop App Ad for Virtual Goods | ✓ | ✓ | ✓ |
Desktop app ads for virtual goods are a subset of desktop engagement, you can use virtual good offers to re-engage your players to come back into your app. For example, an app can offer a discount for an item or a set of their in-app currency in feed to re-engage past payers. See here for instructions on how to set up your app to accept payments.
For reference, this is what the mobile install image unit looks like:

This is what the desktop app ad for virtual goods with image looks like

Prerequisites
- To create an app ad, the app developer must complete the steps in this tutorial.
- The advertiser must have a Facebook Page with which to run these ads through.
Create
When creating the ad, note the following requirements:
- Campaign objective must be
APP_INSTALLS,LINK_CLICKS, orCONVERSIONS. - Ad set promoted object must be set
- Targeting
- For mobile app ads, you must use the mobile targeting spec
user_osfield. The placement should have adevice_platformsfield with value of [‘mobile’] and highly recommend the use of the spec’s other fields to target mobile devices on Facebook. Optionally, you can specifypublisher_platformsif you only want certain platforms. - For canvas app ads,
device_platformsmust bedesktop. Optionally, you can specifyfacebook_positionsif you do not want both Facebook desktop Feed and Right-Hand-Side column. - When
GET_OFFERis used for virtual goods, the price must be discounted. See virtual goods for more information.
App Ad call to actions:
The below additional Call to Actions are available for app ads within the
call_to_action field of a post or the ad creative’s object_story_spec. You can also specify the mobile app’s deep link in the app_link field, or the desktop app’s virtual good object in the product_link field.| Key | Value | Required |
|---|---|---|
type | Call to action types for mobile, regardless of install or engagement: SHOP_NOWBOOK_TRAVELLEARN_MORESIGN_UPDOWNLOADINSTALL_MOBILE_APPUSE_MOBILE_APPWATCH_VIDEOWATCH_MOREOPEN_LINKCall to action types for desktop install or engagement: USE_APP (desktop apps)PLAY_GAME (desktop game apps)Call to action types for desktop app ads for virtual goods: BUY_NOWGET_OFFER | yes |
value | JSON dictionary of:
{"link": "<APP_STORE_LINK>","app_link": "<MOBILE_DEEP_LINK>","product_link": "<VIRTUAL_GOOD_DEEP_LINK>","link_title": "<NAME_FOR_LINK>"} | yes
|
value.link | refers to the App Store, Google Play Store, or Facebook Canvas App URL, for example, https://itunes.apple.com/us/app/facebook/id284882215 | yes |
value.app_link | To define the deep link destination only for mobile apps, for example, myapp://product/12345.
To specify a deep link for desktop apps you should specify it directly in the URL link field. | yes, only for mobile install or engagement ads |
value.product_link | To define the URL that points to the product’s Open Graph virtual good object. See here for setup details. | yes, only for desktop virtual goods |
value.link_title | Allows you to customize the name for the link, which shows up below the ad’s image | no |
Field specification

Create with photo
To create a desktop or mobile app ad with a photo, first create a link Page Post with a photo using the ad creative’s
object_story_spec: {'link_data': ...} field.Example:
curl -X POST \
-F 'name="Sample Creative"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"link_data": {
"call_to_action": {
"type": "INSTALL_MOBILE_APP",
"value": {
"link": "<APP_STORE_URL>"
}
},
"image_hash": "<IMAGE_HASH>",
"link": "<APP_STORE_URL>",
"message": "Try it out"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
Alternatively, you can create the Page Post through the Page’s feed endpoint and use the post ID in the creative. See the examples section below for more examples.
Create with carousel
To create a mobile app install or engagement ad using the carousel ad format, follow the instructions in the carousel ads docs except in each
child_attachments’ link field, specify an app store link.Considerations
- Currently carousel mobile app ads support only one app
- Minimum number of 3 images (vs. 2 on non-app ad carousel ads)
- Carousel mobile app ads must have a call to action defined
- The end card (typically displaying the Page’s profile photo) will not be displayed for carousel mobile app ads.
Note that you should specify the same app store link in each
child_attachment. You do not have to specify the link again in the call_to_action:{'value':{'link':... }}}curl -X POST \
-F 'name="Carousel app ad"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"link_data": {
"message": "My message",
"link": "http://www.example.com/appstoreurl",
"caption": "WWW.ITUNES.COM",
"name": "The link name",
"description": "The link description",
"child_attachments": [
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
},
{
"link": "http://www.example.com/appstoreurl",
"image_hash": "<IMAGE_HASH>",
"call_to_action": {
"type": "USE_MOBILE_APP",
"value": {
"app_link": "<DEEP_LINK>"
}
}
}
],
"multi_share_optimized": true
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
Create with Video
To create an app ad with a video, first upload a video to the ad account’s video library. Then use the video ID in the ad creative’s
object_story_spec: {'video_data':...} field.Example:
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {
"call_to_action": {"type":"INSTALL_MOBILE_APP","value":{"link":"<APP_STORE_URL>"}},
"image_url": "<THUMBNAIL_URL>",
"video_id": "<VIDEO_ID>"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
Alternatively, you can create the Page Post through the Page’s video endpoint and use the video ID in the creative. See the examples section below for more examples.
Read
To retrieve details about your Page Post, refer to the link Page Post docs or video Page Post docs.
You can list all Page Posts from the Page’s
/promotable_posts edge.curl https://graph.facebook.com/v25.0/<PAGE_ID>/promotable_posts
To retrieve details about your ad creative, refer to the ad creative documentation.
Mobile measurement
Deep links
Before you start
- Set up your app to support deep links
- The
pages_manage_adspermission - A Page access token requested by a person who can perform the
ADVERTISEtask on the Page - The app link, if your app supports app links
Sample code
"call_to_action={ 'type':'LEARN_MORE', 'value':{ 'link':'https://itunes.apple.com/us/app/facebook/id284882215', 'app_link':'facebook://path/to/page' } }"
Before specifying an app link, you should validate that it has been scraped by calling:
https://graph.facebook.com/v25.0/?type=og&scrape=true&id=<APP_LINK>
Mobile app insights
Insights only apply for ads with a promoted object containing the app ID. To obtain an app ID, register the app on Facebook.
Meta will provide aggregated daily insights on the demographics of people who installed your app. To retrieve this, you should use an app access token and query
https://graph.facebook.com/v25.0/<APP_ID>/insights/application_mobile_app_installs?&access_token=<ACCESS_TOKEN>
You can also breakdown stats by specifying an additional URL parameter,
breakdown, equal to one of the following values. You cannot currently combine breakdowns.| Name | Description |
|---|---|
gender_age | Break down your statistics on audience’s age and gender |
country | Break down your statistics on audience’s country |
locale | Break down your statistics on audience’s locale |
Examples:
https://graph.facebook.com/v25.0/<APP_ID>/insights/application_mobile_app_installs?breakdown=gender_age&access_token=<ACCESS_TOKEN>
https://graph.facebook.com/v25.0/<APP_ID>/insights/application_mobile_app_installs?breakdown=country&access_token=<ACCESS_TOKEN>
https://graph.facebook.com/v25.0/<APP_ID>/insights/application_mobile_app_installs?breakdown=locale&access_token=<ACCESS_TOKEN>
Examples
Create a mobile app install image ad
Step 1. create the Page Post with image. Note that you should use
PAGE_ACCESS_TOKEN and Pages API session to create Page Post.curl \
-F 'message=Sign up today' \
-F 'picture=<IMAGE_URL>' \
-F 'link=<LINK>' \
-F 'published=1' \
-F 'call_to_action={"type":"SIGN_UP","value":{"link":"<LINK>"}}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
Step 2. Create the ad creative (
{STORY_ID} is in form of '{PAGE_ID}_{POST_ID}')curl -X POST \
-F 'object_story_id="<PAGE_ID>_<POST_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
Step 3. Use the creative in an ad
curl -X POST \
-F 'name="My AdGroup with Redownload"' \
-F 'adset_id="<AD_SET_ID>"' \
-F 'creative={
"creative_id": "<CREATIVE_ID>"
}' \
-F 'redownload=1' \
-F 'status="PAUSED"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads
Create a mobile app image ad with a deep link, optimizing for clicks, paying for impressions
Step 1. Create the Page Post with image. Note that you should use
PAGE_ACCESS_TOKEN and Pages API session to create Page Post.curl -X POST \
-F 'message="This is a test message"' \
-F 'call_to_action={
"type": "BUY_NOW",
"value": {
"link": "<APP_STORE_URL>",
"app_link": "<DEEP_LINK>"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
Step 2. Create the ad creative
curl -X POST \
-F 'object_story_id="<PAGE_ID>_<POST_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
Step 3. Set the bidding at the ad set, optimizing for clicks, paying for impressions.
curl \
-F 'name=LifetimeBudgetSet' \
-F 'lifetime_budget=100000' \
-F 'bid_amount=500' \
-F 'billing_event=IMPRESSIONS' \
-F 'optimization_goal=LINK_CLICKS' \
-F 'promoted_object={"application_id":"<APP_ID>","object_store_url":"<APP_STORE_URL>"}' \
-F 'targeting={
"facebook_positions": ["feed"],
"geo_locations": {"countries":["US"]},
"publisher_platforms": ["facebook","audience_network"],
"user_os": ["IOS"]
}' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'end_time=2018-02-06T04:45:30+0000' \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
Step 4. Use the creative in an ad
curl \
-F 'name=My Ad' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'redownload=1' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads
Create a mobile app engagement image ad with an app link, optimizing for app events, paying for impressions
Step 1. Create the Page Post with image. Note that you should use
PAGE_ACCESS_TOKEN and Pages API session to create Page Post.curl \
-F 'message=Check out this App today. Available on iTunes.' \
-F 'published=1' \
-F 'link=<APP_STORE_URL>' \
-F 'picture=<IMAGE_URL>' \
-F 'call_to_action={
"type": "LEARN_MORE",
"value": {"link":"<APP_STORE_URL>","app_link":"<APP_DEEP_LINK>"}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
Step 2. Create the ad creative
curl -X POST \
-F 'object_story_id="<PAGE_ID>_<POST_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
Step 3. Set the bidding at the ad set, optimizing for app events, paying for impressions.
Note you must also set the ad set’s
promoted_object to include a custom_event_type to optimize towards, see ad set docs for more details.curl -X POST \
-F 'name="A CPA Ad Set optimized for App Events"' \
-F 'campaign_id="<AD_CAMPAIGN_ID>"' \
-F 'daily_budget=300' \
-F 'start_time="2025-11-13T15:11:01-0800"' \
-F 'end_time="2025-11-20T15:11:01-0800"' \
-F 'billing_event="IMPRESSIONS"' \
-F 'optimization_goal="OFFSITE_CONVERSIONS"' \
-F 'bid_amount=100' \
-F 'status="PAUSED"' \
-F 'promoted_object={
"application_id": "<APP_ID>",
"object_store_url": "<APP_STORE_URL>",
"custom_event_type": "PURCHASE"
}' \
-F 'targeting={
"facebook_positions": [
"feed"
],
"geo_locations": {
"countries": [
"US"
]
},
"user_os": [
"iOS"
]
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
Step 4. Use the creative in an ad
curl \
-F 'name=My Ad' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'redownload=1' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads
Examples for Page Post ads
Note that you should use
PAGE_ACCESS_TOKEN and Pages API session to create Page Post.Create a mobile app install video ad
curl \
-F 'name=My Video' \
-F 'message=Check out this app!' \
-F 'thumbnail=<APP_STORE_URL>' \
-F 'published=0' \
-F 'call_to_action={"type":"INSTALL_MOBILE_APP","value":{"link":"<APP_STORE_URL>"}}' \
-F 'source=@<VIDEO_PATH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/videos
Create a mobile app video ad with a deep link
curl \
-F 'name=My Video' \
-F 'message=Check out this app!' \
-F 'thumbnail=<APP_STORE_URL>' \
-F 'published=0' \
-F 'call_to_action={
"type": "LEARN_MORE",
"value": {"link":"<APP_STORE_URL>","app_link":"<APP_DEEP_LINK>"}
}' \
-F 'source=@<VIDEO_PATH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/videos
Create a desktop app install video ad
curl \
-F 'name=My Video' \
-F 'message=Check out this app!' \
-F 'thumbnail=<THUMBNAIL_PATH>' \
-F 'published=0' \
-F 'call_to_action={"type":"PLAY_GAME","value":{"link":"<THUMBNAIL_PATH>"}}' \
-F 'source=@<VIDEO_PATH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/videos
Create a desktop app ads for virtual goods image ad
curl \
-F 'message=Buy coins now!' \
-F 'picture=<IMAGE_URL>' \
-F 'link=<LINK>' \
-F 'published=1' \
-F 'call_to_action={"type":"BUY_NOW","value":{"link":"<LINK>","product_link":"<PRODUCT_LINK>"}}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/feed
Create a desktop app ads for virtual goods video ad
curl \
-F 'name=My Video' \
-F 'message=Buy coins now!' \
-F 'thumbnail=<THUMBNAIL_PATH>' \
-F 'published=0' \
-F 'call_to_action={
"type": "BUY_NOW",
"value": {"link":"<THUMBNAIL_PATH>","product_link":"<THUMBNAIL_PATH>"}
}' \
-F 'source=@<VIDEO_PATH>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/<PAGE_ID>/videos
Create app ads with Awareness objectives
To provide universal link treatment for the Awareness objective, you can include the app ID under
creative.template_url_spec. If not provided, the ad will lead users to your website.curl \
-F 'name=Advantage+ Catalog Ads Template Creative Sample' \
-F 'template_url_spec={
"config": {
"app_id": "1596400373958175"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
Create static ads with Traffic objective app-fallback-to-web behavior
When an app is selected in an ad set, this is the change in
object_story_spec after web fallback is added.curl -X POST \
-F 'name="Traffic app fallback web sample"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"template_data": {
"call_to_action": {
"type": "INSTALL_MOBILE_APP",
"value": {
"link": "https://www.example.com"
“app_link”: “<DEEPLINK_URL>
“object_store_urls”: [
<STORE_URL_OF_APP>
]
}
},
"message": "Test {{product.name | titleize}}",
"link": "https://www.example.com"",
"name": "Headline {{product.price}}",
"description": "Description {{product.description}}"
}
}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
If fallback needs to be a store, provide the store URL under the
link field. If fallback needs to be a website, provide the object_store_urls value as a list with just one value — the app store URL of the app — and the link field with the website fallback URL.Advantage+ Catalog Ads for Mobile App Install
Advantage+ catalog ads can drive people to install your mobile app. This enables you to retarget people with mobile install ads, based on user behavior.
Step 1. Create a campaign for your product catalog
curl -X POST \
-F 'name="App Installs Campaign with Dynamic Product Ads"' \
-F 'objective="OUTCOME_APP_PROMOTION"' \
-F 'status="PAUSED"' \
-F 'special_ad_categories=[]' \
-F 'is_adset_budget_sharing_enabled=0' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/campaigns
Step 2. Create an ad set for a specific product set under the above product catalog
curl \
-F 'name=Mobile App Installs Ad Set with Dynamic Product Ads' \
-F 'bid_amount=3000' \
-F 'billing_event=IMPRESSIONS' \
-F 'optimization_goal=APP_INSTALLS' \
-F 'daily_budget=15000' \
-F 'campaign_id=<CAMPAIGN_ID>' \
-F 'targeting={
"geo_locations": {"countries":["US"]},
"publisher_platforms": ["facebook","audience_network"],
"device_platforms": ["mobile"],
"user_os": ["IOS"],
"dynamic_audience_ids": ["<PRODUCT_AUDIENCE_ID>"]
}' \
-F 'promoted_object={
"product_set_id": "<PRODUCT_SET_ID>",
"application_id": "<APP_ID>",
"object_store_url": "<APP_STORE_URL>"
}' \
-F 'status=PAUSED' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adsets
Step 3. Create the Advantage+ catalog ads creative by using template
curl -X POST \
-F 'name="Advantage+ catalog ads template creative sample"' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"template_data": {
"call_to_action": {
"type": "INSTALL_MOBILE_APP",
"value": {
"link": "http://www.example.com/appstoreurl"
}
},
"message": "Test {{product.name | titleize}}",
"link": "http://www.example.com/appstoreurl",
"name": "Headline {{product.price}}",
"description": "Description {{product.description}}"
}
}' \
-F 'product_set_id="<PRODUCT_SET_ID>"' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
Step 4. Use the above Ad creative in an Ad
curl \
-F 'name=My Ad' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'redownload=1' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads
Upload Playable HTML File to Ad Account
curl -X POST \
-F "name=<NAME>" \
-F "source=<>" \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adplayables"
name: Name that differentiates the ad asset from other playable ads in the ad account; for example,{ad_name}->{playable_asset_name}source: Absolute path of the file on your local machineaccess_token: Can be generated from the Graph API Explorer- You can also use an existing playable asset ID within the ad account
Meta Tag in Playable HTML File
You can add two metadata tags to your playable HTML 5 file. This enables Meta to attribute the playable in the ads to your app.
... <head> ... <meta name="ref-application-id" content="<YOUR_APP_ID>"> <meta name="ref-asset-id" content="<YOUR_ASSET_ID>"> ... </head> ...
- Please provide your Meta app ID and asset ID meta tag in the playable HTML file. This helps Meta provide accurate insights about the asset when it appears in your ad.
- The asset ID uniquely identifies this playable element in your system.
Create Ads in Ad Account
- Set placement to Facebook Feed. Audience Network Rewarded Video and Interstitial only. Please contact your Meta partner for more details.
- Creative can only be video with aspect ratio of >= 1
- Set up the budget and schedule
- Create the playable creative in API:
curl \
-F 'name=Sample Creative' \
-F 'object_story_spec={
"page_id": "<PAGE_ID>",
"video_data": {
"call_to_action": {
"type":"INSTALL_MOBILE_APP",
"value":{
"application":<APP_ID>,
"link":"<APP_STORE_URL>"
}
},
"image_url": "<THUMBNAIL_URL>",
"link_description": "try it out",
"video_id": "<VIDEO_ID>"
}
}' \
-F 'playable_asset_id=<PLAYABLE_ASSET_ID>' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/adcreatives
- Create ad in API:
curl \
-F 'name=My Ad' \
-F 'status=ACTIVE' \
-F 'adset_id=<AD_SET_ID>' \
-F 'creative={"creative_id":"<CREATIVE_ID>"}' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/ads