Dynamic Audiences

Dynamic Ads enables you to show people ads based on their cross-device purchasing intent. You can collect signals of user intent from mobile apps and websites then use this data to build an audience to target prospective customers.

This describes how you can create an audience:

• Step 1: Setup User Signals for Events
• Step 2: Associate User Signals to Catalog
• Step 3: Create Audiences

This document also covers:

• Retrieve Dynamic Audiences
• Troubleshooting

Step 1: Set Up User Signals for Events

To collect user signals, use App Events (for your mobile app) or Facebook Pixel (for your website):

For Mobile, use App Events

You must add the following events to your app through Facebook SDK for iOS and Android:

All of these events should include a content type and a content id (or a JSON array of content ids).

Unlike the Facebook pixel, App Events has no product_catalog_id parameter. Therefore you must make an association between your catalog and app with the external_event_sources endpoint described below.

Sample Add To Cart event on iOS:

[FBSDKAppEvents logEvent:FBSDKAppEventNameAddedToCart
  valueToSum:54.23
  parameters:@{
    FBSDKAppEventParameterNameCurrency    : @"USD",
    FBSDKAppEventParameterNameContentType : @"product",
    FBSDKAppEventParameterNameContentID   : @"123456789"
  }
];

An example purchase event on iOS with two different items purchased with quantity:

[FBSDKAppEvents logPurchase:21.97
  currency:@"USD" 
  parameters:@{
    FBSDKAppEventParameterNameContent   : @"[{\"id\":\"1234\",\"quantity\":2},{\"id\":\"5678\",\"quantity\":1}]",
    FBSDKAppEventParameterNameContentType : @"product"
  }
];

An example purchase event on Android with two items purchased with quantity:

Bundle parameters = new Bundle();
parameters.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, "USD");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, "product");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT, "[{\"id\":\"1234\",\"quantity\":2},{\"id\":\"5678\",\"quantity\":1}]");

logger.logEvent(
  AppEventsConstants.EVENT_NAME_PURCHASED,
  21.97,
  parameters
);

An example purchase event on Android with two items purchased:

Bundle parameters = new Bundle();
parameters.putString(AppEventsConstants.EVENT_PARAM_CURRENCY, "USD");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_TYPE, "product");
parameters.putString(AppEventsConstants.EVENT_PARAM_CONTENT_ID, "[\"1234\",\"5678\"]");

logger.logEvent(
  AppEventsConstants.EVENT_NAME_PURCHASED,
  21.97,
  parameters
);

Note that either CONTENT_ID or CONTENT can be used with Dynamic Ads to report product IDs. CONTENT param will allow you to provide additional information about the products.

Using a Mobile Measurement Partner

To use Dynamic Ads with a mobile measurement partner (MMP), you should trigger required separate events as someone uses your app. The key interaction points you should track are when someone searches for products, views a product, adds something to a cart and purchases items. You should select the events at your MMP that correspond to the following standard Dynamic Ads events:

Also, you need two additional parameters for each of the events to be registered successfully as a valid Dynamic Ads event. These two parameters represent the id of the item being viewed, added to cart or purchased and whether the id is a product or a product group id. The additional parameters available are:

It is advisable to send the _valueToSum and fb_currency parameters when a purchase is made.

For Websites, use Facebook Pixel

The following events must be added to your website if applicable:

• Search
• ViewCategory
• ViewContent
• AddToCart
• Purchase

These events should be sent with the following data parameters:

More details on specifying events and parameters are under Remarketing Events, see Tag API documentation.

An example of Search standard event is shown below. We recommend providing 5 to 10 items in content_ids from your top search results.

<!-- 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','https://connect.facebook.net/en_US/fbevents.js');
// Insert Your Facebook Pixel ID below. 
fbq('init', '<FB_PIXEL_ID>');
fbq('track', 'PageView');

fbq('track', 'Search', { 
  search_string: 'leather sandals',
  content_ids: ['1234', '2424', '1318', '6832'], // top 5-10 search results
  content_type: 'product'
});
</script>
<!-- End Facebook Pixel Code -->

An example of ViewCategory event is shown below. We recommend providing 5 to 10 items in content_ids from your top results. Note that ViewCategory is not a standard event, thus the trackCustom function is used.

<!-- 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','https://connect.facebook.net/en_US/fbevents.js');
// Insert Your Facebook Pixel ID below. 
fbq('init', '<FB_PIXEL_ID>');
fbq('track', 'PageView');

fbq('trackCustom', 'ViewCategory', {
  content_name: 'Really Fast Running Shoes',
  content_category: 'Apparel &amp; Accessories > Shoes',
  content_ids: ['1234', '2424', '1318', '6832'], // top 5-10 results
  content_type: 'product'
});
</script>
<!-- End Facebook Pixel Code -->

An example of ViewContent standard event is shown below. More details on pixel setup, see Facebook Pixel.

<!-- 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','https://connect.facebook.net/en_US/fbevents.js');
// Insert Your Facebook Pixel ID below. 
fbq('init', '<FB_PIXEL_ID>');
fbq('track', 'PageView');

fbq('track', 'ViewContent', {
  content_ids: ['1234'],
  content_type: 'product',
  value: 0.50,
  currency: 'USD'
});
</script>
<!-- End Facebook Pixel Code -->

An example of AddToCart standard event depends on how your eCommerce platform handles adding an item to a cart. If it is done dynamically this should be placed in an onclick event handler so it is triggered on the button click. If a separate page is loaded then the pixel event can be fired like normal.

<!-- 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','https://connect.facebook.net/en_US/fbevents.js');
// Insert Your Facebook Pixel ID below. 
fbq('init', '<FB_PIXEL_ID>');
fbq('track', 'PageView');

// If you have a separate add to cart page that is loaded.
fbq('track', 'AddToCart', {
  content_ids: ['1234', '1853', '9386'],
  content_type: 'product',
  value: 3.50,
  currency: 'USD'
});
</script>
<!-- End Facebook Pixel Code -->

If the event needs to be fired on button click and there is no separate page that loads:

<!-- The below method uses jQuery, but that is not required -->

<button id="addToCartButton">Add To Cart</button>
<!-- Add event to the button's click handler -->

<script type="text/javascript">
  $( '#addToCartButton' ).click(function() {
    fbq('track', 'AddToCart', {
      content_ids: ['1234'],
      content_type: 'product',
      value: 2.99,
      currency: 'USD' 
    });  
  });
</script>

An example of Purchase standard event with two items with quantity:

<!-- 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','https://connect.facebook.net/en_US/fbevents.js');
// Insert Your Facebook Pixel ID below. 
fbq('init', '<FB_PIXEL_ID>');
fbq('track', 'PageView');

fbq('track', 'Purchase', {
  contents: [
    {'id': '1234', 'quantity': 2},
    {'id': '4642', 'quantity': 1}
  ],
  content_type: 'product',
  value: 21.97,
  currency: 'USD'
});
</script>

<!-- End Facebook Pixel Code -->

An example of Purchase standard event with two items:

<!-- 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','https://connect.facebook.net/en_US/fbevents.js');
// Insert Your Facebook Pixel ID below. 
fbq('init', '<FB_PIXEL_ID>');
fbq('track', 'PageView');

fbq('track', 'Purchase', {
  content_ids: ['1234', '4642'],
  content_type: 'product',
  value: 21.97,
  currency: 'USD'
});
</script>

<!-- End Facebook Pixel Code -->

Choosing the right content_type (fb_content_type for mobile)

If the page is about a specific SKU (specific size, color, etc), then use product for content_type and pass the product IDs (id column in the Product Feed) in content_ids. ALL AddToCart and Purchase events should use content_type=product because people buy specific products. People don't buy an amorphous shirt of indeterminate size and color; they buy a specific shirt with a specific size and color.

If the page is about a group of related products that vary by size, color, etc but belong to the same product group, use product_group and pass the product group IDs (item_group_id column in the Product Feed) in content_ids. A common use case is a ViewContent page where the user has not chosen a size yet. Do NOT use product_group with AddToCart or Purchase.

It's important that the content_type matches the type of id(s) included in the content_ids or contents parameter.

Passing the specific product IDs (content_type=product) allows Facebook to recommend more relevant products because it knows which specific variant (size, color, etc) the user expressed interest in. Note that what content_type you pass does not impact the recommendation logic. We will always show products (not product groups), even if content_type=product_group.

Step 2: Associate User Signals to Product Catalog

Next, you need to associate your event sources with each of your product catalogs so that Facebook can get this data and display the correct product in an ad. You can do this by visiting your Business Manager's Catalog Page and clicking the Associate Event Source button. Make sure to select the app and pixel that will be receiving the Dynamic Ads events.

Alternatively, you can make a HTTP POST with a list of external event sources as a UTF-8 encoded query string parameters:

use FacebookAds\Object\ProductCatalog;

$product_catalog = new ProductCatalog(<PRODUCT_CATALOG_ID>);
$product_catalog->createExternalEventSource(array(), array(
  'external_event_sources' => array(
    <PIXEL_ID>,
    <APP_ID>,
  ),
));

from facebookads.adobjects.productcatalog import ProductCatalog

product_catalog = ProductCatalog(<PRODUCT_CATALOG_ID>)
product_catalog.add_external_event_sources([
    <PIXEL_ID>,
    <APP_ID>,
])

curl \
  -F 'external_event_sources=["<PIXEL_ID>","<APP_ID>"]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PRODUCT_CATALOG_ID>/external_event_sources

You need to have permissions on the catalog, the pixel, and the app as well as the business.

When you make the API call, specify the following parameters:

Step 3: Create Product Audience

The next step is to build Product Audiences, based on activity on your mobile apps and website. You can choose what events to use and target ads using your Product Audiences.

For standard app events, the audience will be aggregated under the Ads Pixel event names:

• Search
• ViewContent
• AddToCart
• Purchase

Use these event names in your audience rules, even if it includes users on Android and iOS.

Create a Product Audience by making an HTTP POST call to:

https://graph.facebook.com/<API_VERSION>/act_<AD_ACCOUNT_ID>/product_audiences

Specify the following parameters:

To create an audience targeting people that viewed or added products to a cart, but didn't finish the purchase, you can use the following example:

curl -X POST \
  -F 'name="Test Product Audience"' \
  -F 'product_set_id="<PRODUCT_SET_ID>"' \
  -F 'inclusions=[
       {
         "retention_seconds": 86400,
         "rule": {
           "event": {
             "eq": "AddToCart"
           }
         }
       },
       {
         "retention_seconds": 72000,
         "rule": {
           "event": {
             "eq": "ViewContent"
           }
         }
       }
     ]' \
  -F 'exclusions=[
       {
         "retention_seconds": 172800,
         "rule": {
           "event": {
             "eq": "Purchase"
           }
         }
       }
     ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/product_audiences

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_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' : 'Test Product Audience',
  'product_set_id' : '<productSetID>',
  'inclusions' : [{'retention_seconds':86400,'rule':{'event':{'eq':'AddToCart'}}},{'retention_seconds':72000,'rule':{'event':{'eq':'ViewContent'}}}],
  'exclusions' : [{'retention_seconds':172800,'rule':{'event':{'eq':'Purchase'}}}],
};
const product_audiences = (new AdAccount(id)).createProductAudience(
  fields,
  params
);
logApiCallResult('product_audiences api call complete.', product_audiences);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\CustomAudience;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'Test Product Audience',
  'product_set_id' => '<productSetID>',
  'inclusions' => array(array('retention_seconds' => 86400,'rule' => array('event' => array('eq' => 'AddToCart'))),array('retention_seconds' => 72000,'rule' => array('event' => array('eq' => 'ViewContent')))),
  'exclusions' => array(array('retention_seconds' => 172800,'rule' => array('event' => array('eq' => 'Purchase')))),
);
echo json_encode((new AdAccount($id))->createProductAudience(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'Test Product Audience',
  'product_set_id': '<productSetID>',
  'inclusions': [{'retention_seconds':86400,'rule':{'event':{'eq':'AddToCart'}}},{'retention_seconds':72000,'rule':{'event':{'eq':'ViewContent'}}}],
  'exclusions': [{'retention_seconds':172800,'rule':{'event':{'eq':'Purchase'}}}],
}
print AdAccount(id).create_product_audience(
  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 = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createProductAudience()
      .setName(\"Test Product Audience\")
      .setProductSetId(\"<productSetID>\")
      .setInclusions(\"[{\\"retention_seconds\\":86400,\\"rule\\":{\\"event\\":{\\"eq\\":\\"AddToCart\\"}}},{\\"retention_seconds\\":72000,\\"rule\\":{\\"event\\":{\\"eq\\":\\"ViewContent\\"}}}]\")
      .setExclusions(\"[{\\"retention_seconds\\":172800,\\"rule\\":{\\"event\\":{\\"eq\\":\\"Purchase\\"}}}]\")
      .execute();

  }
}

require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
product_audiences = ad_account.product_audiences.create({
    name: 'Test Product Audience',
    product_set_id: '<productSetID>',
    inclusions: [{'retention_seconds':86400,'rule':{'event':{'eq':'AddToCart'}}},{'retention_seconds':72000,'rule':{'event':{'eq':'ViewContent'}}}],
    exclusions: [{'retention_seconds':172800,'rule':{'event':{'eq':'Purchase'}}}],
})

If you want target people that viewed a product on the web with iPhone, but haven't purchased on any device, create the following audience below.

This assumes that you include a userAgent parameter in your Facebook pixel:

curl -X POST \
  -F 'name="Test Iphone Product Audience"' \
  -F 'product_set_id="<PRODUCT_SET_ID>"' \
  -F 'inclusions=[
       {
         "retention_seconds": 86400,
         "rule": {
           "and": [
             {
               "event": {
                 "eq": "AddToCart"
               }
             },
             {
               "userAgent": {
                 "i_contains": "iPhone"
               }
             }
           ]
         }
       }
     ]' \
  -F 'exclusions=[
       {
         "retention_seconds": 172800,
         "rule": {
           "event": {
             "eq": "Purchase"
           }
         }
       }
     ]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/product_audiences

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_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' : 'Test Iphone Product Audience',
  'product_set_id' : '<productSetID>',
  'inclusions' : [{'retention_seconds':86400,'rule':{'and':[{'event':{'eq':'AddToCart'}},{'userAgent':{'i_contains':'iPhone'}}]}}],
  'exclusions' : [{'retention_seconds':172800,'rule':{'event':{'eq':'Purchase'}}}],
};
const product_audiences = (new AdAccount(id)).createProductAudience(
  fields,
  params
);
logApiCallResult('product_audiences api call complete.', product_audiences);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\CustomAudience;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'name' => 'Test Iphone Product Audience',
  'product_set_id' => '<productSetID>',
  'inclusions' => array(array('retention_seconds' => 86400,'rule' => array('and' => array(array('event' => array('eq' => 'AddToCart')),array('userAgent' => array('i_contains' => 'iPhone')))))),
  'exclusions' => array(array('retention_seconds' => 172800,'rule' => array('event' => array('eq' => 'Purchase')))),
);
echo json_encode((new AdAccount($id))->createProductAudience(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'name': 'Test Iphone Product Audience',
  'product_set_id': '<productSetID>',
  'inclusions': [{'retention_seconds':86400,'rule':{'and':[{'event':{'eq':'AddToCart'}},{'userAgent':{'i_contains':'iPhone'}}]}}],
  'exclusions': [{'retention_seconds':172800,'rule':{'event':{'eq':'Purchase'}}}],
}
print AdAccount(id).create_product_audience(
  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 = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).createProductAudience()
      .setName(\"Test Iphone Product Audience\")
      .setProductSetId(\"<productSetID>\")
      .setInclusions(\"[{\\"retention_seconds\\":86400,\\"rule\\":{\\"and\\":[{\\"event\\":{\\"eq\\":\\"AddToCart\\"}},{\\"userAgent\\":{\\"i_contains\\":\\"iPhone\\"}}]}}]\")
      .setExclusions(\"[{\\"retention_seconds\\":172800,\\"rule\\":{\\"event\\":{\\"eq\\":\\"Purchase\\"}}}]\")
      .execute();

  }
}

require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
product_audiences = ad_account.product_audiences.create({
    name: 'Test Iphone Product Audience',
    product_set_id: '<productSetID>',
    inclusions: [{'retention_seconds':86400,'rule':{'and':[{'event':{'eq':'AddToCart'}},{'userAgent':{'i_contains':'iPhone'}}]}}],
    exclusions: [{'retention_seconds':172800,'rule':{'event':{'eq':'Purchase'}}}],
})

Retrieve Product Audiences

Once you create a product audience, you can retrieve it with Custom Audiences API. See Custom Audience Creating. You can get the original parameters used for audience creation with the data_source parameter.

Product Audience is a specific type of Custom Audience that's dynamically generated from product events. The act_{AD_ACCOUNT_ID}/product_audiences endpoint is a special POST endpoint to construct these audiences.

Example to retrieve Custom Audience:

curl -X GET \
  -d 'fields="data_source,subtype"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v5.0/act_<AD_ACCOUNT_ID>/customaudiences

'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const AdAccount = bizSdk.AdAccount;
const CustomAudience = bizSdk.CustomAudience;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_ACCOUNT_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 = [
  'data_source',
  'subtype',
];
params = {
};
const customaudiencess = (new AdAccount(id)).getCustomAudiences(
  fields,
  params
);
logApiCallResult('customaudiencess api call complete.', customaudiencess);

require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\AdAccount;
use FacebookAds\Object\CustomAudience;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_ACCOUNT_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
  'data_source',
  'subtype',
);
$params = array(
);
echo json_encode((new AdAccount($id))->getCustomAudiences(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);

from facebook_business.adobjects.adaccount import AdAccount
from facebook_business.adobjects.customaudience import CustomAudience
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
  'data_source',
  'subtype',
]
params = {
}
print AdAccount(id).get_custom_audiences(
  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 = \"<AD_ACCOUNT_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new AdAccount(id, context).getCustomAudiences()
      .requestField(\"data_source\")
      .requestField(\"subtype\")
      .execute();

  }
}

require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_ACCOUNT_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad_account = FacebookAds::AdAccount.get(id)
customaudiencess = ad_account.customaudiences({
    fields: { 'data_source''subtype' },
})

Example to retrieve a specific Product Audience:

use FacebookAds\Object\ProductAudience;

$product_audience = new ProductAudience(<PRODUCT_AUDIENCE_ID>);
$product_audience->read();

from facebookads.objects import ProductAudience

product_audience = ProductAudience(<PRODUCT_AUDIENCE_ID>)
product_audience.remote_read()

CustomAudience customAudience2 = new CustomAudience(<PRODUCT_AUDIENCE_ID>, context).get()
  .execute();

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<PRODUCT_AUDIENCE_ID>

Troubleshooting

The video below walks through common issues found when setting up the pixel, app events, and catalog. It also features tools you can use to debug.