推廣 API

動態商品廣告受眾

進階高效速成目錄廣告可讓您根據用戶的跨裝置購買意願，向其展示廣告。您可以從流動應用程式及網站蒐集用戶的意願訊號，並以此建立廣告受眾來鎖定潛在顧客。

本文件包含以下內容：

第 1 步：設定事件的用戶訊號

如要蒐集用戶訊號，請使用應用程式事件（流動應用程式適用）或 Meta 像素（網站適用）。

如果您擁有應用程式，而且只在桌面版網站刊登廣告，則仍應該安裝 Facebook SDK。這可協助您擷取訊號並擴展您的目標廣告受眾。

如果是流動應用程式，請使用應用程式事件

您必須透過 Facebook iOS SDK 及 Facebook Android SDK，將以下事件加入您的應用程式：

事件iOS 事件Android 事件

搜尋

FBSDKAppEventNameSearched

EVENT_NAME_SEARCHED

瀏覽內容

FBSDKAppEventNameViewedContent

EVENT_NAME_VIEWED_CONTENT

新增至購物車

FBSDKAppEventNameAddedToCart

EVENT_NAME_ADDED_TO_CART

購買

// 透過 logPurchase 傳送
[[FBSDKAppEvents shared] logPurchase:(double) currency:(NSString *) parameters:(NSDictionary *)];

EVENT_NAME_PURCHASED

所有這些事件均需包含 content_id（或 content_id 的 JSON 陣列）。

與 Meta 像素不同，應用程式事件並沒有 product_catalog_id 參數。因此，您必須使用下方所述的 external_event_sources 端點，為目錄及應用程式建立連結。

範例

以下為 iOS AddToCart 事件的範例：

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

以下範例顯示在提供商品數量的情況下，包含兩件不同已購買物品的 iOS Purchase 事件：

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

以下範例顯示在提供商品數量的情況下，包含兩件已購買物品的 Android Purchase 事件：

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 Purchase 事件：

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 的編號類型同步。


如未提供 content_type，Meta 會將擁有相同編號的每個項目與事件配對，而不考慮其類型。


請參閱「選擇正確的 content_type」了解詳情。

_valueToSum

字串

此為選用項目。
商品總值。

fb_currency

字串

此為選用項目。
商品或購買金額的貨幣。

備註：建議您在用戶購買項目時傳送 _valueToSum 和 fb_currency 參數。

如果是網站，請使用 Meta 像素

您必須將以下事件加入您的網站（如適用）：

  • Search
  • ViewCategory
  • ViewContent
  • AddToCart
  • Purchase

上述事件應連同以下數據參數一併傳送：

名稱說明

content_ids

字串或字串[]

必須提供 content_ids 或 contents。
零售商的商品或商品群組編號。如果可以，請儘量使用商品編號，以便更準確地鎖定目標廣告受眾。

contents

物件[]

必須提供 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

字串

此為選用項目。
要使用的商品目錄。如果提供此參數，則此項目會是由像素觸發的唯一連結目錄。如果不提供此參數，則系統會使用與您像素連結的目錄。
請查看「為用戶訊號與商品目錄建立連結」了解詳情。

範例

以下為 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 標準事件的範例。如需了解更多有關像素設定的詳情，請參閱 Meta 像素。

<!-- 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 事件處理常式中，而用戶點擊按鈕時就會觸發事件。如果載入獨立頁面，像素事件將會如常觸發。

<!-- 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（特定尺寸、顏色等），則為 content_type 使用 product，然後傳遞 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 推薦更相關的商品，因為 Meta 會知道用戶對哪些特定款式（尺寸、顏色等）感興趣。我們會一律顯示商品（並非商品群組），即使在 content_type=product_group 的情況下亦不例外。

如無提供 content_type，Meta 會將擁有相同編號的每個項目與事件配對，而不考慮其類型。建議傳送 content_type，這樣您可進一步控制您希望哪個特定編號與事件配對。

第 2 步：為用戶訊號與商品目錄建立連結

您需要將事件來源與每個商品目錄建立連結，以便 Facebook 取得此等數據，並在廣告中展示正確的商品。若要執行此動作，請前往您的目錄企業管理平台目錄頁面並點擊「連結事件來源」按鈕。請務必選取將會接收進階高效速成目錄廣告事件的應用程式及像素。

或者，您亦可以執行 POST API 呼叫，並以外部事件來源清單作為 UTF-8 編碼查詢字串參數：

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

備註：您必須擁有目錄、像素、應用程式及企業的權限。

參數

名稱說明

external_event_sources

此為必要項目。
建立連結的應用程式及像素編號陣列，用作 UTF-8 編碼查詢字串參數

第 3 步：建立商品廣告受眾

接下來，您需根據流動應用程式和網站的活動，建立商品廣告受眾。您可以透過商品廣告受眾，選擇要使用的事件及指定廣告目標。

若是標準應用程式事件，則系統將會根據廣告像素事件名稱彙整廣告受眾：

  • 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

物件[]

此為必要項目。
參照一項 event 的網站自訂廣告受眾規則。

exclusions

JSON 物件

此為可選項目。
將帳戶管理中心帳戶排除在目標廣告受眾以外的事件。
套用排除條件後，如果事件在同一個商品群組（即商品在商品摘要中有相同的 item_group_id in）中的任何商品上發生，則系統會將執行此等事件的帳戶管理中心帳戶排除在目標廣告受眾以外。
例如：商品廣告受眾設定為包含 ViewContent 並排除 Purchase 事件。有一個帳戶管理中心帳戶瀏覽了商品 A 及 B，然後購買了商品 B。如果商品 A 及商品 B 屬於同一個商品群組，系統便會將此帳戶管理中心帳戶排除在商品廣告受眾之外，因為 A 與 B 只是不同的款式。如果商品 A 及 B 並非屬於同一個商品群組，則此帳戶管理中心帳戶會繼續留在廣告受眾中，因為此帳戶管理中心帳戶仍有商品 A 的 ViewContent 事件。

exclusions.retention_seconds

整數

如已指定排除條件，此為必要項目。
保留排除條件的秒數。

exclusions.rule

物件[]

如已指定排除條件，則此為必要項目。
參照一項 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 像素中加入 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>

了解詳情