市场营销 API

提升调研

转化提升成效衡量目前受到限制。请联系您的 Meta 代表，了解有关获取访问权限的信息。

创建并开展试验，衡量 Facebook 广告系列的成效。确定业务成效最好的广告策略。请参阅参考文档 > 广告调研。

创建提升调研时，您可以创建一个随机的测试组（此组账户中心账户能看见您的广告）和对照组（此组账户中心账户不会看见您的广告）。

您可以利用 Facebook Pixel 像素代码或应用事件，安全地与 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

已停用。在 observation_end_time 和 end_time 之间的这段时间内，Facebook 仍会投放广告。如果您使用的是 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 更新为今后的时间，并向测试组添加新的相关对象。

若要在兼顾提升成效衡量的情况下投放覆盖和频次广告，您必须先创建提升调研，并确保覆盖和频次广告的投放期在提升调研的开展期内。

创建测试组

首先，分别确定收到和不会收到您广告的账户中心账户的数量。创建调研时，您必须创建测试组；将 JSON 对象清单传入 ad_studies 下的 cells。请参阅参考文档 > 广告调研单元。测试组应包含以下信息。

参数描述

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 Pixel 像素代码

如果您使用 CONVERSIONS，同时将 Facebook Pixel 像素代码或移动应用作为事件源，则您必须提供想要为对应目标捕获的事件名称清单。然后，Facebook 可以根据这些特定转化事件提供结果报告。

成效衡量数据来源 事件名称

Facebook Pixel 像素代码

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 Pixel 像素代码编号清单，包括每个编号的相关 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”开头的以下字段（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'