市场营销 API

动态商品受众

借助进阶赋能型目录广告，您可以根据用户的跨设备购买意向向他们显示广告。您可以从移动应用和网站收集用户意向信号，然后使用此数据构建受众来定位潜在客户。

本文档提供以下几方面的指南：

第 1 步：设置事件的用户信号

如要收集用户信号，请使用移动应用的应用事件，或者网站的 Meta Pixel 像素代码。

如果您拥有应用而且仅在桌面端投放广告，仍然应该安装 Facebook SDK，这可帮助您捕获信号并扩展目标受众。

移动应用的应用事件

您必须通过 iOS 版 Facebook SDK 和 Android 版 Facebook SDK 向应用添加下列事件：

事件iOS 事件Android 事件

Search

FBSDKAppEventNameSearched

EVENT_NAME_SEARCHED

ViewContent

FBSDKAppEventNameViewedContent

EVENT_NAME_VIEWED_CONTENT

AddToCart

FBSDKAppEventNameAddedToCart

EVENT_NAME_ADDED_TO_CART

Purchase

// 通过 logPurchase 发送
[[FBSDKAppEvents shared] logPurchase:(double) currency:(NSString *) parameters:(NSDictionary *)];

EVENT_NAME_PURCHASED

上述所有事件都应该包含 content_id（或者由 content_id 组成的 JSON 数组）。

与 Meta Pixel 像素代码不同，应用事件没有 product_catalog_id 参数。因此，您必须使用下文所述的 external_event_sources 端点在目录与应用之间建立关联。

示例

iOS 的“加入购物车”事件：

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

购买两件不同商品的 iOS 购物事件（提供商品数量）：

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

购买两件商品的 Android 购物事件（提供商品数量）：

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

购买两件商品的 Android 购物事件：

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

请注意，进阶赋能型目录广告可以使用 CONTENT_ID 或 CONTENT 报告商品编号。您可以通过 CONTENT 参数提供商品的额外信息。

使用移动应用成效衡量合作伙伴

如需将进阶赋能型目录广告与移动应用成效衡量合作伙伴 (MMP) 结合使用，您应该在有人使用您的应用时触发所需的单独事件。您应该追踪的关键互动点是有人搜索商品、浏览商品、将某件商品加入购物车和购买商品时。您应该在 MMP 中选择以下标准进阶赋能型目录广告事件对应的事件：

名称描述

fb_mobile_search

有人搜索商品

fb_mobile_content_view

当帐户管理中心帐户查看商品

fb_mobile_add_to_cart

有人将商品加入购物车

fb_mobile_purchase

帐户管理中心帐户购买一件或多件商品

另外，您需要两个额外参数，才能使每个事件成功注册为一个有效的进阶赋能型目录广告事件。这两个参数分别表示用户正在查看、已加入购物车或已购买商品的编号，以及该编号是商品编号还是商品组编号。可用的附加参数包括：

名称描述

fb_content_id

字符串

必须提供 fb_content_id 或 fb_content。
零售商的商品编号或商品组编号。这应该是一个字符串，其中包含 JSON 编码形式的编号数组。尽量使用商品编号，以便提升目标受众定位的精确度。

fb_content

字符串

必须提供 fb_content_id 或 fb_content。
JSON 对象清单，包含国际商品编码 (EAN)（如适用）或其他商品或内容标识符，以及商品的数量和价格。


必须提供 id 和 quantity 字段。
例如：
"[{\"id\": \"1234\", \"quantity\": 2}, {\"id\": \"5678\", \"quantity\": 1}]"

fb_content_type

字符串

非必要。
product 或 product_group，需要与用作 fb_content_id 的编号类型同步。


如果未提供 fb_content_type，Meta 会将事件与编号相同的每个商品匹配，而不会考虑其类型。


详情请参阅“选择正确的 content_type”。

_valueToSum

字符串

非必要。
商品总价值。

fb_currency

字符串

非必要。
商品或购买金额所用的货币。

备注：建议您在用户购买商品时发送 _valueToSum 和 fb_currency 参数。

使用网站专用 Meta Pixel 像素代码

在适用情况下，务必将以下事件添加到您的网站：

  • Search
  • ViewCategory
  • ViewContent
  • AddToCart
  • Purchase

这些事件应与下列数据参数一同发送：

名称描述

content_ids

string 或 string[]

必须提供 content_ids 或 contents。
零售商的商品编号或商品组编号。尽量使用商品编号，以便提升目标受众定位的精确度。

contents

object[]

必须提供 content_ids 或 contents。
JSON 对象清单，包含零售商的商品编号或商品组编号，以及与商品相关的额外信息。


必须提供id 和 quantity 字段
例如：[{"id": "1234", "quantity": 2}, {"id": "5678", "quantity": 1}]

content_type

字符串

非必要。
product 或 product_group，需要与用作 content_ids 的编号类型同步。


如果未提供 content_type，Meta 会将事件与编号相同的每个商品匹配，而不会考虑其类型。


详情请参阅“选择正确的 content_type”。

product_catalog_id

字符串

非必要。
要使用的商品目录。如果已提供此商品目录，则此目录将为与触发的 Pixel 像素代码关联的唯一目录。如果未提供此商品目录，将使用与您的 Pixel 像素代码关联的目录。
详情请参阅将用户信号与商品目录关联。

示例

下方示例为 Search 标准事件。建议在 content_ids 中提供您热门搜索结果中的 5 到 10 个商品。

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

下方示例为 ViewCategory 事件。建议在 content_ids 中提供您热门结果中的 5 到 10 个商品。请注意，ViewCategory 不是标准事件，因此将使用 trackCustom 函数。

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

下方示例为 ViewContent 标准事件。如需进一步了解 Pixel 像素代码设置，请参阅 Meta 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 -->

AddToCart 标准事件取决于您的电子商务平台如何处理将商品加入购物车的操作。如果此操作采用动态方式完成，则应该将此事件放入 onclick 事件处理程序中，在用户点击按钮时触发此事件。如果已加载单独的页面，则可以正常触发 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');

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

如果需要在用户点击按钮时触发事件并且没有要加载的单独页面，请使用以下代码：

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

购买两件商品的 Purchase 标准事件（提供商品数量）：

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

购买两件商品的 Purchase 标准事件：

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

选择正确的 content_type

注意：fb_content_type 是移动应用的内容类型。

如果页面与特定 SKU（具体尺寸、颜色等）相关，请使用 product 作为 content_type，并在 content_ids 中传递商品编号（即商品信息库中的 id 列）。所有 AddToCart 和 Purchase 事件应使用 content_type=product，因为用户会购买特定商品。用户不会购买尺寸和颜色不确定且无法分类的衬衫，他们会购买具有具体尺寸和颜色的特定衬衫。

如果页面与一组款式（尺寸、颜色等）不同但属于同一商品组的相关商品相关，请使用 product_group 并在 content_ids 中传递商品组编号（即商品信息库中的 item_group_id 列）。常见用例是用户尚未在其中选择尺寸的 ViewContent 页面。请勿将 product_group 与 AddToCart 或 Purchase 一起使用。

content_type 必须与 content_ids 或 contents 参数中所包含编号的类型相符。

通过传递特定商品编号 (content_type=product)，Meta 能够了解用户对哪些具体款式（尺寸、颜色等）感兴趣，从而推荐相关度更高的商品。即使传递 content_type=product_group，我们也会始终显示商品（而不是商品组）。

如果未提供 content_type，Meta 会将事件与编号相同的每个商品匹配，而不会考虑其类型。建议发送 content_type，使用此参数，更易于控制您想与事件匹配的特定编号。

第 2 步：将用户信号与商品目录关联

您需要将事件源与每个商品目录关联，以便 Facebook 获取此数据，并在广告中显示正确商品。如要执行此操作，可以访问商务管理平台的目录页面，然后点击关联事件源按钮。请务必选择要接收进阶赋能型目录广告事件的应用和 Pixel 像素代码。

或者，您也可以使用外部事件源清单作为 UTF-8 编码查询字符串参数，并以此发出 POST API 调用：

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

说明：您需要拥有目录、Pixel 像素代码、应用及公司的相应权限。

参数

名称描述

external_event_sources

必要。
要关联的应用编号和 Pixel 像素代码编号，其格式为 UTF-8 编码查询字符串参数

第 3 步：创建商品受众

下一步是根据移动应用和网站上的活动构建商品受众。您可以通过商品受众选择要使用的事件，并指定广告目标。

对于标准应用事件，系统将以广告 Pixel 像素代码事件名称汇总受众：

  • Search
  • ViewContent
  • AddToCart
  • Purchase

在您的受众规则中使用这些事件名称，即使其中包含 Android 和 iOS 用户也无妨。

对 /act_{ad-account-id}/product_audiences 端点执行 POST API 调用，以创建商品受众。

https://graph.facebook.com/v21.0/act_AD_ACCOUNT_ID/product_audiences

参数

名称描述

name

字符串

必要。
受众的名称。

description

字符串

非必要。
对受众的描述。

product_set_id

数字字符串

必要。要定位到此受众的商品系列。

inclusions

JSON 对象

必要。
一组要定位的事件。至少需要一个包含条件。每个包含条件应恰好具有一个事件。

inclusions.retention_seconds

整数

必要。
将账户中心账户留作受众的秒数。

inclusions.rule

object[]

必要。
引用一个 event 的网站自定义受众规则。

exclusions

JSON 对象

非必要。
应从目标受众中排除某个帐户管理中心帐户的事件。
对于排除条件，如果发生的事件涉及同一商品组中的任意商品（即，在商品信息库中具有同一 item_group_id in 的商品），则将从设置目标受众中排除发生这些事件的帐户管理中心帐户。
例如，将商品受众设置为包含 ViewContent，并将购买事件排除在外。帐户管理中心帐户查看商品 A 和 B，并购买商品 B。如果商品 A 和商品 B 都属于同一商品组，则将从商品受众中排除该帐户管理中心帐户，因为 A 和 B 只是款式。如果商品 A 和 B 属于不同的商品组，则继续将该帐户管理中心帐户留作受众，因为该帐户仍然有商品 A 的 ViewContent 事件。

exclusions.retention_seconds

整数

必要（如果已指定排除条件）。
保留排除条件的秒数。

exclusions.rule

object[]

必要（如果已指定排除条件）。
引用一个 event 的网站自定义受众规则。

无论作为顶层规则还是作为顶层 and 规则的一部分，每条规则都必须包含带运算符 eq 的 event。

如果在包含条件和排除条件中都使用同一 event，则任何额外参数检查必须完全相同。

示例

如要创建已查看商品或将商品添加至购物车，但未完成购买的目标受众人群，可以使用以下代码：

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/v21.0/act_<AD_ACCOUNT_ID>/product_audiences
Open In Graph API Explorer
'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);
Open In Graph API Explorer
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);
Open In Graph API Explorer
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,
)
Open In Graph API Explorer
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();

  }
}
Open In Graph API Explorer
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'}}}],
})
Open In Graph API Explorer

如要定位在网络上使用 iPhone 查看过某件商品但未在任何设备上购买的用户，请创建下方受众。

以下示例假设您已在 Meta Pixel 像素代码中加入 userAgent 参数。

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/v21.0/act_<AD_ACCOUNT_ID>/product_audiences
Open In Graph API Explorer
'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);
Open In Graph API Explorer
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);
Open In Graph API Explorer
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,
)
Open In Graph API Explorer
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();

  }
}
Open In Graph API Explorer
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'}}}],
})
Open In Graph API Explorer

检索商品受众

在您创建商品受众后，便可使用自定义受众 API 对其进行检索。您可以通过 data_source 参数获取用于创建受众的原始参数。

商品受众是特定类型的自定义受众，依据商品事件动态生成。act_{ad-account-id}/product_audiences 端点是用于构建商品受众的特殊 POST 端点。

示例

如要检索自定义受众，请使用以下代码：

curl -X GET \
  -d 'fields="data_source,subtype"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences
Open In Graph API Explorer
'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);
Open In Graph API Explorer
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);
Open In Graph API Explorer
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,
)
Open In Graph API Explorer
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();

  }
}
Open In Graph API Explorer
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' },
})
Open In Graph API Explorer

如要检索特定商品受众，请使用以下代码：

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>

详细了解