App Ads

Overview

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, or carousel creatives. Conceptually this allows for the following ads:

Photo Video Carousel

Mobile Install Ad

Mobile Engagement Ad

Desktop Install Ad

Desktop Engagement Ad

Desktop app ad for virtual goods Ad

Desktop app ads for virtual goods are a subset of desktop engagement, you can now 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

In order to create an app ad, the app developer must complete the steps in this tutorial.

Additionally, the advertiser must have a 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, or CONVERSIONS.
  • Ad set promoted object must be set
  • Targeting
  • For mobile app ads, we require the use of the mobile targeting spec user_os field. The placement should have a device_platforms field with value of ['mobile'] and highly recommend the use of the spec's other fields to target mobile devices on Facebook. Optionally, you can specify publisher_platforms if you only want certain platforms.
  • For canvas app ads, device_platforms must be desktop. Optionally, you can specify facebook_positions if you do not want both Facebook desktop Newsfeed and Right-Hand-Side column.
  • When GET_OFFER is used for virtual goods, the price must be discounted. Please 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_NOW
BOOK_TRAVEL
LEARN_MORE
SIGN_UP
DOWNLOAD
INSTALL_MOBILE_APP
USE_MOBILE_APP
WATCH_VIDEO
WATCH_MORE
OPEN_LINK
Call 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_NOW
GET_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

  • Only certain values are required

value.link

refers to the App Store, Google Play Store, or Facebook Canvas App URL, e.g. https://itunes.apple.com/us/app/facebook/id284882215

yes

value.app_link

To define the deep link destination only for mobile apps, e.g. 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:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;

$link_data = new AdCreativeLinkData();
$link_data->setData(array(
  AdCreativeLinkDataFields::MESSAGE => 'try it out',
  AdCreativeLinkDataFields::LINK => '<APP_STORE_URL>',
  AdCreativeLinkDataFields::IMAGE_HASH => '<IMAGE_HASH>',
  AdCreativeLinkDataFields::CALL_TO_ACTION => array(
    'type' => 'INSTALL_MOBILE_APP',
    'value' => array(
      'link' => '<APP_STORE_URL>',
    ),
  ),
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => $link_data,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec


link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'try it out'
link_data[AdCreativeLinkData.Field.link] = '<APP_STORE_URL>'
link_data[AdCreativeLinkData.Field.caption] = 'My caption'
link_data[AdCreativeLinkData.Field.image_hash] = '<IMAGE_HASH>'

call_to_action = {
    'type': 'INSTALL_MOBILE_APP',
    'value': {
        'link': '<APP_STORE_URL>',
    },
}

link_data[AdCreativeLinkData.Field.call_to_action] = call_to_action

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'Sample Creative'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()
print(creative)
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldLinkData(
        new AdCreativeLinkData()
          .setFieldCallToAction(
            new AdCreativeLinkDataCallToAction()
              .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_INSTALL_MOBILE_APP)
              .setFieldValue(
                new AdCreativeLinkDataCallToActionValue()
                  .setFieldLink(<APP_STORE_URL>)
                  .setFieldLinkCaption("Facebook")
              )
          )
          .setFieldCaption("My caption")
          .setFieldImageHash(<IMAGE_HASH>)
          .setFieldLink(<APP_STORE_URL>)
          .setFieldMessage("try it out")
      )
      .setFieldPageId(<PAGE_ID>)
  )
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Sample Creative' \
  -F 'object_story_spec={ 
    "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" 
    }, 
    "page_id": "<PAGE_ID>" 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/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.

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':... }}}

Inline

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataChildAttachmentFields;

$child_attachments = array();

for ($i = 0; $i <= 3; $i++) {
  $child_attachments[] = array(
    AdCreativeLinkDataChildAttachmentFields::LINK => '<APP_STORE_URL>',
    AdCreativeLinkDataChildAttachmentFields::IMAGE_HASH => '<IMAGE_HASH>',
    AdCreativeLinkDataChildAttachmentFields::CALL_TO_ACTION => array(
      'type' => 'USE_MOBILE_APP',
      'value' => array(
        'app_link' => '<DEEP_LINK_I>',
        'link_title' => '<LINK_TITLE_I>',
      ),
    ),
  );
}

$object_story_spec = array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::LINK_DATA => array(
    AdCreativeLinkDataFields::MESSAGE => 'My description',
    AdCreativeLinkDataFields::LINK => '<APP_STORE_URL>',
    AdCreativeLinkDataFields::CAPTION => 'WWW.ITUNES.COM',
    AdCreativeLinkDataFields::CHILD_ATTACHMENTS => $child_attachments,
    AdCreativeLinkDataFields::MULTI_SHARE_OPTIMIZED => true,
  ),
);

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');
$creative->setData(array(
  AdCreativeFields::NAME => 'Carousel app ad',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativelinkdata import AdCreativeLinkData
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativelinkdatachildattachment \
    import AdCreativeLinkDataChildAttachment

child_attachments = list()
for i in range(3):
    child_attachment = AdCreativeLinkDataChildAttachment()
    child_attachment[AdCreativeLinkDataChildAttachment.Field.link] = \
        '<APP_STORE_URL>'
    child_attachment[AdCreativeLinkDataChildAttachment.Field.image_hash] = \
        '<IMAGE_HASH>'
    child_attachment[
        AdCreativeLinkDataChildAttachment.Field.call_to_action
    ] = {
        'type': 'USE_MOBILE_APP',
        'value': {
            'app_link': '<DEEP_LINK_I>',
            'link_title': '<LINK_TITLE_I>',
        },
    }
    child_attachments.append(child_attachment)

link_data = AdCreativeLinkData()
link_data[AdCreativeLinkData.Field.message] = 'My description'
link_data[AdCreativeLinkData.Field.link] = '<APP_STORE_URL>'
link_data[AdCreativeLinkData.Field.caption] = 'WWW.ITUNES.COM'
link_data[AdCreativeLinkData.Field.child_attachments] = child_attachments
link_data[AdCreativeLinkData.Field.multi_share_optimized] = True

story = AdCreativeObjectStorySpec()
story[story.Field.page_id] = <PAGE_ID>
story[story.Field.link_data] = link_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'Carousel app ad'
creative[AdCreative.Field.object_story_spec] = story

creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Carousel app ad")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldLinkData(
        new AdCreativeLinkData()
          .setFieldCaption("WWW.ITUNES.COM")
          .setFieldChildAttachments(Arrays.asList(
            new AdCreativeLinkDataChildAttachment()
              .setFieldCallToAction(
                new AdCreativeLinkDataCallToAction()
                  .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_USE_MOBILE_APP)
                  .setFieldValue(
                    new AdCreativeLinkDataCallToActionValue()
                      .setFieldAppLink(<DEEP_LINK_I>)
                      .setFieldLinkTitle("LINK_TITLE_$i")
                  )
              )
              .setFieldImageHash(<IMAGE_HASH>)
              .setFieldLink(<APP_STORE_URL>)
          , 
            new AdCreativeLinkDataChildAttachment()
              .setFieldCallToAction(
                new AdCreativeLinkDataCallToAction()
                  .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_USE_MOBILE_APP)
                  .setFieldValue(
                    new AdCreativeLinkDataCallToActionValue()
                      .setFieldAppLink(<DEEP_LINK_I>)
                      .setFieldLinkTitle("LINK_TITLE_$i")
                  )
              )
              .setFieldImageHash(<IMAGE_HASH>)
              .setFieldLink(<APP_STORE_URL>)
          , 
            new AdCreativeLinkDataChildAttachment()
              .setFieldCallToAction(
                new AdCreativeLinkDataCallToAction()
                  .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_USE_MOBILE_APP)
                  .setFieldValue(
                    new AdCreativeLinkDataCallToActionValue()
                      .setFieldAppLink(<DEEP_LINK_I>)
                      .setFieldLinkTitle("LINK_TITLE_$i")
                  )
              )
              .setFieldImageHash(<IMAGE_HASH>)
              .setFieldLink(<APP_STORE_URL>)
          , 
            new AdCreativeLinkDataChildAttachment()
              .setFieldCallToAction(
                new AdCreativeLinkDataCallToAction()
                  .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_USE_MOBILE_APP)
                  .setFieldValue(
                    new AdCreativeLinkDataCallToActionValue()
                      .setFieldAppLink(<DEEP_LINK_I>)
                      .setFieldLinkTitle("LINK_TITLE_$i")
                  )
              )
              .setFieldImageHash(<IMAGE_HASH>)
              .setFieldLink(<APP_STORE_URL>)
          ))
          .setFieldLink(<APP_STORE_URL>)
          .setFieldMessage("My description")
          .setFieldMultiShareOptimized(true)
      )
      .setFieldPageId(<PAGE_ID>)
  )
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Carousel app ad' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "link_data": { 
      "message": "My description", 
      "link": "<APP_STORE_URL>", 
      "caption": "WWW.ITUNES.COM", 
      "child_attachments": [ 
        { 
          "link": "<APP_STORE_URL>", 
          "image_hash": "<IMAGE_HASH>", 
          "call_to_action": { 
            "type": "USE_MOBILE_APP", 
            "value": {"app_link":"<DEEP_LINK_I>","link_title":"<LINK_TITLE_I>"} 
          } 
        }, 
        { 
          "link": "<APP_STORE_URL>", 
          "image_hash": "<IMAGE_HASH>", 
          "call_to_action": { 
            "type": "USE_MOBILE_APP", 
            "value": {"app_link":"<DEEP_LINK_I>","link_title":"<LINK_TITLE_I>"} 
          } 
        }, 
        { 
          "link": "<APP_STORE_URL>", 
          "image_hash": "<IMAGE_HASH>", 
          "call_to_action": { 
            "type": "USE_MOBILE_APP", 
            "value": {"app_link":"<DEEP_LINK_I>","link_title":"<LINK_TITLE_I>"} 
          } 
        }, 
        { 
          "link": "<APP_STORE_URL>", 
          "image_hash": "<IMAGE_HASH>", 
          "call_to_action": { 
            "type": "USE_MOBILE_APP", 
            "value": {"app_link":"<DEEP_LINK_I>","link_title":"<LINK_TITLE_I>"} 
          } 
        } 
      ], 
      "multi_share_optimized": true 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/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:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeVideoData;
use FacebookAds\Object\Fields\AdCreativeVideoDataFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Fields\AdCreativeFields;

$video_data = new AdCreativeVideoData();
$video_data->setData(array(
  AdCreativeVideoDataFields::LINK_DESCRIPTION => 'try it out',
  AdCreativeVideoDataFields::IMAGE_URL => '<THUMBNAIL_URL>',
  AdCreativeVideoDataFields::VIDEO_ID => <VIDEO_ID>,
  AdCreativeVideoDataFields::CALL_TO_ACTION => array(
    'type' => 'INSTALL_MOBILE_APP',
    'value' => array(
      'link' => '<APP_STORE_URL>',
    ),
  ),
));

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::VIDEO_DATA => $video_data,
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Sample Creative',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec
from facebookads.adobjects.adcreativevideodata \
    import AdCreativeVideoData

video_data = AdCreativeVideoData()
video_data[AdCreativeVideoData.Field.link_description] = 'try it out'
video_data[AdCreativeVideoData.Field.video_id] = <VIDEO_ID>
video_data[AdCreativeVideoData.Field.image_url] = '<THUMBNAIL_URL>'
video_data[AdCreativeVideoData.Field.call_to_action] = {
    'type': 'INSTALL_MOBILE_APP',
    'value': {
        'link': '<APP_STORE_URL>',
    },
}

object_story_spec = AdCreativeObjectStorySpec()
object_story_spec[AdCreativeObjectStorySpec.Field.page_id] = <PAGE_ID>
object_story_spec[AdCreativeObjectStorySpec.Field.video_data] = video_data

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'Sample Creative'
creative[AdCreative.Field.object_story_spec] = object_story_spec
creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Sample Creative")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldPageId(<PAGE_ID>)
      .setFieldVideoData(
        new AdCreativeVideoData()
          .setFieldCallToAction(
            new AdCreativeLinkDataCallToAction()
              .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_INSTALL_MOBILE_APP)
              .setFieldValue(
                new AdCreativeLinkDataCallToActionValue()
                  .setFieldLink(<APP_STORE_URL>)
                  .setFieldLinkTitle("Facebook")
              )
          )
          .setFieldDescription("try it out")
          .setFieldImageUrl(<THUMBNAIL_URL>)
          .setFieldVideoId(<VIDEO_ID>)
      )
  )
  .execute();
String ad_creative_id = adCreative.getId();
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>", 
      "link_description": "try it out", 
      "video_id": "<VIDEO_ID>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/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/{API_VERSION}/{PAGE_ID}/promotable_posts

To retrieve details about your ad creative, refer to the ad creative documentation.

Exclusion of existing mobile app users

For mobile install ads, we encourage you to set up your ads so that existing installers do not see your mobile install ad.

Android

This is done automatically since the app's package name is already included in the link field.

iOS

Please refer to the setup tutorial to learn how to exclude installers from your app by updating your app's .plist file.

Another option to exclude existing installers is to specify exclusion at ad creation time, you can specify your iOS app's URL with the trailing :// or : as appropriate in the below field to exclude existing installers.

"call_to_action": { "type": 'INSTALL_MOBILE_APP', "value": { "app_link": "facebook://" } } If you are using a carousel mobile app ad, you must specify the app_link in each child_attachments to exclude existing installers:

'child_attachments':[ {'call_to_action': {'app_link':'facebook://', ... } ... }, {'call_to_action': {'app_link':'facebook://', ... } ... }, {'call_to_action': {'app_link':'facebook://', ... } ... }, ]

Mobile Measurement

Measuring ad performance only applies for ads with a promoted object containing the app ID. To obtain an app ID, register the app on Facebook.

We recommend that all advertisers use Facebook’s SDK to measure mobile installs. The developer needs to install the latest SDK and set up their app to measure the performance of your mobile ads. For iOS apps, download the FB iOS SDK 3.0 or higher. For Android apps, download the FB Android SDK 3.0.

However, if your client is currently using a third-party to measure installs or would prefer to work with a third-party (i.e., for lifetime value calculation), we have partnered with companies to provide measurement solutions for mobile app install ads. Partners are listed here.

You can confirm that the volume of installs is being correctly reported in the Insights section for your app in the App Dashboard. In addition, in the App Summary Page, there is a time stamp 'Last Mobile Install Reported" for iOS and Android so that you can confirm that an install is being reported (see image below).

Please refer to the stats, report stats, or conversions documentation for retrieving ad related statistics.

To learn how to set up your app to support deep links, refer to the deep link guide. Once your app supports deep links, you can specify it in the ad creative creation for either mobile app install or engagement:

"call_to_action={'type':'LEARN_MORE', 'value':{'link':'https://itunes.apple.com/us/app/facebook/id284882215', 'app_link':'facebook://path/to/page'}}"

If your app supports App Links, you may specify the app link in this field as well, e.g. http://myapp.com/product/12345. Learn more about adding support for App Links on iOS and Android. Before specifying an app link, you should validate that it has been scraped by calling

https://graph.facebook.com/{API_VERSION}/?type=og&amp;scrape=true&amp;id={APP_LINK}

with a manage_pages access token.

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.

Facebook 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/{API_VERSION}/{APP_ID}/insights/application_mobile_app_installs?&access_token={ACCESS_TOKEN}

You can also breakdown stats by specifying an additional URL param, 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/{API_VERSION}/{APP_ID}/insights/application_mobile_app_installs?breakdown=gender_age&amp;access_token={ACCESS_TOKEN}

https://graph.facebook.com/{API_VERSION}/{APP_ID}/insights/application_mobile_app_installs?breakdown=country&amp;access_token={ACCESS_TOKEN}

https://graph.facebook.com/{API_VERSION}/{APP_ID}/insights/application_mobile_app_installs?breakdown=locale&amp;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 page API session to create page post.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'message' => 'Sign up today',
  'picture' => '<IMAGE_URL>',
  'link' => '<LINK>',
  'published' => 1,
  'call_to_action' => array(
    'type' => 'SIGN_UP',
    'value' => array(
      'link' => '<LINK>',
    ),
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/feed',
  RequestInterface::METHOD_POST,
  $params)->getContent();
from facebookads import FacebookAdsApi

params = {
    'massage': 'Sign up today.',
    'picture': '<IMAGE_URL>',
    'link': '<LINK>',
    'published': 1,
    'call_to_action': {
        'type': 'SIGN_UP',
        'value': {
            'link': '<LINK>',
        },
    },
}

data = FacebookAdsApi.get_default_api().\
    call('POST', (<PAGE_ID>, 'feed'), params=params)
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/v2.10/<PAGE_ID>/feed

Step 2. Create the ad creative ({STORY_ID} is in form of '{PAGE_ID}_{POST_ID}')

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::OBJECT_STORY_ID => <STORY_ID>,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.object_story_id] = <POST_ID>

creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setObjectStoryId(object_story_id)
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'object_story_id=<STORY_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adcreatives

Step 3. Use the creative in an ad

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$data = array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData($data);
$ad->create(array(
  'redownload' => 1,
));
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {'creative_id': <CREATIVE_ID>}
ad[Ad.Field.redownload] = True
ad.remote_create(params={
    'status': Ad.Status.paused,
})
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("My Ad")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setRedownload(true)
  .execute();
String ad_id = ad.getId();
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/v2.10/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 page API session to create page post.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'message' => 'Check out this App today. Available on iTunes.',
  'published' => 1,
  'link' => '<APP_STORE_URL>',
  'picture' => '<IMAGE_URL>',
  'call_to_action' => array(
    'type' => 'LEARN_MORE',
    'value' => array(
      'link' => '<APP_STORE_URL>',
      'app_link' => '<APP_DEEP_LINK>',
    ),
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/feed',
  RequestInterface::METHOD_POST,
  $params)->getContent();
from facebookads import FacebookAdsApi

params = {
    'massage': 'Check out this App today. Available on iTunes.',
    'picture': '<IMAGE_URL>',
    'link': '<APP_STORE_URL>',
    'published': 1,
    'call_to_action': {
        'type': 'LEARN_MORE',
        'value': {
            'link': '<APP_STORE_URL>',
            'app_link': '<APP_DEEP_LINK>',
        },
    },
}

path = "/{}/feed".format(<PAGE_ID>)
data = FacebookAdsApi.get_default_api().call('POST', (path,), params=params)
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/v2.10/<PAGE_ID>/feed

Step 2. Create the ad creative

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::OBJECT_STORY_ID => <STORY_ID>,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.object_story_id] = <POST_ID>

creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setObjectStoryId(object_story_id)
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'object_story_id=<STORY_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adcreatives

Step 3. Set the bidding at the ad set, optimizing for clicks, paying for impressions.

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Targeting;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'LifetimeBudgetSet',
  AdsetFields::LIFETIME_BUDGET => 100000,
  AdSetFields::BID_AMOUNT => 500,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::LINK_CLICKS,
  AdSetFields::PROMOTED_OBJECT => array(
      'application_id' => <APP_ID>,
      'object_store_url' => '<APP_STORE_URL>',
  ),
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
    TargetingFields::USER_OS => array(
      'IOS',
    ),
    TargetingFields::PUBLISHER_PLATFORMS => array(
      'facebook',
      'audience_network',

    ),
    TargetingFields::FACEBOOK_POSITIONS => array('feed'),
  )),
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::END_TIME =>
    (new \DateTime("+1 week"))->format(\DateTime::ISO8601),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_PAUSED,
));
import time
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adset import AdSet

ad_account = AdAccount(fbid='act_<AD_ACCOUNT_ID>')

params = {
    AdSet.Field.name: 'LifetimeBudgetSet',
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.lifetime_budget: 10000,
    AdSet.Field.start_time: int(time.time()),
    AdSet.Field.end_time: int(time.time() + 100000),
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.link_clicks,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 500,
    AdSet.Field.promoted_object: {
        'application_id': <APP_ID>,
        'object_store_url': '<APP_STORE_URL>',
    },
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
        'user_os': ['iOS'],
        Targeting.Field.publisher_platforms: ['facebook', 'audience_network'],
        Targeting.Field.facebook_positions: ['feed'],
    },
    AdSet.Field.status: AdSet.Status.active,
}
adset = ad_account.create_ad_set(params=params)
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=2017-09-21T15:41:37+0000' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adsets

Step 4. Use the creative in an ad

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$data = array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData($data);
$ad->create(array(
  'redownload' => 1,
));
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {'creative_id': <CREATIVE_ID>}
ad[Ad.Field.redownload] = True
ad.remote_create(params={
    'status': Ad.Status.paused,
})
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("My Ad")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setRedownload(true)
  .execute();
String ad_id = ad.getId();
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/v2.10/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 page API session to create page post.

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;

$params = array(
  'message' => 'Check out this App today. Available on iTunes.',
  'published' => 1,
  'link' => '<APP_STORE_URL>',
  'picture' => '<IMAGE_URL>',
  'call_to_action' => array(
    'type' => 'LEARN_MORE',
    'value' => array(
      'link' => '<APP_STORE_URL>',
      'app_link' => '<APP_DEEP_LINK>',
    ),
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/feed',
  RequestInterface::METHOD_POST,
  $params)->getContent();
from facebookads import FacebookAdsApi

params = {
    'massage': 'Check out this App today. Available on iTunes.',
    'picture': '<IMAGE_URL>',
    'link': '<APP_STORE_URL>',
    'published': 1,
    'call_to_action': {
        'type': 'LEARN_MORE',
        'value': {
            'link': '<APP_STORE_URL>',
            'app_link': '<APP_DEEP_LINK>',
        },
    },
}

path = "/{}/feed".format(<PAGE_ID>)
data = FacebookAdsApi.get_default_api().call('POST', (path,), params=params)
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/v2.10/<PAGE_ID>/feed

Step 2. Create the ad creative

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::OBJECT_STORY_ID => <STORY_ID>,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.object_story_id] = <POST_ID>

creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setObjectStoryId(object_story_id)
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'object_story_id=<STORY_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/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, please refer to ad set docs for more details.

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Targeting;


$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');
$adset->setData(array(
  AdSetFields::NAME => 'LifetimeBudgetSet',
  AdsetFields::LIFETIME_BUDGET => 100000,
  AdSetFields::BID_AMOUNT => 500,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::OPTIMIZATION_GOAL =>
    AdSetOptimizationGoalValues::OFFSITE_CONVERSIONS,
  AdSetFields::PROMOTED_OBJECT => array(
      'application_id' => <APP_ID>,
      'object_store_url' => '<APP_STORE_URL>',
      'custom_event_type' => 'ADD_TO_CART',
  ),
  AdSetFields::TARGETING => (new Targeting())->setData(array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
    TargetingFields::USER_OS => array(
      'IOS',
    ),
  )),
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::END_TIME =>
    (new \DateTime("+1 week"))->format(\DateTime::ISO8601),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_PAUSED,
));
import time
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adset import AdSet

ad_account = AdAccount(fbid='act_<AD_ACCOUNT_ID>')

params = {
    AdSet.Field.name: 'LifetimeBudgetSet',
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.lifetime_budget: 10000,
    AdSet.Field.start_time: int(time.time()),
    AdSet.Field.end_time: int(time.time() + 100000),
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.offsite_conversions,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 500,
    AdSet.Field.promoted_object: {
        'application_id': <APP_ID>,
        'object_store_url': '<APP_STORE_URL>',
        'custom_event_type': 'ADD_TO_CART',
    },
    AdSet.Field.targeting: {
        'geo_locations': {
            'countries': ['US'],
        },
        'user_os': ['iOS'],
        'publisher_platforms': ['facebook', 'audience_network'],
        'device_platforms': ['mobile'],
    },
    AdSet.Field.status: AdSet.Status.active,
}
adset = ad_account.create_ad_set(params=params)
curl \
  -F 'name=LifetimeBudgetSet' \
  -F 'lifetime_budget=100000' \
  -F 'bid_amount=500' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'optimization_goal=OFFSITE_CONVERSIONS' \
  -F 'promoted_object={ 
    "application_id": "<APP_ID>", 
    "object_store_url": "<APP_STORE_URL>", 
    "custom_event_type": "ADD_TO_CART" 
  }' \
  -F 'targeting={"geo_locations":{"countries":["US"]},"user_os":["IOS"]}' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'end_time=2017-09-21T15:41:37+0000' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adsets

Step 4. Use the creative in an ad

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$data = array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData($data);
$ad->create(array(
  'redownload' => 1,
));
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {'creative_id': <CREATIVE_ID>}
ad[Ad.Field.redownload] = True
ad.remote_create(params={
    'status': Ad.Status.paused,
})
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("My Ad")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setRedownload(true)
  .execute();
String ad_id = ad.getId();
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/v2.10/act_<AD_ACCOUNT_ID>/ads

Examples for page post ads

Note that you should use PAGE_ACCESS_TOKEN and page API session to create page post. For video post, domain is "video-graph.facebook.com" instead of "graph.facebook.com".

Create a mobile app install video ad

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$params = array(
  'name' => 'My Video',
  'message' => 'Check out this app!',
  'thumbnail' => '<THUMBNAIL_PATH>',
  'published' => 0,
  'call_to_action' => array(
    'type' => AdCreativeCallToActionTypeValues::INSTALL_MOBILE_APP,
    'value' => array(
      'link' => '<APP_STORE_URL>',
    ),
  ),
);

$request = Api::instance()->prepareRequest(
  '/'.<PAGE_ID>.'/videos',
  RequestInterface::METHOD_POST,
  $params);

$request->setLastLevelDomain('graph-video');
$request->getFileParams()->offsetSet('source', '<VIDEO_PATH>');
$response = Api::instance()->executeRequest($request);

$data = $response->getContent();
from facebookads import FacebookAdsApi

params = {
    'name': 'My Video',
    'massage': 'Check out this app!',
    'thumbnail': '<THUMBNAIL_URL>',
    'published': 0,
    'call_to_action': {
        'type': 'INSTALL_MOBILE_APP',
        'value': {
            'link': '<APP_STORE_URL>',
        },
    },
}

url = 'https://graph-video.facebook.com/' + FacebookAdsApi.API_VERSION
path = "/{}/videos".format(<PAGE_ID>)
files = {'source': open('<VIDEO_PATH>', 'rb')}

data = FacebookAdsApi.get_default_api().call(
    'POST',
    url + path,
    params=params,
    files=files
)
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-video.facebook.com/v2.10/<PAGE_ID>/videos

Create a mobile app video ad with a deep link

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$params = array(
  'name' => 'My Video',
  'message' => 'Check out this app!',
  'thumbnail' => '<THUMBNAIL_PATH>',
  'published' => 0,
  'call_to_action' => array(
    'type' => AdCreativeCallToActionTypeValues::LEARN_MORE,
    'value' => array(
      'link' => '<APP_STORE_URL>',
      'app_link' => '<APP_DEEP_LINK>',
    ),
  ),
);
$request = Api::instance()->prepareRequest(
  '/'.<PAGE_ID>.'/videos',
  RequestInterface::METHOD_POST,
  $params);

$request->setLastLevelDomain('graph-video');
$request->getFileParams()->offsetSet('source', '<VIDEO_PATH>');
$response = Api::instance()->executeRequest($request);

$data = $response->getContent();
from facebookads import FacebookAdsApi

params = {
    'name': 'My Video',
    'massage': 'Check out this app!',
    'thumbnail': '<THUMBNAIL_URL>',
    'published': 0,
    'call_to_action': {
        'type': 'LEARN_MORE',
        'value': {
            'link': '<APP_STORE_URL>',
            'app_link': '<APP_DEEP_LINK>',
        },
    },
}

url = 'https://graph-video.facebook.com/' + FacebookAdsApi.API_VERSION
path = "/{}/videos".format(<PAGE_ID>)
files = {'source': open('<VIDEO_PATH>', 'rb')}

data = FacebookAdsApi.get_default_api().call(
    'POST',
    url + path,
    params=params,
    files=files
)
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-video.facebook.com/v2.10/<PAGE_ID>/videos

Create a desktop app install video ad

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$params = array(
  'name' => 'My Video',
  'message' => 'Check out this app!',
  'thumbnail' => '<THUMBNAIL_PATH>',
  'published' => 0,
  'call_to_action' => array(
    'type' => AdCreativeCallToActionTypeValues::PLAY_GAME,
    'value' => array(
      'link' => '<URL>',
    ),
  ),
);
$request = Api::instance()->prepareRequest(
  '/'.<PAGE_ID>.'/videos',
  RequestInterface::METHOD_POST,
  $params);

$request->setLastLevelDomain('graph-video');
$request->getFileParams()->offsetSet('source', '<VIDEO_PATH>');
$response = Api::instance()->executeRequest($request);

$data = $response->getContent();
from facebookads import FacebookAdsApi

params = {
    'name': 'My Video',
    'massage': 'Check out this app!',
    'thumbnail': '<THUMBNAIL_URL>',
    'published': 0,
    'call_to_action': {
        'type': 'PLAY_GAME',
        'value': {
            'link': '<URL>',
        },
    },
}

url = 'https://graph-video.facebook.com/' + FacebookAdsApi.API_VERSION
path = "/{}/videos".format(<PAGE_ID>)
files = {'source': open('<VIDEO_PATH>', 'rb')}

data = FacebookAdsApi.get_default_api().call(
    'POST',
    '<URL>' + path,
    params=params,
    files=files
)
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-video.facebook.com/v2.10/<PAGE_ID>/videos

Create a desktop app ads for virtual goods image ad

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$params = array(
  'message' => 'Buy coins now!',
  'picture' => '<IMAGE_URL>',
  'link' => '<LINK>',
  'published' => 1,
  'call_to_action' => array(
    'type' => AdCreativeCallToActionTypeValues::BUY_NOW,
    'value' => array(
      'link' => '<LINK>',
      'product_link' => '<PRODUCT_LINK>',
    ),
  ),
);

$data = Api::instance()->call(
  '/'.<PAGE_ID>.'/feed',
  RequestInterface::METHOD_POST,
  $params)->getContent();
from facebookads import FacebookAdsApi

params = {
    'massage': 'Buy coins now!',
    'picture': '<IMAGE_URL>',
    'link': '<LINK>',
    'published': 1,
    'call_to_action': {
        'type': 'BUY_NOW',
        'value': {
            'link': '<LINK>',
            'product_link': '<PRODUCT_LINK>',
        },
    },
}

data = FacebookAdsApi.get_default_api().\
    call('POST', (<PAGE_ID>, 'feed'), params=params)
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/v2.10/<PAGE_ID>/feed

Create a desktop app ads for virtual goods video ad

use FacebookAds\Api;
use FacebookAds\Http\RequestInterface;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$params = array(
  'name' => 'My Video',
  'message' => 'Buy coins now!',
  'thumbnail' => '<THUMBNAIL_PATH>',
  'published' => 0,
  'call_to_action' => array(
    'type' => AdCreativeCallToActionTypeValues::BUY_NOW,
    'value' => array(
      'link' => '<APP_URL>',
      'product_link' => '<PRODUCT_LINK>',
    ),
  ),
);

$request = Api::instance()->prepareRequest(
  '/'.<PAGE_ID>.'/videos',
  RequestInterface::METHOD_POST,
  $params);

$request->setLastLevelDomain('graph-video');
$request->getFileParams()->offsetSet('source', '<VIDEO_PATH>');
$response = Api::instance()->executeRequest($request);

$data = $response->getContent();
from facebookads import FacebookAdsApi

params = {
    'name': 'My Video',
    'massage': 'Buy coins now!',
    'thumbnail': '<THUMBNAIL_URL>',
    'published': 0,
    'call_to_action': {
        'type': 'BUY_NOW',
        'value': {
            'link': '<APP_STORE_URL>',
            'product_link': '<PRODUCT_LINK>',
        },
    },
}

files = {'source': open('<VIDEO_PATH>', 'rb')}

data = FacebookAdsApi.get_default_api().call(
    'POST', (<PAGE_ID>, 'videos'),
    params=params,
    files=files
)
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-video.facebook.com/v2.10/<PAGE_ID>/videos

Dynamic Ads for Mobile App Install

Dynamic Ads can drive people to install your mobile app. This enables you to retarget people with mobile install ads, based user's behavior.

Step 1. Create a campaign for your product catalog

use FacebookAds\Object\Campaign;
use FacebookAds\Object\Fields\CampaignFields;
use FacebookAds\Object\Values\CampaignObjectiveValues;

$campaign = new Campaign(null, 'act_<AD_ACCOUNT_ID>');
$campaign->setData(array(
  CampaignFields::NAME => 'Mobile App Installs Campaign with Dynamic Product Ads',
  CampaignFields::OBJECTIVE => CampaignObjectiveValues::MOBILE_APP_INSTALLS,
  CampaignFields::PROMOTED_OBJECT => array(
    'product_catalog_id' => <PRODUCT_CATALOG_ID>,
  ),
));

$campaign->create(array(
  Campaign::STATUS_PARAM_NAME => Campaign::STATUS_PAUSED,
));
from facebookads.adobjects.campaign import Campaign

campaign = Campaign(parent_id='act_<AD_ACCOUNT_ID>')
campaign[Campaign.Field.name] = 'Mobile App Installs Campaign' \
    ' with Dynamic Product Ads'
campaign[Campaign.Field.objective] = Campaign.Objective.app_installs
campaign[Campaign.Field.promoted_object] = {
    'product_catalog_id': <PRODUCT_CATALOG_ID>,
}

campaign.remote_create(params={
    'status': Campaign.Status.paused,
})
Campaign campaign = new AdAccount(act_<AD_ACCOUNT_ID>, context).createCampaign()
  .setName("Mobile App Installs Campaign with Dynamic Product Ads")
  .setObjective(Campaign.EnumObjective.VALUE_MOBILE_APP_INSTALLS)
  .setPromotedObject("{\"product_catalog_id\":\"" + <PRODUCT_CATALOG_ID> + "\"}")
  .setStatus(Campaign.EnumStatus.VALUE_PAUSED)
  .execute();
String campaign_id = campaign.getId();
curl \
  -F 'name=Mobile App Installs Campaign with Dynamic Product Ads' \
  -F 'objective=MOBILE_APP_INSTALLS' \
  -F 'promoted_object={"product_catalog_id":"<PRODUCT_CATALOG_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.8/act_<AD_ACCOUNT_ID>/campaigns

Step 2. Create an ad set for a specific product set under the above product catalog

use FacebookAds\Object\AdSet;
use FacebookAds\Object\Fields\AdSetFields;
use FacebookAds\Object\Fields\TargetingFields;
use FacebookAds\Object\Values\AdSetBillingEventValues;
use FacebookAds\Object\Values\AdSetOptimizationGoalValues;

$adset = new AdSet(null, 'act_<AD_ACCOUNT_ID>');

$adset->setData(array(
  AdSetFields::NAME => 'Mobile App Installs Ad Set with Dynamic Product Ads',
  AdSetFields::BID_AMOUNT => 3000,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::OPTIMIZATION_GOAL => AdSetOptimizationGoalValues::APP_INSTALLS,
  AdSetFields::DAILY_BUDGET => 15000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
    TargetingFields::PUBLISHER_PLATFORMS => array(
      'facebook',
      'audience_network',
    ),
    TargetingFields::DEVICE_PLATFORMS => array('mobile'),
    TargetingFields::USER_OS => array(
      'IOS',
    ),
    TargetingFields::DYNAMIC_AUDIENCE_IDS => array(<PRODUCT_AUDIENCE_ID>),
  ),
  AdSetFields::PROMOTED_OBJECT => array(
    'product_set_id' => <PRODUCT_SET_ID>,
    'application_id' => <APP_ID>,
    'object_store_url' => '<APP_STORE_URL>',
  ),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_PAUSED,
));
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.adset import AdSet
from facebookads.adobjects.targeting import Targeting

ad_account = AdAccount(fbid='act_<AD_ACCOUNT_ID>')

params = {
    AdSet.Field.name: 'Mobile App Installs Ad Set with Dynamic Product Ads',
    AdSet.Field.promoted_object: {
        'product_set_id': product_set_id,
        'application_id': <APP_ID>,
        'object_store_url': '<APP_STORE_URL>',
    },
    AdSet.Field.campaign_id: <CAMPAIGN_ID>,
    AdSet.Field.daily_budget: 15000,
    AdSet.Field.optimization_goal: AdSet.OptimizationGoal.app_installs,
    AdSet.Field.billing_event: AdSet.BillingEvent.impressions,
    AdSet.Field.bid_amount: 3000,
    AdSet.Field.targeting: {
        Targeting.Field.geo_locations: {
            'countries': ['US'],
        },
        Targeting.Field.publisher_platforms: ['facebook', 'audience_network'],
        Targeting.Field.device_platforms: ['mobile'],
        Targeting.Field.user_os: [
            'IOS',
        ],
        Targeting.Field.dynamic_audience_ids: [
            <PRODUCT_AUDIENCE_ID>,
        ],
    },
    AdSet.Field.status: AdSet.Status.active,
}
adset = ad_account.create_ad_set(params=params)
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/v2.8/act_<AD_ACCOUNT_ID>/adsets

Step 3. Create the Dynamic Ad creative by using template

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\AdCreativeLinkData;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\Values\AdCreativeCallToActionTypeValues;

$object_story_spec = new AdCreativeObjectStorySpec();
$object_story_spec->setData(array(
  AdCreativeObjectStorySpecFields::PAGE_ID => <PAGE_ID>,
  AdCreativeObjectStorySpecFields::TEMPLATE_DATA =>
    (new AdCreativeLinkData())->setData(array(
      AdCreativeLinkDataFields::CALL_TO_ACTION => array(
        'type' => AdCreativeCallToActionTypeValues::INSTALL_MOBILE_APP,
        'value' => array(
          'link' => '<APP_STORE_URL>',
          'link_title' => 'Link title',
        ),
      ),
      AdCreativeLinkDataFields::MESSAGE => 'Test {{product.name | titleize}}',
      AdCreativeLinkDataFields::LINK => '<APP_STORE_URL>',
      AdCreativeLinkDataFields::NAME => 'Headline {{product.price}}',
      AdCreativeLinkDataFields::DESCRIPTION =>
        'Description {{product.description}}',
    )),
));

$creative = new AdCreative(null, 'act_<AD_ACCOUNT_ID>');

$creative->setData(array(
  AdCreativeFields::NAME => 'Dynamic Ad Template Creative Sample',
  AdCreativeFields::OBJECT_STORY_SPEC => $object_story_spec,
  AdCreativeFields::PRODUCT_SET_ID => <PRODUCT_SET_ID>,
));

$creative->create();
from facebookads.adobjects.adcreative import AdCreative
from facebookads.adobjects.adcreativeobjectstoryspec \
    import AdCreativeObjectStorySpec

story = AdCreativeObjectStorySpec()
story[story.Field.page_id] = <PAGE_ID>
story[story.Field.template_data] = {
    'call_to_action': {
        'type': 'INSTALL_MOBILE_APP',
        'value': {
            'link': '<APP_STORE_URL>',
            'link_title': 'Link title',
        },
    },
    'message': 'Test {{product.name | titleize}}',
    'link': '<APP_STORE_URL>',
    'name': 'Headline {{product.price}}',
    'description': 'Description {{product.description}}',
}

creative = AdCreative(parent_id='act_<AD_ACCOUNT_ID>')
creative[AdCreative.Field.name] = 'Dynamic Ad Template Creative Sample'
creative[AdCreative.Field.object_story_spec] = story
creative[AdCreative.Field.product_set_id] = <PRODUCT_SET_ID>
creative.remote_create()
AdCreative adCreative = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAdCreative()
  .setName("Dynamic Ad Template Creative Sample")
  .setObjectStorySpec(
    new AdCreativeObjectStorySpec()
      .setFieldPageId(<PAGE_ID>)
      .setFieldTemplateData(
        new AdCreativeLinkData()
          .setFieldCallToAction(
            new AdCreativeLinkDataCallToAction()
              .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_INSTALL_MOBILE_APP)
              .setFieldValue(
                new AdCreativeLinkDataCallToActionValue()
                  .setFieldLink(<APP_STORE_URL>)
                  .setFieldLinkTitle("Link title")
              )
          )
          .setFieldDescription("Description {{product.description}}")
          .setFieldLink(<APP_STORE_URL>)
          .setFieldMessage("Test {{product.name | titleize}}")
          .setFieldName("Headline {{product.price}}")
      )
  )
  .setProductSetId(<PRODUCT_SET_ID>)
  .execute();
String ad_creative_id = adCreative.getId();
curl \
  -F 'name=Dynamic Ad Template Creative Sample' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "template_data": { 
      "call_to_action": { 
        "type": "INSTALL_MOBILE_APP", 
        "value": {"link":"<APP_STORE_URL>","link_title":"Link title"} 
      }, 
      "description": "Description {{product.description}}", 
      "link": "<APP_STORE_URL>", 
      "message": "Test {{product.name | titleize}}", 
      "name": "Headline {{product.price}}" 
    } 
  }' \
  -F 'product_set_id=<PRODUCT_SET_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.10/act_<AD_ACCOUNT_ID>/adcreatives

Step 4. Use the above Ad creative in an Ad

use FacebookAds\Object\Ad;
use FacebookAds\Object\Fields\AdFields;

$data = array(
  AdFields::NAME => 'My Ad',
  AdFields::ADSET_ID => <AD_SET_ID>,
  AdFields::CREATIVE => array(
    'creative_id' => <CREATIVE_ID>,
  ),
);

$ad = new Ad(null, 'act_<AD_ACCOUNT_ID>');
$ad->setData($data);
$ad->create(array(
  'redownload' => 1,
));
from facebookads.adobjects.ad import Ad

ad = Ad(parent_id='act_<AD_ACCOUNT_ID>')
ad[Ad.Field.name] = 'My Ad'
ad[Ad.Field.adset_id] = <AD_SET_ID>
ad[Ad.Field.creative] = {'creative_id': <CREATIVE_ID>}
ad[Ad.Field.redownload] = True
ad.remote_create(params={
    'status': Ad.Status.paused,
})
Ad ad = new AdAccount(act_<AD_ACCOUNT_ID>, context).createAd()
  .setName("My Ad")
  .setAdsetId(<AD_SET_ID>)
  .setCreative(
    new AdCreative()
      .setFieldId(<CREATIVE_ID>)
  )
  .setRedownload(true)
  .execute();
String ad_id = ad.getId();
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/v2.10/act_<AD_ACCOUNT_ID>/ads

App Event Optimization

Optimize Mobile App Install campaigns for AppEvent by specifying OFFSITE_CONVERSIONS as an option. Ads will be delivered to people most likely take actions such as purchase products in your app after app install:

  • Optimization Goal: Set to OFFSITE_CONVERSIONS
  • Billing Event: Set to IMPRESSIONS
  • Promoted Object: Set custom_event_type in the promoted object to the app event you want to optimize. You can only optimize on one app event at a time.
  • Bid Amount: Set bid amount to value you want to pay for a user to install AND perform the app event one or more times.

Possible values for the custom_app_event in the Promoted Object are:

  • COMPLETE_REGISTRATION
  • CONTENT_VIEW
  • SEARCH
  • RATE
  • TUTORIAL_COMPLETION
  • ADD_TO_CART
  • ADD_TO_WISHLIST
  • INITIATED_CHECKOUT
  • ADD_PAYMENT_INFO
  • PURCHASE
  • LEAD
  • LEVEL_ACHIEVED
  • ACHIEVEMENT_UNLOCKED
  • SPENT_CREDITS

Example cURL:

curl
-F "name=App Event Optimization Example" 
-F "status=PAUSED" 
-F "optimization_goal=OFFSITE_CONVERSIONS"
-F "billing_event=IMPRESSIONS" 
-F "promoted_object={'application_id': {app_id}, 'object_store_url': '{appstore_url}', 'custom_event_type': 'PURCHASE'}"
-F "bid_amount=100" 
-F "daily_budget=300" 
-F "campaign_id={campaign_id}" 
-F "targeting={'geo_locations':{'countries':['US','GB']}, 'page_types':['mobilefeed'], 'user_os':['ios']}" 
-F "access_token={access_token}" "https://graph.facebook.com/v2.7/act_{act_id}/adset

Value Optimization

This feature is available on a limited basis to white-listed partners and advertisers. Contact your Facebook representative if you want to use value optimization.

Mobile App Install campaigns can also be optimized for purchase value. To use value optimization, ensure your mobile app SDK implementation is sending purchase events and their values. See the App Events pages for additional detail.

  • Optimization Goal: Set to VALUE
  • Billing Event: Set to IMPRESSIONS
  • Promoted Object: Set custom_event_type to PURCHASE
  • Bid Amount: Set is_autobid to true

Example:

curl
-F "name=App Event Optimization Example" 
-F "status=PAUSED" 
-F "optimization_goal=VALUE"
-F "billing_event=IMPRESSIONS" 
-F "promoted_object={'application_id': {app_id}, 'object_store_url': '{appstore_url}', 'custom_event_type': 'PURCHASE'}"
-F "is_autobid=true" 
-F "daily_budget=300" 
-F "campaign_id={campaign_id}" 
-F "targeting={'geo_locations':{'countries':['US','GB']}, 'page_types':['mobilefeed'], 'user_os':['ios']}" 
-F "access_token={access_token}" "https://graph.facebook.com/v2.7/act_{act_id}/adset

Related docs: