Creative

Carousel Dynamic Ad Template

With Dynamic Product Ads, advertisers can create a product catalog and set up a creative template that automatically gets product information from the catalog:

curl -X POST \
 -F 'name=Dynamic Ad Template Creative Sample' \
 -F 'object_story_spec={ \
       "page_id": <PAGE_ID>, \
       "template_data": { \
         "message": "Test {{product.name | titleize}}", \
         "link": "<YOUR_LINK_URL>", \
         "name": "Headline {{product.price}}", \
         "description": "Description {{product.description}}", \
         "max_product_count": 3 \
       } \
     }' \
 -F 'product_set_id=<PRODUCT_SET_ID>' \
 -F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adcreatives

Relevance Score

Advertisers can use Facebook's Relevance score to see how closely connected their creative is for a target market. After Facebook serves your ad more than 500 times it receives a daily relevance score from 1–10, where ten means we estimate your ad is highly relevant and one means we estimate it’s not very relevant.

To get the relevance score for an ad:

curl -G \
-d 'date_preset=last_7_days' \
-d 'level=ad' \
-d 'fields=["impressions","relevance_score"]' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

An example result would look like this:

{
 "data": [
   {
     "impressions": "29371", 
     "relevance_score": {
       "score": 4, 
       "positive_feedback": "LOW", 
       "negative_feedback": "LOW", 
       "status": "OK" }, 
       "date_start": "2015-10-08", 
       "date_stop": "2015-10-14" },
...
}

Targeting

To avoid audience overlap in you acquisition campaigns when you are trying to use lookalikes from your most valuable custom audiences, you can use the tiered lookalike targeting strategy.

First you can use the following SDK calls to create tiered lookalike audiences from the seed custom audience in the given country:

for tier in range(1, tiers + 1):
  lookalike = CustomAudience(parent_id=accountid)
  lookalike[LookalikeAudience.Field.name] = \
    ‘{0} LAL {1}’.format(name, tier)
  lookalike[LookalikeAudience.Field.origin_audience_id] = seed_id
  lookalike[LookalikeAudience.Field.lookalike_spec] = {
    ‘ratio’: ‘{:.2f}’.format(tier / 100.0),
    LookalikeAudience.Field.LookalikeSpec.country: country,
  }
  lookalike.remote_create()

Then in the targeting setting in the ad sets, you can take the lookalike audience and exclude the one from the previous tier like this:

for tier in range(1, tiers + 1):
  ad_set = AdSet(parent_id=accountid)
  ad_set[AdSet.Field.bid_info] = tiered_bidinfos[tier - 1]
  audience = tiered_lookalikes[tier - 1]
  exclude_audience = None
  if tier != 1:
    exclude_audience = tiered_lookalikes[tier - 2]
  targeting = {
    TargetingSpecsField.custom_audiences: [{
      ‘id’: audience[CustomAudience.Field.id],
      ‘name’: audience[CustomAudience.Field.name],
    }]
  }
  if exclude_audience:
    targeting[TargetingSpecsField.excluded_custom_audiences] = [{
      ‘id’: exclude_audience[CustomAudience.Field.id],
      ‘name’: exclude_audience[CustomAudience.Field.name],
    }]
  ad_set[AdSet.Field.targeting] = targeting
  ad_set.remote_create()

Optimization

To read the Facebook pixel stats and see the number of fires for each event type, you should send the following request:

curl -F \
-d 'access_token=_____' \
-d 'aggregation=event>' \
'https://graph.facebook.com/<API_VERSION>/<PIXEL_ID>/stats'

To read insights based upon your campaign, you should use the following request:

curl -G \
-d 'fields=actions' \
-d 'access_token=<ACCESS_TOKEN>' \
'https://graph.facebook.com/<API_VERSION>/<CAMPAIGN_ID>/insights'

Measurement

Tracking Facebook ad conversion on mobile apps (S2S)

Retrieve the attribution id from Android device:

public static final Uri ATTRIBUTION_ID_CONTENT_URI = Uri.parse("content://com.facebook.katana.provider.AttributionIdProvider");

public static final String ATTRIBUTION_ID_COLUMN_NAME = "aid";

public static String getAttributionId(ContentResolver contentResolver) {
        String [] projection = {ATTRIBUTION_ID_COLUMN_NAME};
        Cursor c = contentResolver.query(ATTRIBUTION_ID_CONTENT_URI, projection, null, null, null);
        if (c == null || !c.moveToFirst()) {
            return null;
        }
        String attributionId = c.getString(c.getColumnIndex(ATTRIBUTION_ID_COLUMN_NAME));
        c.close();
        return attributionId;
    }

Retrieve the attribution id from iOS device:

  (FBAdvertisingTrackingStatus)advertisingTrackingStatus {
    FBAdvertisingTrackingStatus status = AdvertisingTrackingUnspecified;
    Class ASIdentifierManagerClass = [FBDynamicFrameworkLoader loadClass:@"ASIdentifierManager" withFramework:@"AdSupport"];
    if ([ASIdentifierManagerClass class]) {
        ASIdentifierManager *manager = [ASIdentifierManagerClass sharedManager];
        if (manager) {
            status = [manager isAdvertisingTrackingEnabled] ? AdvertisingTrackingAllowed : AdvertisingTrackingDisallowed;
        }
    }
    return status;
}

Send conversion event from server:

curl \
  -F "event=CUSTOM_APP_EVENTS" \
  -F "advertiser_id=<idfa_or_aaid_from_above_call>" \
  -F "advertiser_tracking_enabled=1" \
  -F "application_tracking_enabled=1" \
  -F custom_events="[{\"_eventName\":\"fb_mobile_purchase\",                                                                                                                                                                                                                                                                                                             
                      \"_valueToSum\":55.22,                                                                                                                                                                                                                                                                                                                             
                      \"_appVersion\":\"2.1.1\",                                                                                                                                                                                                                                                                                                                         
                      \"_logTime\":1367017882,                                                                                                                                                                                                                                                                                                                           
                      \"fb_currency\":\"GBP\",                                                                                                                                                                                                                                                                                                                           
                    }]" \
  "https://graph.facebook.com/<API_VERSION>/<APP_ID>/activities"

Tracking Facebook ad conversion on desktop/mobile web

Create pixel:

curl \
  -F 'name=My WCA Pixel' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/adspixels

Get the pixel code:

curl -G \
  -d 'fields=code' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/<PIXEL_ID>

Place the pixel code on Advertiser's website:

<!-- Facebook Pixel Code -->
<script>
!function(f,b,e,v,n,t,s){if(f.fbq)return;n=f.fbq=function(){n.callMethod?
n.callMethod.apply(n,arguments):n.queue.push(arguments)};if(!f._fbq)f._fbq=n;
n.push=n;n.loaded=!0;n.version='2.0';n.queue=[];t=b.createElement(e);t.async=!0;
t.src=v;s=b.getElementsByTagName(e)[0];s.parentNode.insertBefore(t,s)}(window,
document,'script','//connect.facebook.net/en_US/fbevents.js');
// Insert Your Facebook Pixel ID below. 
fbq('init', '<FB_PIXEL_ID>');
fbq('track', 'PageView');
</script>
<!-- Insert Your Facebook Pixel ID below. --> 
<noscript><img height="1" width="1" style="display:none"
src="https://www.facebook.com/tr?id=<FB_PIXEL_ID>&amp;ev=PageView&amp;noscript=1"
/></noscript>
<!-- End Facebook Pixel Code -->

Tracking Facebook ad conversion offline:

curl \
-F 'access_token=<ACCESS_TOKEN>' \
-F 'pixel_id=<PIXEL_ID>' \
-F 'event=<STANDARD_EVENT_NAME>' \
-F 'payload=[ \
  { \
    PHONE_SHA256:"<PHONE_HASH>", \
    EMAIL_SHA256:"<EMAIL_HASH>", \
    custom_data: { \
      value:<VALUE>, \
      currency:"<CURRENCY>" \
    } \
  } \
]' \
https://graph.facebook.com/<API_VERSION>/act_<ACCOUNT_ID>/offlineconversions

Publisher side ad tracking (Atlas)

Impression/Click ping urls:

https://ad.atdmt.com/i/img;p=11252200420187;idfa=;idfa_lat=;aaid=AEBE52E7-03EE-455A-B3C4-E57283966239;aaid_
lat=false;cache=6884795518

https://ad.atdmt.com/c/go;p=11252200420187;ev.a=1;idfa=;idfa_lat=;aaid=AEBE52E7-03EE-455A-B3C4-
E57283966239;aaid_lat=false;cache=6884795518

Place this code on publisher web site:

<script src='https://ad.atdmt.com/i/a.js;p=11077201133989;cache=123?click='></script><noscript><iframe frameborder='0' scrolling='no' marginheight='0' marginwidth='0' height='100' width='300' src='https://ad.atdmt.com/i/a.html;p=11077201133989;cache=?click=' topmargin='0' leftmargin='0' allowtransparency='1'></iframe></noscript>

Call the tracking end point from publisher mobile:

String urls = "https://ad.atdmt.com/i/img;p=11252200420187;idfa=;idfa_lat=;aaid=AEBE52E7-03EE-455A-B3C4-E57283966239;aaid_lat=false;cache=6884795518'"
URL url = new URL(urls);

HttpURLConnection urlc = (HttpURLConnection) url.openConnection();
urlc.setRequestProperty("User-Agent", "Android Application:"+Z.APP_VERSION);
urlc.setRequestProperty("Connection", "close");
urlc.connect();

Tracking conversions on advertiser site (Atlas)

Advertiser side conversion tracking on web:

<script>
  var e = document.createElement("script");
  e.async = true;
  e.src = "https://ad.atdmt.com/m/a.js;m=11077201133223;cache=" + Math.random() +
    "?revenue={revenue}" +
    "&amp;qty={qty}" +
    "&amp;currency_code={currency_code}" +
    "&amp;order_id={order_id}";
  var s = document.getElementsByTagName("script")[0];
  s.parentNode.insertBefore(e, s);
</script>

Advertiser side conversion tracking on mobile:

URL url = new URL(“https://ad.atdmt.com/m/img;m=11077201133223;idfa=;idfa_lat=;aaid={aaid};aaid_lat={aaid_lat};cache=;ua=;client_ip=;timestamp=?revenue={revenue}&amp;event=purchase”);

HttpURLConnection urlc = (HttpURLConnection) url.openConnection();
urlc.setRequestProperty("User-Agent", "Android Application:"+Z.APP_VERSION);
urlc.setRequestProperty("Connection", "close");
urlc.connect();

Reporting

Cross device reporting (Facebook):

curl -G \
  -d 'action_breakdowns=["action_device"]' \
  -d 'breakdowns=["placement","impression_device"]' \
  -d 'date_preset=yesterday' \
  -d 'time_increment=all_days' \
  -d 'fields=impressions,actions,website_ctr,app_custom_event.fb_mobile_purchase' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

Offline conversion reporting (Facebook):

curl -G \
  -d 'action_breakdowns= action_device' \
  -d 'fields=["campaign_name","actions","cost_per_action_type"]
' \
  -d 'breakdowns=["placement","impression_device"]' \
  -d 'date_preset=yesterday' \
  -d 'time_increment=all_days' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/insights

Cross publisher cross device reporting (Atlas):

https://graph.atlassolutions.com/<API_VERSION>/<COMPANY_ID>/reports?
reports=
[{
  "name":"Conversion Report",
  "version":1,
  "description":"",
  "definition":{
    "column_definitions":[
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"advertiser_name",
      "name":"Advertiser Name",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"campaign_name",
      "name":"Campaign Name",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"publihser_name",
      "name":"Publisher Name",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"advertiser_name",
      "name":"Advertiser Name",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"impression_device_type",
      "name":"Impression Device Type",
      "aggregation_usage":"dimension"
    },
    {
      "area":"serving",
      "attribution_model":null,
      "category":"standard",
      "key":"conversion_device_type",
      "name":"Conversion Device Type",
      "aggregation_usage":"dimension"
    },    
    {
      "area":"attribution",
      "attribution_model":"last_touch",
      "category":"standard",
      "key":"impression",
      "name":"Impression",
      "aggregation_usage":"metric"
    },
    {
      "area":"attribution",
      "attribution_model":"last_touch",
      "category":"standard",
      "key":"click",
      "name":"Click",
      "aggregation_usage":"metric"
    }
    ],
    "date_range":{
      "type":"relative",
      "date_unit":"day",
      "quantity":"0",
      "time_zone":"America/New_York"
    },
    "time_zone":"America/New_York",
    "report_type":"publisher",
    "crosstab_columns":[],
    "action_tag_ids":[],
    "filters":{
      "advertiser_ids":["11077200770662"],
      "branch_ids":["11077200629234"],
      "campaign_ids":["11077201127917"],
      "client_ids":["11077200629235"],
      "company_ids":["11077200629233"],
      "publisher_ids":["11182200774314"],
      "site_ids":["11182200828329"]
    }
  },
  "file_format":"xlsx",
  "is_email_enabled":false,
  "email_addresses":[],
  "email_suffix":""
}]

Instagram and Audience Network

Advertising on Instagram and Audience Network

curl \
  -F 'name=My AdSet' \
  -F 'optimization_goal=REACH' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'bid_amount=2' \
  -F 'daily_budget=1000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \  
  -F 'targeting={        
    "geo_locations":{"countries":["US"]}
    "page_types":[
        "mobilefeed",
        "instagramstream",
        "mobileexternal",
      ]
    }' \
https://graph.facebook.com/v2.5/act_<AD_ACCOUNT_ID>/adsets

Preview a Instagram ad with cropping spec

curl –G \
-d 'ad_format=INSTAGRAM_STANDARD' \
-d 'creative={"object_story_spec":{
  "page_id": <PAGE_ID>
  "instagram_actor_id": <IG_ACCOUNT_FBID>
  "link_data": {
    ....
    "image_hash": "<IMAGE_HASH>",
    "image_crops": {
    '191x100': [[0, 200], [2000, 1247]], 
    '100x100': [[350, 100], [1550, 1300]]
    },
    ....
  }}' \
-d "access_token=<ACCESS_TOKEN>" \
https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/generatepreviews

Create a creative with a cropping spec

curl \
....
-F "image_hash=df35e69e647887b98bf9184aece6712e" \
-F "image_crops={
  '191x100': [[0, 200], [2000, 1247]],
  '100x100': [[350, 100]. [1550, 1300]]
}" \
-F "access_token=________" \
"https://graph.facebook.com/<API_VERSION>/act_<account id>/adcreatives"

Checking if a post can be reused

curl –G \
-d "access_token=<ACCESS_TOKEN>"\
-d "field=is_instagram_eligible"\
"https://graph.facebook.com/<API_VERSION>/<VIDEO_ID / POST_ID>"

Fetching insights

// stats for a given ad account
GET /<API_VERSION>/act_<AD_ACCOUNT_ID>/insights
// stats for a given campaign
GET /<API_VERSION>/<CAMPAIGN_ID>/insights
// stats for a given ad set
GET /<API_VERSION>/<AD_SET_ID>/insights
// stats for a given ad
GET /<API_VERSION>/<AD_ID>/insights
/insights?breakdowns=instagram_stream,mobile_external_only
curl \

  -F 'targeting={"geo_locations":{"countries":["US"]},"page_types":["desktopfeed","rightcolumn"]}' \
  -F 'status=ACTIVE' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.5/act_<AD_ACCOUNT_ID>/adsets

Additional Resources

Please check out our Marketing API Resources page