Dynamic Ads for Lead Generation

Generate leads with your Dynamic Ads. If you have a product catalog ready and run Dynamic Ads you can now collect leads with your ads on Facebook. Facebook selects the most relevant items in your product set, as we with all Dynamic Ads, and display a lead gen form when someone clicks and item.

When you download leads via API or as a file, we include retailer_item_id. This indicates which items someone clicked on and submitted their lead information for.

Creating Dynamic Ads for Lead Generation

Create a campaign with the objective as lead_generation.

curl -X POST \
  -F 'name=Lead generation campaign' \
  -F 'objective=LEAD_GENERATION' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v3.0/act_<AD_ACCOUNT_ID>/campaigns
const adsSdk = require('facebook-nodejs-ads-sdk');
const AdAccount = adsSdk.AdAccount;
const Campaign = adsSdk.Campaign;

let access_token = '<ACCESS_TOKEN>';
let app_secret = '<APP_SECRET>';
let app_id = '<APP_ID>';
let id = '<ID>';
const api = adsSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const fields = [
];
const params = {
  'name' : 'Lead generation campaign',
  'objective' : 'LEAD_GENERATION',
  'status' : 'PAUSED',
};
(new AdAccount(id)).createCampaign(
  fields,
  params
)
.then((result) => {
  campaigns_id = result.id;
  console.log(campaigns_id);
})
.catch((error) => {
  console.log(error);
});
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' => 'Lead generation campaign',
  'objective' => 'LEAD_GENERATION',
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createCampaign(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.campaign import Campaign
from facebookads.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': 'Lead generation campaign',
  'objective': 'LEAD_GENERATION',
  '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(\"Lead generation campaign\")
      .setObjective(Campaign.EnumObjective.VALUE_LEAD_GENERATION)
      .setStatus(Campaign.EnumStatus.VALUE_PAUSED)
      .execute();
  }
}
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)
ad_account.campaigns.create(
    name: 'Lead generation campaign',
    objective: 'LEAD_GENERATION',
    status: 'PAUSED',
)

This returns a campaign_id you use for your ad set.

As in all Dynamic Ads, you must specify product_set_id in promoted_object for your ad set. This enables you to advertise products from that set. For lead generation, set optimization_goal to lead_generation:

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 => 'Product Catalog Sales Adset',
  AdSetFields::BID_AMOUNT => 3000,
  AdSetFields::BILLING_EVENT => AdSetBillingEventValues::IMPRESSIONS,
  AdSetFields::OPTIMIZATION_GOAL =>
    AdSetOptimizationGoalValues::LEAD_GENERATION,
  AdSetFields::DAILY_BUDGET => 15000,
  AdSetFields::CAMPAIGN_ID => <CAMPAIGN_ID>,
  AdSetFields::TARGETING => array(
    TargetingFields::GEO_LOCATIONS => array(
      'countries' => array('US'),
    ),
    TargetingFields::DYNAMIC_AUDIENCE_IDS => array(<DYNAMIC_AUDIENCE_ID>),
  ),
  AdSetFields::PROMOTED_OBJECT => array(
    'product_set_id' => <PRODUCT_SET_ID>,
    'page_id' => <PAGE_ID>,
  ),
));

$adset->create(array(
  AdSet::STATUS_PARAM_NAME => AdSet::STATUS_PAUSED,
));
curl \
  -F 'name=Product Catalog Sales Adset' \
  -F 'bid_amount=3000' \
  -F 'billing_event=IMPRESSIONS' \
  -F 'optimization_goal=LEAD_GENERATION' \
  -F 'daily_budget=15000' \
  -F 'campaign_id=<CAMPAIGN_ID>' \
  -F 'targeting={ 
    "geo_locations": {"countries":["US"]}, 
    "dynamic_audience_ids": ["<DYNAMIC_AUDIENCE_ID>"] 
  }' \
  -F 'promoted_object={"product_set_id":"<PRODUCT_SET_ID>","page_id":"<PAGE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/act_<AD_ACCOUNT_ID>/adsets

DYNAMIC_AUDIENCE_ID refers to a Product Audience who views your ads. You can omit dynamic_audience_ids from instead set behavioral- or demographic- based targeting to reach an audience. Provide:

  • product_audience_specs or
  • excluded_product_audience_specs parameters.

See Dynamic Ads.

Providing Ad and Creative

First provide ad creative:

use FacebookAds\Object\AdCreative;
use FacebookAds\Object\Fields\AdCreativeFields;
use FacebookAds\Object\Fields\AdCreativeLinkDataFields;
use FacebookAds\Object\Fields\AdCreativeObjectStorySpecFields;
use FacebookAds\Object\AdCreativeObjectStorySpec;
use FacebookAds\Object\AdCreativeLinkData;
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::SIGN_UP,
        'value' => array(
          'lead_gen_form_id' => <FORM_ID>,
        ),
      ),
      AdCreativeLinkDataFields::MESSAGE => 'Test {{product.name | titleize}}',
      AdCreativeLinkDataFields::LINK => '<LINK>',
      AdCreativeLinkDataFields::NAME => 'Headline {{product.price}}',
      AdCreativeLinkDataFields::DESCRIPTION =>
        'Description {{product.description}}',
      AdCreativeLinkDataFields::MULTI_SHARE_END_CARD => false,
    )),
));

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

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

$creative->create();
curl \
  -F 'name=Dynamic Ad With Leadgen Template Creative Sample' \
  -F 'object_story_spec={ 
    "page_id": "<PAGE_ID>", 
    "template_data": { 
      "call_to_action": {"type":"SIGN_UP","value":{"lead_gen_form_id":"<FORM_ID>"}}, 
      "description": "Description {{product.description}}", 
      "link": "<LINK>", 
      "message": "Test {{product.name | titleize}}", 
      "multi_share_end_card": false, 
      "name": "Headline {{product.price}}" 
    } 
  }' \
  -F 'product_set_id=<PRODUCT_SET_ID>' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.9/act_<AD_ACCOUNT_ID>/adcreatives

This returns creative_id you can use to create or update an Ad:

curl -X POST \
  -F 'name=My Ad' \
  -F 'adset_id=<AD_SET_ID>' \
  -F 'creative={"creative_id":"<CREATIVE_ID>"}' \
  -F 'status=PAUSED' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v3.0/act_<AD_ACCOUNT_ID>/ads
const adsSdk = require('facebook-nodejs-ads-sdk');
const AdAccount = adsSdk.AdAccount;
const Ad = adsSdk.Ad;

let access_token = '<ACCESS_TOKEN>';
let app_secret = '<APP_SECRET>';
let app_id = '<APP_ID>';
let id = '<ID>';
const api = adsSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const fields = [
];
const params = {
  'name' : 'My Ad',
  'adset_id' : '<adSetID>',
  'creative' : {'creative_id':'<adCreativeID>'},
  'status' : 'PAUSED',
};
(new AdAccount(id)).createAd(
  fields,
  params
)
.then((result) => {
  ads_id = result.id;
  console.log(ads_id);
})
.catch((error) => {
  console.log(error);
});
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\Ad;
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' => 'My Ad',
  'adset_id' => '<adSetID>',
  'creative' => array('creative_id' => '<adCreativeID>'),
  'status' => 'PAUSED',
);
echo json_encode((new AdAccount($id))->createAd(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
from facebookads.adobjects.adaccount import AdAccount
from facebookads.adobjects.ad import Ad
from facebookads.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': 'My Ad',
  'adset_id': '<adSetID>',
  'creative': {'creative_id':'<adCreativeID>'},
  'status': 'PAUSED',
}
print AdAccount(id).create_ad(
  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).createAd()
      .setName(\"My Ad\")
      .setAdsetId(<adSetID>L)
      .setCreative(
          new AdCreative()
            .setFieldId(\"<adCreativeID>\")
        )
      .setStatus(Ad.EnumStatus.VALUE_PAUSED)
      .execute();
  }
}
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)
ad_account.ads.create(
    name: 'My Ad',
    adset_id: '<adSetID>',
    creative: {'creative_id':'<adCreativeID>'},
    status: 'PAUSED',
)

Fetching Leads

If you have the lead id from a CRM integration for example, you can ask for the details including item_id.

use FacebookAds\Object\Lead;

$form = new Lead(<LEAD_ID>);
$form->read(array(
    LeadFields::FIELD_DATA,
    "retailer_item_id",
));
curl -G \
  -d 'fields=field_data,retailer_item_id' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<LEAD_ID>

You can also bulk query all the leads for a form:

use FacebookAds\Object\LeadgenForm;

$form = new LeadgenForm(<FORM_ID>);
$leads = $form->getLeads(array(
    LeadFields::FIELD_DATA,
    "retailer_item_id",
));
curl -G \
  -d 'fields=field_data,retailer_item_id' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<FORM_ID>/leads

Or for an ad:

use FacebookAds\Object\Ad;

$ad = new Ad(<AD_ID>);
$leads = $ad->getLeads(array(
    LeadFields::FIELD_DATA,
    "retailer_item_id",
));
curl -G \
  -d 'fields=field_data,retailer_item_id' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<AD_ID>/leads