行銷 API
返回中文(台灣)
這份文件已更新。
中文(台灣) 的翻譯尚未完成。
英文更新時間：2023年7月21日

指標提升研究

建立並執行實驗來衡量 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% 控制。這會產生 A 組中約 28.6%（亦即 20%/70%）的用戶人口為控制組用戶，而 B 組中約 33.3%（亦即 10%/30%）的用戶人口為控制組用戶。

一般而言，所有測試組的處理和控制組比率的總和應該等於 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

衡量轉換的提升幅度。

以 CAPI 為基礎的 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 日之前開始的研究中。7 月 13 日之後開始的研究將沒有「買家」衡量指標，也不會依性別、年齡和國家／地區進行資料解析。此變更將影響以下以「買家」為開頭的欄位（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'