Marketing API Version

Lift Study

Create and run an experiment to measure your Facebook campaign's efficiency. Determine what ads strategy drives the most business impact. See Ad Study, Reference.

When you create a lift study, you create a randomized test group of people that see your ads and control group who don't see your ads.

You can securely share conversion data from your ad campaign with Facebook using Facebook Pixels, or App Events. Facebook determines the increased conversions generated from your campaign. We compare the number of conversions, people converting, and available sales revenue between test and control groups. Results appear in Ads Manager.

Setting Up Studies

Set up a study with one or more groups, called cells. When you set up your study, Facebook randomizes the audience the audience for your ads and assigns people to either the test or control group. After you run a study, Facebook calculates the difference between the test groups and control groups so that you evaluate the impact of your Facebook ads towards business goals.

To set up a study, make a POST call:

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

You can set up a study with a single test group to see how Facebook ads lead to additional business. You can also set up a study with multiple test groups, which lets you determine what *advertising approach** works best for your audience.

Here is an example of how to set up a lift study with one test group.

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:"MAI",applications:[{id:<APP_ID>}]}]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies

To create a new study, provide the following:

  • name of study.
  • description, or the study's purpose.
  • cooldown_start_time. Start of your pre-campaign quiet period. During this time, Facebook pauses all ads in the study to establish baseline data. We resume running ads once your study period starts. You do not need to establish a baseline for your study, you can set this value to equal start_time.
  • start_time of campaign active period, when ads start running. Study start time must be in the future.
  • end_time of campaign active period, when ads stop running.
  • observation_end_time. End of your post-campaign quiet period which starts when the study period ends. We attribute conversions during this period to your study. Facebook also pauses any ads in the study during this period. If you don't need this quiet period for your study, set equal to end_time.
  • cells in study that define test and control groups.
  • objectives of the study. See Defining Study Objective.
  • viewers. Share this study to a list of Facebook User IDs.
  • type of study. For Conversion Lift, the type should be LIFT.

Once the study starts, you cannot update start_time and treatment_percentage of the cells. You also cannot remove the associated objects, such as adaccounts or campaigns, of the test groups. You can still update the end_time and observation_end_time to a future time if the study has not yet ended and add new associated objects to test groups.

To run Reach and Frequency in conjunction with Lift measurement, you must set up a Lift study first and make sure the duration of the Reach and Frequency is within the duration of the Lift study.

Test Group

Determine how many people recieve your ads and how many people do not. You must create a test group when you set up the study; pass a list of JSON objects in cells under ad_studies. See Ad Study Cell, Reference. A test group contains this information:

  • name of the test group.
  • description of the test group.
  • treatment_percentage defines people who recieve your ads.
  • control_percentage defines a holdout percentage of the people who will not see ads. Treatment plus control percentages must equal 100.
  • List of ad entities, such as adaccounts or campaigns, that you want to study. Facebook runs and measures all ads under active ad entities during the study period.

To read test groups in a study:

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

You can update or modify cell information as well as treatment and control percentages by providing the cell ID in 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>

You can also read all the studies that you created at ad_studies for your business.

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

Multiple Test Groups

Set up a study with multiple test groups of Facebook users. This helps measure incremental impact of different Facebook strategies on business goals, such as using different ads targeting options. To set up a study with multiple test groups, provide a list of test groups in 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:"MAI",applications:[{id:<APP_ID>}]}]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies

control_percentage determines the holdout for each test group respective to the total population. For example, you have a study with two test groups: group A is 50% treatment with 20% control and group B is 20% treament with 10% control. This results in ~28.6%, or 20%/70% of the population in group A, to be control users and ~33.3%, or 10%/30% of the population in group B, to be control users.

The sum of treatment and control percentages across test groups normally should equal 100. However, it can be less than 100 for some specific use cases. For example, when you have three test groups that are split evenly at 33%.

You can update, add, and remove test groups in a study. To update an existing test group, refer to its ID in test group. To add a new test group, provide a new test group object. To remove a test group, simply omit it from cells when you update the study:

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>

Defining Objectives

Define advertising objectives you want to measure and how you pass conversion data to Facebook. A lift study requires at least one objective. You cannot modify objectives after the study starts running. See Ad Study Objective, Reference. For example, create and add the MAI objective to a study:

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:"MAI",applications:[{id:<APP_ID>}]}]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies
NameDescriptionMeasurement Sources

SALES

Measure the lift in purchases. The reporting will contain dollar amount.

Conversion Pixels, Facebook Pixels, and Mobile App.

NONSALES

Measures the lift in non-purchase conversions.

Conversion Pixels, Facebook Pixels, and Mobile App.

MAI

Measure the lift in mobile application installs.

Mobile App

If you use SALES and NONSALES and use Facebook Pixel or Mobile App as event sources, you must provide a list of the event names that you want to capture for the objective. Facebook can then report results based on these speecific conversion events.

Measurement SourceEvent Names

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

Mobile App

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

Create an objective by passing a list of JSON objects objectives when you create a new study. Objectives contain the following information:

  • name of the objective.
  • is_primary, a boolean spcifying if this is your primary advertising objective. A study can only have one primary objective.
  • type of objective: SALES, NONSALES, or MAI.
  • adspixels, list of Facebook Pixel IDs along with the relevant list of event_names per id if applicable.
  • offsitepixels, list of Conversion Pixel IDs if applicable.
  • applications, list of your mobile apps including relevant event_names per id.

You can also have multiple objectives per study. The result will be aggregated based on objectives. Here is an example of a study with multiple objectives—the MAI objective as seen previously and another SALES objective with Facebook Pixel and Application as measurement sources.

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:"MAI objective",is_primary:true,type:"MAI",applications:[{id:<APP_ID1>},{id:<APP_ID2>}]},{name:"SALES objective",type:"SALES",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

You can update, add, and remove objectives in a study by doing so at the study level similar to modifying test groups. To update an existing objective, refer to its ID in the objectives object. To add a new objective, provide a new objective object. To remove an objective, simply omit it from the objectives parameter when you update it.

Here is an example of updating an objective's applications measurement sources and removing its adspixels measurement sources:

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>

To read objectives for a study:

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

Reporting

Not available via API, see Ads Manager. Results appears once there are 50 conversions in a test group and 50 conversions in a control group.