推廣 API
返回中文(香港)
這份文件已更新。
中文(香港) 的翻譯尚未完成。
英文更新時間：2023年7月18日

數據提升研究

建立並執行實驗，以衡量您的 Facebook 宣傳活動成效。判斷哪個廣告策略能帶動最大的業務影響力。請參閱參考資料：廣告研究。

建立數據提升研究時，您會建立隨機分配的測試組（涵蓋看到廣告的帳戶管理中心帳戶）和對照組（涵蓋沒有看到廣告的帳戶管理中心帳戶）。

您可以安全地使用 Facebook 像素或應用程式事件，與 Facebook 分享廣告宣傳活動的轉換數據。Facebook 會判斷宣傳活動帶來的轉換次數增幅。我們會比較測試組與對照組的轉換次數、帳戶管理中心帳戶轉換數量，以及所得之銷售收入。

設定研究

設定含有一個或以上群組（稱為組別）的研究。設定研究後，Facebook 會隨機分配廣告受眾，並將帳戶管理中心帳戶分為測試組與對照組。進行研究後，Facebook 會計算測試組與對照組之間的差異值，這樣您就可以評估 Facebook 廣告對於業務目標的影響力。

如要建立研究，請執行 POST 呼叫：

'https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies'

您可以建立含有單一測試組的研究，看看 Facebook 廣告如何帶來其他的業務效益。您亦可建立含有多個測試組的研究，讓您判斷哪種廣告策略最適合您的廣告受眾。

範例 - 建立含有單一個測試組的研究

curl \
  -F 'name="new study"' \
  -F 'description="description of my study"' \
  -F 'start_time=1435622400' \
  -F 'end_time=1436918400' \
  -F 'cooldown_start_time=1433116800' \
  -F 'observation_end_time=1438300800' \
  -F 'viewers=[<USER_ID1>, <USER_ID2>]' \
  -F 'type=LIFT' \
  -F 'cells=[{name:"test group",description:"description of my test group",treatment_percentage:90,control_percentage:10,adaccounts:[<ACCOUNT_ID1>,<ACCOUNT_ID2>]}]' \
  -F 'objectives=[{name:"new objective",is_primary:true,type:"CONVERSIONS",applications:[{id:<APP_ID>}]}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies'

若要建立新的研究，請提供下列項目：

參數說明

name

研究名稱。

description

有關研究目的之簡短描述。

cooldown_start_time

已棄用。Facebook 仍會在 observation_end_time 至 end_time 期間刊登廣告。如果您使用的是 cooldown_start_time，就必須現在使用 start_time 設定此時間。

start_time

宣傳活動活躍時段的開始時間。研究的開始時間必須為未來時間。

end_time

宣傳活動活躍時段的結束時間。

observation_end_time

測試後轉換期間的結束時間。在此期間（即在 end_time 和 observation_end_time 之間），所有 Facebook 廣告（包括在本研究加入的廣告）都會正常地向測試組和對照組刊登，但不會有機會記錄新用戶。我們會在此期間繼續把轉換與各相應群組中的用戶配對。如果您的研究不需要測試後轉換期間，請將此項設定為 end_time。

cells

研究中定義測試組與對照組的單元。

objectives

研究的目標。請參閱定義研究目標。

viewers

將此研究分享至 Facebook 用戶編號清單。

type

若為轉換提升，類型應為 LIFT。

限制 - 研究開始之後，您就無法更新組別的 start_time 和 treatment_percentage。您也無法移除相關物件，例如測試組的 adaccounts 或 campaigns。研究尚未結束前，您仍可將 end_time 和 observation_end_time 更新至未來時間，並將相關物件新增至測試組。

若要同時執行「觸及率和頻率」及「數據提升成效衡量」，您必須先建立「數據提升研究」，並確保「觸及率和頻率」的執行時段是在「數據提升研究」的時段內。

建立測試組

首先，請決定要讓多少帳戶管理中心帳戶看到廣告，多少帳戶管理中心帳戶看不到廣告。設定研究時，您必須建立測試組；在 ad_studies 下的 cells 內傳送 JSON 物件清單。請參閱廣告研究組別參考資料。測試組必須包含以下資訊。

參數說明

name

測試組名稱。

description

有關測試組的簡短說明。

treatment_percentage

定義將會收到您廣告的帳戶管理中心帳戶。

control_percentage

定義對照組百分比，即不會看到廣告的帳戶管理中心帳戶比例。實驗組與對照組比率的總和必須等於 100。

ad_studies

研究的廣告實體清單，例如 adaccounts 或 campaigns。Facebook 會在研究時段內刊登並衡量活躍廣告實體內的所有廣告。

範例 - 讀取研究中的測試組

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<STUDY_ID>/cells'

範例 - 只需在 cells 中提供組別編號，即可更新或修改組別資訊，以及實驗和對照百分比

curl \
  -F 'cells=[{id:<CELL_ID>,treatment_percentage:80,control_percentage:20}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<STUDY_ID>'

範例 - 讀取您在 ad_studies 中為自己企業建立的所有研究

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies'

您還可使用存取憑證，在 {ad-account-ID/include_all_studies=true} 處發出 GET 要求，查看與您的廣告帳戶相關的所有研究。

建立多個測試組

建立含有多個 Facebook 用戶測試組的研究。這樣有助衡量不同 Facebook 廣告策略為業務目標帶來的影響力增幅，例如使用不同的廣告目標設定選項。要建立含有多個測試組的研究，請在 cells 中提供測試組清單。

curl \
  -F 'name="new study"' \
  -F 'description="description of my study"' \
  -F 'start_time=1435622400' \
  -F 'end_time=1436918400' \
  -F 'cooldown_start_time=1433116800' \
  -F 'observation_end_time=1438300800' \
  -F 'viewers=[<USER_ID1>, <USER_ID2>]' \
  -F 'type=LIFT' \
  -F 'cells=[{name:"group A",description:"description of group A",treatment_percentage:50,control_percentage:20,campaigns:[<CAMPAIGN_ID1>]},{name:"group B",description:"description of group B",treatment_percentage:20,control_percentage:10,campaigns:[<CAMPAIGN_ID2>]}]' \
  -F 'objectives=[{name:"new objective",is_primary:true,type:"CONVERSIONS",applications:[{id:<APP_ID>}]}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies'

control_percentage 可決定每個測試組中與總人數相比的對照百分比。舉例來說，如果您的研究設有兩個測試組：測試組 A 有 50% 實驗對象及 20% 對照對象，而測試組 B 有 20% 實驗對象及 10% 對照對象。這樣約有 28.6%，或 20%／70% 的實驗組 A 人數會是對照對象，約 33.3%，或 10%／30% 的實驗組 B 人數會是對照對象。

測試組的實驗與對照百分比總和通常應等於 100。但在特定的使用案例下，有可能會低於 100。舉例來說，如果您有三個測試組，便會平均分配為每組 33%。

您可以更新、新增和移除研究中的測試組。

  • 若要更新現有的測試組，請參考該組別在測試組中的編號。
  • 若要新增測試組，請提供新的測試組物件。
  • 要移除測試組，只需在更新研究時，於 cells 中省略該群組即可：
curl \
  -F 'cells=[{id:<CELL_ID1>,treatment_percentage:60,control_percentage:10},{name:"group C",description:"replacing group B",treatment_percentage:25,control_percentage:5,campaigns:[<CAMPAIGN_ID3>]}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<STUDY_ID>'

定義廣告目標

定義您想衡量的廣告目標，以及將轉換數據傳送至 Facebook 的方式。每項數據提升研究最少需要一個目標。開始執行研究後，您將無法修改目標。請參閱廣告研究目標參考資料。

範例：建立 CONVERSIONS 目標並將其新增至研究

curl \
  -F 'name="new study"' \
  -F 'description="description of my study"' \
  -F 'start_time=1435622400' \
  -F 'end_time=1436918400' \
  -F 'cooldown_start_time=1433116800' \
  -F 'observation_end_time=1438300800' \
  -F 'viewers=[<USER_ID1>, <USER_ID2>]' \
  -F 'type=LIFT' \
  -F 'cells=[{name:"test group",description:"description of my test group",treatment_percentage:90,control_percentage:10,adaccounts:[<ACCOUNT_ID1>,<ACCOUNT_ID2>]}]' \
  -F 'objectives=[{name:"new objective",is_primary:true,type:"CONVERSIONS",applications:[{id:<APP_ID>}]}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies'


名稱 說明 資料來源

CONVERSIONS

衡量轉換次數的提升幅度。

基於轉換 API 的 Facebook 像素

如果您使用 CONVERSIONS，並使用 Facebook 像素或流動應用程式作為事件來源，您就必須提供要就該目標記錄的事件名稱之清單，然後 Facebook 就會根據這些特定轉換事件回報成效。

成效衡量來源 事件名稱

Facebook 像素

fb_pixel_view_content、fb_pixel_search、fb_pixel_add_to_cart、fb_pixel_add_to_wishlist、fb_pixel_initiate_checkout、fb_pixel_add_payment_info、fb_pixel_purchase、fb_pixel_lead、fb_pixel_complete_registration、custom

流動應用程式

fb_mobile_activate_app、fb_mobile_complete_registration、fb_mobile_content_view、fb_mobile_search、fb_mobile_rate、fb_mobile_tutorial_completion、fb_mobile_add_to_cart、fb_mobile_add_to_wishlist、fb_mobile_initiated_checkout、fb_mobile_add_payment_info、fb_mobile_purchase、fb_mobile_level_achieved、fb_mobile_achievement_unlocked、fb_mobile_spent_credits

建立目標

建立新的研究時，您可傳送 JSON 物件 objectives 清單來建立目標。目標包含下列資訊：

參數說明

name

目標名稱。

is_primary

此為布林值，用於指定這是您的主要廣告目標。每項研究只能有一個主要目標。

type

CONVERSIONS 的目標值。

adspixels

Facebook 像素編號清單，其中包括每個編號的 event_names 相關清單（如適用）。

applications

流動應用程式清單，包括每個編號的 event_names 相關清單。

offline_conversion_data_sets

離線事件組合編號清單（如適用）。我們目前不支援離線轉換的事件資料細節。

customconversions

自訂轉換編號清單（如適用）。

每項研究也可以有多個目標。成效會根據目標彙整。以下是具有多個目標的研究之範例。

curl \
  -F 'name="another study"' \
  -F 'description="description of another study"' \
  -F 'start_time=1435622400' \
  -F 'end_time=1436918400' \
  -F 'cooldown_start_time=1433116800' \
  -F 'observation_end_time=1438300800' \
  -F 'viewers=[<USER_ID1>, <USER_ID2>]' \
  -F 'type=LIFT' \
  -F 'cells=[{name:"test group",description:"description of my test group",treatment_percentage:90,control_percentage:10,adaccounts:[<ACCOUNT_ID1>,<ACCOUNT_ID2>]}]' \
  -F 'objectives=[{name:"first objective objective",is_primary:true,type:"CONVERSIONS",applications:[{id:<APP_ID1>},{id:<APP_ID2>}]},{name:"scond  objective",type:"CONVERSIONS",applications:[{id:<APP_ID3>,event_names:["fb_mobile_purchase"]}],adspixels:[{id:<FB_PIXEL_ID>,event_names:["fb_pixel_purchase","fb_pixel_lead"]}]}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies'

您可更新、新增及移除研究中的目標，方法是在研究級別中操作（與修改測試組類似）。如要更新現有的目標，請參閱 objectives 物件中的目標編號。若要新增目標，請提供新的目標物件。如要移除目標，只需在更新時於 objectives 參數中省略該目標即可。

範例 - 更新目標的 applications 成效衡量來源，並移除其 adspixels 成效衡量來源

curl \
  -F 'objectives=[{id:<OBJECTIVE_ID>,name:"new objective name",applications:[{id:<APP_ID>}],adspixels:[]}]' \
  -F 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<STUDY_ID>'

範例 - 讀取研究目標

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<STUDY_OBJECTIVE_ID>?fields=results&breakdowns=["cell_id"]'

報告

檢索目標

如果研究在 2021 年 7 月 13 日截止日期前開始，則所有相關「buyers」衡量數據均會顯示。至於 7 月 13 日後開始的研究，「buyers」衡量數據和按性別、年齡和國家／地區分類的資料細節均不會顯示。此變更會影響下列以「buyers」開頭的欄位（buyers_test、buyers_control_scaled2 等）。

另請注意，您需要使用 cell_id 資料細節才能獲得組別層級結果。

研究的目標是在建立研究時所定義的。請參閱設定指南，了解如何定義研究目標

您可讀取為研究建立的目標，方法是向研究的 objectives 關係連線執行 GET 呼叫。

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<STUDY_OBJECTIVE_ID>?fields=results&breakdowns=["cell_id"]'

如要了解目標的詳情，請參閱廣告研究目標參考文件。

檢索成效

如要檢索某個目標的結果，您可在欄位參數中指定 results，藉以向目標節點執行 GET 呼叫。last_updated_results 欄位也會顯示這個特定目標的結果數據最後更新的時間。

樣本回應會顯示已剖析的 JSON 以便讀取。

指令：

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<STUDY_OBJECTIVE_ID>?fields=results&breakdowns=["cell_id"]'

最後得出的數據是 JSON 物件，含有衡量數據名稱和值字串。請參閱 Facebook 提升幅度衡量數據詞彙表。

有買家：

{
	"results": [
	"{"cell_id":"<cell_id>",
	"population_test":2334212,
	"population_control":123407,
	"population_reached":1862084,
	"impressions":19020874,
	"spend":26059,
	"buyers_control_raw_scaled":37672.615701199,
	"buyers_exposed":30085.482427228,
	"buyers_frequentist_pValue":0.00064950107027983,
	"conversions_control_raw_scaled":110918.27003534,
	"conversions_exposed":86961.044050743,
	"conversions_raw_pValue":0.12863848309723,
	"conversions_test":104412.89695396,
	"conversions_control_scaled":104575.81331581,
	"conversions_incremental":-162.91636184894,
	"conversions_notExposed":87123.960412592,
	"conversions_confidence":0.69291721817069,
	"conversions_multicell_confidence":null,
	"conversions_incremental_lower":-3470.6251396487,
	"conversions_incremental_upper":3235.0644420632,
	"conversions_multicell_rank":null,
	"conversions_incremental_share":-0.001873440730011,
	"conversions_CPiC":-159.95324044961,
	"buyers_test":40732.369934386,
	"buyers_control_scaled":41990.129061459,
	"buyers_incremental":-1257.7591270729,
	"buyers_notExposed":36617.935710157,
	"buyers_confidence":0.19318944031404,
	"buyers_multicell_confidence":null,
	"buyers_incremental_lower":-2905.5296282828,
	"buyers_incremental_upper":426.25813050358,
	"buyers_multicell_rank":null,
	"buyers_incremental_share":-0.041806181107957,
	"buyers_CPiB":-20.718593440578}"
	  ],
	  "id": "<objective_id>"
}

無買家：

{
	"results": [
	"{"cell_id":"<cell_id>",
	"population_test":2334212,
	"population_control":123407,
	"population_reached":1862084,
	"impressions":19020874,
	"spend":26059,
	"conversions_control_raw_scaled":110918.27003534,
	"conversions_exposed":86961.044050743,
	"conversions_raw_pValue":0.12863848309723,
	"conversions_test":104412.89695396,
	"conversions_control_scaled":104575.81331581,
	"conversions_incremental":-162.91636184894,
	"conversions_notExposed":87123.960412592,
	"conversions_confidence":0.69291721817069,
	"conversions_multicell_confidence":null,
	"conversions_incremental_lower":-3470.6251396487,
	"conversions_incremental_upper":3235.0644420632,
	"conversions_multicell_rank":null,
	"conversions_incremental_share":-0.001873440730011,
	"conversions_CPiC":-159.95324044961}"
	  ],
	  "id": "<objective_id>"
}

資料細節結果

除了檢索每項目標的結果，您也可選擇提供 breakdowns 參數，藉以細分結果。

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  'https://graph.facebook.com/<API_VERSION>/<STUDY_OBJECTIVE_ID>?fields=results&breakdowns=["cell_id"]'

下列是可用的資料細節元素：

研究如在 7 月 13 日後開始，其按性別、年齡和國家／地區分類的資料細節將均不會顯示。

資料細節 值

age

13-17、18-24、25-34、35-44、45-54、55-54、65+

cell_id

研究中可用單元的編號。

gender

M 或 F

country

雙字母國碼／區碼（ISO 3166-1 alpha-2）。範例：US、GB、IN、AU。

目前只支援與 cell_id 合併查詢。

例如：breakdowns=['cell_id','country']

結果會根據可用的資料細節，傳回含有多個 JSON 物件的陣列。舉例來說，如果有提供 cell_id，結果就會根據研究中的組別數量細分。您可提供一項或以上的資料細節；但資料細節的總和必須最少有 100 次轉換次數（測試組加對照組），才能顯示結果。

{
  "id": "<STUDY_OBJECTIVE_ID>",
  "results": [
  {
    "cell_id": "<CELL_ID1>",
    ...
    Default fields where the values are specific to the <CELL_ID1> breakdown
    ...
  },
  {
    "cell_id": "<CELL_ID2>",
    ...
    Default fields where the values are specific to the <CELL_ID2> breakdown
    ...
  }],
}

特定日期戳記的結果

您可以在 API 呼叫中指定一個日期戳記，以獲取特定日期的研究結果。請注意，此呼叫所傳回的結果，將會與您在當日執行，且沒有包括日期戳記欄位的呼叫所傳回的結果相同。此日期必須在過去 30 天內。

curl -G \
      -d 'access_token=<ACCESS_TOKEN>' \
      'https://graph.facebook.com/<API_VERSION>/<STUDY_OBJECTIVE_ID>?fields=results&ds=2020-03-01'