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, carousel, or Playable creatives. See Ads Help Center, Specifications for Playable Ads.

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 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

  • To create an app ad, the app developer must complete the steps in this tutorial.
  • 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:

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/v3.2/act_<AD_ACCOUNT_ID>/adcreatives
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdCreative = bizSdk.AdCreative; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Sample Creative', 'object_story_spec' : {'page_id':'<pageID>','link_data':{'call_to_action':{'type':'INSTALL_MOBILE_APP','value':{'link':'<appLink>'}},'image_hash':'<imageHash>','link':'<appLink>','message':'Try it out'}}, }; const adcreatives = (new AdAccount(id)).createAdCreative( fields, params ); logApiCallResult('adcreatives api call complete.', adcreatives);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdCreative; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Sample Creative', 'object_story_spec' => array('page_id' => '<pageID>','link_data' => array('call_to_action' => array('type' => 'INSTALL_MOBILE_APP','value' => array('link' => '<appLink>')),'image_hash' => '<imageHash>','link' => '<appLink>','message' => 'Try it out')), ); echo json_encode((new AdAccount($id))->createAdCreative( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adcreative import AdCreative from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Sample Creative', 'object_story_spec': {'page_id':'<pageID>','link_data':{'call_to_action':{'type':'INSTALL_MOBILE_APP','value':{'link':'<appLink>'}},'image_hash':'<imageHash>','link':'<appLink>','message':'Try it out'}}, } print AdAccount(id).create_ad_creative( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(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(\"<appLink>\") ) ) .setFieldImageHash(\"<imageHash>\") .setFieldLink(\"<appLink>\") .setFieldMessage(\"Try it out\") ) .setFieldPageId(\"<pageID>\") ) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adcreatives = ad_account.adcreatives.create({ name: 'Sample Creative', object_story_spec: {'page_id':'<pageID>','link_data':{'call_to_action':{'type':'INSTALL_MOBILE_APP','value':{'link':'<appLink>'}},'image_hash':'<imageHash>','link':'<appLink>','message':'Try it out'}}, })

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

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.11/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::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.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>',
        'link_title': 'Facebook',
    },
}

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>)
              )
          )
          .setFieldLinkDescription("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>", 
      "video_id": "<VIDEO_ID>" 
    } 
  }' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/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.

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.11/<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/v3.2/act_<AD_ACCOUNT_ID>/adcreatives
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdCreative = bizSdk.AdCreative; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'object_story_id' : '<pageID>_<postID>', }; const adcreatives = (new AdAccount(id)).createAdCreative( fields, params ); logApiCallResult('adcreatives api call complete.', adcreatives);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdCreative; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'object_story_id' => '<pageID>_<postID>', ); echo json_encode((new AdAccount($id))->createAdCreative( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adcreative import AdCreative from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'object_story_id': '<pageID>_<postID>', } print AdAccount(id).create_ad_creative( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdCreative() .setObjectStoryId(\"<pageID>_<postID>\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adcreatives = ad_account.adcreatives.create({ object_story_id: '<pageID>_<postID>', })

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.11/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.11/<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/v3.2/act_<AD_ACCOUNT_ID>/adcreatives
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdCreative = bizSdk.AdCreative; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'object_story_id' : '<pageID>_<postID>', }; const adcreatives = (new AdAccount(id)).createAdCreative( fields, params ); logApiCallResult('adcreatives api call complete.', adcreatives);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdCreative; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'object_story_id' => '<pageID>_<postID>', ); echo json_encode((new AdAccount($id))->createAdCreative( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adcreative import AdCreative from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'object_story_id': '<pageID>_<postID>', } print AdAccount(id).create_ad_creative( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdCreative() .setObjectStoryId(\"<pageID>_<postID>\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adcreatives = ad_account.adcreatives.create({ object_story_id: '<pageID>_<postID>', })

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.adset import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    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.remote_create(params={
    'status': AdSet.Status.paused,
})
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/v2.11/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.11/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.11/<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/v3.2/act_<AD_ACCOUNT_ID>/adcreatives
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdCreative = bizSdk.AdCreative; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'object_story_id' : '<pageID>_<postID>', }; const adcreatives = (new AdAccount(id)).createAdCreative( fields, params ); logApiCallResult('adcreatives api call complete.', adcreatives);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdCreative; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'object_story_id' => '<pageID>_<postID>', ); echo json_encode((new AdAccount($id))->createAdCreative( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adcreative import AdCreative from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'object_story_id': '<pageID>_<postID>', } print AdAccount(id).create_ad_creative( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdCreative() .setObjectStoryId(\"<pageID>_<postID>\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adcreatives = ad_account.adcreatives.create({ object_story_id: '<pageID>_<postID>', })

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.adset import AdSet

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    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'],
    },
})

adset.remote_create(params={
    'status': AdSet.Status.paused,
})
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=2018-02-06T04:45:30+0000' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/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.11/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.11/<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.11/<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.11/<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.11/<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.11/<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

curl -X POST \ -F 'name="App Installs Campaign with Dynamic Product Ads"' \ -F 'objective="APP_INSTALLS"' \ -F 'status="PAUSED"' \ -F 'access_token=<ACCESS_TOKEN>' \ https://graph.facebook.com/v3.2/act_<AD_ACCOUNT_ID>/campaigns
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const Campaign = bizSdk.Campaign; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'App Installs Campaign with Dynamic Product Ads', 'objective' : 'APP_INSTALLS', 'status' : 'PAUSED', }; const campaigns = (new AdAccount(id)).createCampaign( fields, params ); logApiCallResult('campaigns api call complete.', campaigns);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\Campaign; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'App Installs Campaign with Dynamic Product Ads', 'objective' => 'APP_INSTALLS', 'status' => 'PAUSED', ); echo json_encode((new AdAccount($id))->createCampaign( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.campaign import Campaign from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'App Installs Campaign with Dynamic Product Ads', 'objective': 'APP_INSTALLS', 'status': 'PAUSED', } print AdAccount(id).create_campaign( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createCampaign() .setName(\"App Installs Campaign with Dynamic Product Ads\") .setObjective(Campaign.EnumObjective.VALUE_APP_INSTALLS) .setStatus(Campaign.EnumStatus.VALUE_PAUSED) .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) campaigns = ad_account.campaigns.create({ name: 'App Installs Campaign with Dynamic Product Ads', objective: 'APP_INSTALLS', status: 'PAUSED', })

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.adset import AdSet
from facebookads.adobjects.targeting import Targeting

adset = AdSet(parent_id='act_<AD_ACCOUNT_ID>')
adset.update({
    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.remote_create(params={
    'status': AdSet.Status.paused,
})
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

curl -X POST \ -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": "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/v3.2/act_<AD_ACCOUNT_ID>/adcreatives
'use strict'; const bizSdk = require('facebook-nodejs-business-sdk'); const AdAccount = bizSdk.AdAccount; const AdCreative = bizSdk.AdCreative; const access_token = '<ACCESS_TOKEN>'; const app_secret = '<APP_SECRET>'; const app_id = '<APP_ID>'; const id = '<ID>'; const api = bizSdk.FacebookAdsApi.init(access_token); const showDebugingInfo = true; // Setting this to true shows more debugging info. if (showDebugingInfo) { api.setDebug(true); } const logApiCallResult = (apiCallName, data) => { console.log(apiCallName); if (showDebugingInfo) { console.log('Data:' + JSON.stringify(data)); } }; let fields, params; fields = [ ]; params = { 'name' : 'Dynamic Ad Template Creative Sample', 'object_story_spec' : {'page_id':'<pageID>','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}}'}}, 'product_set_id' : '<productSetID>', }; const adcreatives = (new AdAccount(id)).createAdCreative( fields, params ); logApiCallResult('adcreatives api call complete.', adcreatives);
require __DIR__ . '/vendor/autoload.php'; use FacebookAds\Object\AdAccount; use FacebookAds\Object\AdCreative; use FacebookAds\Api; use FacebookAds\Logger\CurlLogger; $access_token = '<ACCESS_TOKEN>'; $app_secret = '<APP_SECRET>'; $app_id = '<APP_ID>'; $id = '<ID>'; $api = Api::init($app_id, $app_secret, $access_token); $api->setLogger(new CurlLogger()); $fields = array( ); $params = array( 'name' => 'Dynamic Ad Template Creative Sample', 'object_story_spec' => array('page_id' => '<pageID>','template_data' => array('call_to_action' => array('type' => 'INSTALL_MOBILE_APP','value' => array('link' => 'http://www.example.com/appstoreurl')),'message' => 'Test array(array(product.name | titleize))','link' => 'http://www.example.com/appstoreurl','name' => 'Headline array(array(product.price))','description' => 'Description array(array(product.description))')), 'product_set_id' => '<productSetID>', ); echo json_encode((new AdAccount($id))->createAdCreative( $fields, $params )->exportAllData(), JSON_PRETTY_PRINT);
from facebook_business.adobjects.adaccount import AdAccount from facebook_business.adobjects.adcreative import AdCreative from facebook_business.api import FacebookAdsApi access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAdsApi.init(access_token=access_token) fields = [ ] params = { 'name': 'Dynamic Ad Template Creative Sample', 'object_story_spec': {'page_id':'<pageID>','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}}'}}, 'product_set_id': '<productSetID>', } print AdAccount(id).create_ad_creative( fields=fields, params=params, )
import com.facebook.ads.sdk.*; import java.io.File; import java.util.Arrays; public class SAMPLE_CODE_EXAMPLE { public static void main (String args[]) throws APIException { String access_token = \"<ACCESS_TOKEN>\"; String app_secret = \"<APP_SECRET>\"; String app_id = \"<APP_ID>\"; String id = \"<ID>\"; APIContext context = new APIContext(access_token).enableDebug(true); new AdAccount(id, context).createAdCreative() .setName(\"Dynamic Ad Template Creative Sample\") .setObjectStorySpec( new AdCreativeObjectStorySpec() .setFieldPageId(\"<pageID>\") .setFieldTemplateData( new AdCreativeLinkData() .setFieldCallToAction( new AdCreativeLinkDataCallToAction() .setFieldType(AdCreativeLinkDataCallToAction.EnumType.VALUE_INSTALL_MOBILE_APP) .setFieldValue( new AdCreativeLinkDataCallToActionValue() .setFieldLink(\"http://www.example.com/appstoreurl\") ) ) .setFieldDescription(\"Description {{product.description}}\") .setFieldLink(\"http://www.example.com/appstoreurl\") .setFieldMessage(\"Test {{product.name | titleize}}\") .setFieldName(\"Headline {{product.price}}\") ) ) .setProductSetId(\"<productSetID>\") .execute(); } }
require 'facebook_ads' access_token = '<ACCESS_TOKEN>' app_secret = '<APP_SECRET>' app_id = '<APP_ID>' id = '<ID>' FacebookAds.configure do |config| config.access_token = access_token config.app_secret = app_secret end ad_account = FacebookAds::AdAccount.get(id) adcreatives = ad_account.adcreatives.create({ name: 'Dynamic Ad Template Creative Sample', object_story_spec: {'page_id':'<pageID>','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}}'}}, product_set_id: '<productSetID>', })

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.11/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/<API_VERSION>/act_<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 machine
  • access_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 Facebook 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 Facebook app ID and asset ID meta tag in the playable HTML file. This helps Facebook 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 News Feed and Audience Network Rewarded Video only Note: Playables in Audience Network Rewarded Video placement is available on a limited basis. Please contact your Facebook representative 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/<API_VERSION>/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/<API_VERSION>/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/<API_VERSION>/act_{act_id}/adset

Value Optimization

This feature is available on a limited basis to whitelisted 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
  • Attribution Window: 7-day or 1-day

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 "attribution_spec=[{'event_type': 'CLICK_THROUGH', 'window_days':'1'}]"
-F "targeting={'geo_locations':{'countries':['US','GB']}, 'publisher_platforms':['facebook'], 'device_platforms': ['mobile'], 'facebook_positions': ['feed'], 'user_os':['ios']}" 
-F "access_token={access_token}" "https://graph.facebook.com/<API_VERSION>/act_{act_id}/adset

Related docs: