마케팅 API
그래프 API 버전

Ad Study

Test your ads and choose the strategy that is driving the most conversions. For example, create a split test to find out which ad set performs the best:

curl \
-F 'name="new study"' \
-F 'description="test creative"' \
-F 'start_time=1435622400' \
-F 'end_time=1436918400' \
-F 'type=SPLIT_TEST' \
-F 'cells=[{name:"Group A",treatment_percentage:50,adsets:[<AD_SET_ID>]},{name:"Group B",treatment_percentage:50,adsets:[<AD_SET_ID>]}]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/ad_studies

Use ad study for these experiments:

Study Type Use Case

Split Testing

Inform near-term optimization decisions. Example: Is Creative A doing better than Creative B?

Conversion Lift

Measure incremental impact of Facebook ads on business outcomes.

Multi-Cell Conversion Lift

Measure incremental impact of different Facebook ads strategies on business outcomes.

Brand Lift Results

Retrieve and analyze your brand lift study results.

See Lift Study for setting up Conversion Lift and Multi-Cell Conversion Lift.

읽기

A lift study object

Examples

To read the details for a study, make a HTTP GET to:

 https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>

To read about the cells in a study:

curl -G \
-d 'fields="name,treatment_percentage,campaigns,adsets,adaccounts"' \
-d 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>/cells


// The response
{
  "data": [
    {
      "id": "<CELL_ID>",
      "name": Group A,
      "treatment_percentage": 50,
      "adsets": {
        "data": [
          {
           "id": "<AD_SET_ID>"
          }
        ],
      }
    },
    {
      "id": "<CELL_ID>",
      "name": Group B,
      "treatment_percentage": 50,
      "adsets": {
        "data": [
          {
            "id": "<AD_SET_ID>"
          }
        ],
      }
    }
  ],
}

예

Graph API Explorer
GET /v21.0/{ad-study-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{ad-study-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{ad-study-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{ad-study-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{ad-study-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
그래프 API를 사용하는 방법을 알아보려면 그래프 API 사용 가이드를 읽어보세요.

매개변수

이 엔드포인트는 매개변수가 없습니다.

필드

필드설명
id
numeric string

ID of the Lift study

기본
business
Business

The business that owns this study if it exists.

canceled_time
datetime

Time stamp when study was canceled

cooldown_start_time
datetime

Cooldown start time

created_by
User

Who Lift study was created by

created_time
datetime

When was the Lift study created

description
string

Description

기본
end_time
datetime

End time

기본
name
string

Name of the Lift study

기본
observation_end_time
datetime

Observation end time

results_first_available_date
string

When results for at least one objective of the study are available

start_time
datetime

Start time

기본
type
string

The type of study, either audience segmentation or lift.

updated_by
User

Updated by

updated_time
datetime

Updated time

에지

Edge설명
cells
Edge<AdStudyCell>

The cells which are part of the objective

objectives
Edge<AdStudyObjective>

The objectives which are part of the objective

오류 코드

오류설명
100Invalid parameter
368The action attempted has been deemed abusive or is otherwise disallowed
200Permissions error

만들기

Requirements

  • treatment_percentage for each cell should be at least 10.
  • The sum of treatment_percentage for all study cells should be less or equal to 100.
  • Each cell must have at least one object associated with it. The object can be adaccounts, campaigns, or adsets.
다음 경로에서 ad_studies 에지에 POST 요청을 만들 수 있습니다:
이 에지에 게시할 때 an AdStudy이(가) 생성됩니다.

매개변수

매개변수설명
cells
list<Object>

Describes the cells in the study.

필수
description
string

id
int64

name
string

creation_template
enum {AUTOMATIC_PLACEMENTS, BRAND_AWARENESS, FACEBOOK, FACEBOOK_AUDIENCE_NETWORK, FACEBOOK_INSTAGRAM, FACEBOOK_NEWS_FEED, FACEBOOK_NEWS_FEED_IN_STREAM_VIDEO, IN_STREAM_VIDEO, INSTAGRAM, MOBILE_OPTIMIZED_VIDEO, PAGE_POST_ENGAGEMENT, REACH, TV_COMMERCIAL, TV_FACEBOOK, VIDEO_VIEW_OPTIMIZATION, LOW_FREQUENCY, MEDIUM_FREQUENCY, HIGH_FREQUENCY}

adaccounts
list<int64>

adsets
list<numeric string or integer>

campaigns
list<numeric string or integer>

control_percentage
float with at most two digits after decimal point

treatment_percentage
float with at most two digits after decimal point

client_business
numeric string or integer

Business associated with the study.

confidence_level
float

Confidence level used in power calculations and final study report.

cooldown_start_time
integer

Start of the pre-measurement cool-down period. This period ends when the study period starts.

description
string

The purpose of the study.

end_time
integer

Time when the study period ends.

필수
name
string

Name of the study.

필수
objectives
list<Object>

A vector of objects describing the objectives assigned to this study.

id
numeric string or integer

is_primary
boolean

name
string

type
enum {SALES, NONSALES, MAE, TELCO, FTL, MAI, PARTNER, BRANDLIFT, BRAND, MPC_CONVERSION, CONVERSIONS}

offsite_datasets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

adspixels
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

customconversions
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

applications
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

offline_conversion_data_sets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

product_sets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

product_catalogs
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

observation_end_time
integer

The end of the observation period for this study. This period starts when the study period ends.

start_time
integer

The time when the study period starts.

필수
type
enum {LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING}

The type of ad study, such as SPLIT_TEST or LIFT.

viewers
list<int>

This study is shared with these people.

반환 유형

이 엔드포인트는 기록 후 읽기를 지원하며 반환 유형에서 id로 표시되는 노드를 읽습니다.
Struct {
id: numeric string,
}

오류 코드

오류설명
100Invalid parameter
다음 경로에서 ad_studies 에지에 POST 요청을 만들 수 있습니다:
이 에지에 게시할 때 an AdStudy이(가) 생성됩니다.

매개변수

매개변수설명
cells
list<Object>

A shape to describe the cells of the study

description
string

id
int64

name
string

creation_template
enum {AUTOMATIC_PLACEMENTS, BRAND_AWARENESS, FACEBOOK, FACEBOOK_AUDIENCE_NETWORK, FACEBOOK_INSTAGRAM, FACEBOOK_NEWS_FEED, FACEBOOK_NEWS_FEED_IN_STREAM_VIDEO, IN_STREAM_VIDEO, INSTAGRAM, MOBILE_OPTIMIZED_VIDEO, PAGE_POST_ENGAGEMENT, REACH, TV_COMMERCIAL, TV_FACEBOOK, VIDEO_VIEW_OPTIMIZATION, LOW_FREQUENCY, MEDIUM_FREQUENCY, HIGH_FREQUENCY}

adaccounts
list<int64>

adsets
list<numeric string or integer>

campaigns
list<numeric string or integer>

control_percentage
float with at most two digits after decimal point

treatment_percentage
float with at most two digits after decimal point

client_business
numeric string or integer

Business associated with study

confidence_level
float

Confidence level used in power calculation and final report

cooldown_start_time
integer

The beginning of the pre measurement cooldown period. This period ends when the study period starts.

description
string

A brief description about the purpose of the study.

end_time
integer

The time when the study period ends.

name
string

The name of the study.

objectives
list<Object>

A vector of objects describing the objectives assigned to this study

id
numeric string or integer

is_primary
boolean

name
string

type
enum {SALES, NONSALES, MAE, TELCO, FTL, MAI, PARTNER, BRANDLIFT, BRAND, MPC_CONVERSION, CONVERSIONS}

offsite_datasets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

adspixels
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

customconversions
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

applications
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

offline_conversion_data_sets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

product_sets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

product_catalogs
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

observation_end_time
integer

The end of the observation period for this study, this period starts when the study period ends.

start_time
integer

The time when the study period starts.

type
enum {LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING}

The type of ad study, either SPLIT_TEST or LIFT.

viewers
list<int>

The list of people who this study has been shared with.

반환 유형

이 엔드포인트는 기록 후 읽기를 지원하며 반환 유형에서 id로 표시되는 노드를 읽습니다.
Struct {
id: numeric string,
cell_ids: List [
numeric string
],
objective_ids: List [
numeric string
],
}

오류 코드

오류설명
200Permissions error
100Invalid parameter

업데이트 중

To update study fields:

curl \
-F 'name="new name"' \
-F 'end_time=1437004800' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>

Add a cell an existing study and change treatment_percentage of all the cells:

curl \
-F 'cells=[{id:<CELL_ID>,treatment_percentage:50},{id:<CELL_ID>,treatment_percentage:10},{name:"Group C",treatment_percentage:20,adsets:[<AD_SET_ID>]}]' \
-F 'access_token=<ACCESS_TOKEN>' \
https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>

Limitations

To update treatment_percentage for a cell, do it at the study level along with other cells. You also make updates to a study to add additional cells to it. You must provide the percentage of all existing and new cells in the study update since they are correlated.

Once the study runs, you cannot update start_time, treatment_percentage for cells. You cannot remove associated objects such as adsets, adaccounts, campaigns. However, you can update end_time to the future time if the study is not yet ended and add new associated objects to the cells if needed.

/{ad_study_id}에 POST 요청을 하여 an AdStudy을(를) 업데이트할 수 있습니다.

매개변수

매개변수설명
cells
list<Object>

A shape to describe the cells of the study

description
string

id
int64

name
string

creation_template
enum {AUTOMATIC_PLACEMENTS, BRAND_AWARENESS, FACEBOOK, FACEBOOK_AUDIENCE_NETWORK, FACEBOOK_INSTAGRAM, FACEBOOK_NEWS_FEED, FACEBOOK_NEWS_FEED_IN_STREAM_VIDEO, IN_STREAM_VIDEO, INSTAGRAM, MOBILE_OPTIMIZED_VIDEO, PAGE_POST_ENGAGEMENT, REACH, TV_COMMERCIAL, TV_FACEBOOK, VIDEO_VIEW_OPTIMIZATION, LOW_FREQUENCY, MEDIUM_FREQUENCY, HIGH_FREQUENCY}

adaccounts
list<int64>

adsets
list<numeric string or integer>

campaigns
list<numeric string or integer>

control_percentage
float with at most two digits after decimal point

treatment_percentage
float with at most two digits after decimal point

client_business
numeric string or integer

Business associated with study

confidence_level
float

Confidence level used in power calculation and final report

cooldown_start_time
integer

The beginning of the pre measurement cooldown period. This period ends when the study period starts.

description
string

A brief description about the purpose of the study.

end_time
integer

The time when the study period ends.

name
string

The name of the study.

objectives
list<Object>

A vector of objects describing the objectives assigned to this study

id
numeric string or integer

is_primary
boolean

name
string

type
enum {SALES, NONSALES, MAE, TELCO, FTL, MAI, PARTNER, BRANDLIFT, BRAND, MPC_CONVERSION, CONVERSIONS}

offsite_datasets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

adspixels
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

customconversions
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

applications
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

offline_conversion_data_sets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

product_sets
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

product_catalogs
list<JSON or object-like arrays>

id
numeric string or integer

필수
event_names
list<string>

observation_end_time
integer

The end of the observation period for this study, this period starts when the study period ends.

start_time
integer

The time when the study period starts.

type
enum {LIFT, SPLIT_TEST, CONTINUOUS_LIFT_CONFIG, GEO_LIFT, BACKEND_AB_TESTING}

A type of the study.

viewers
list<int>

The list of people who this study has been shared with.

반환 유형

이 엔드포인트는 기록 후 읽기 기능을 지원하며 회원님이 게시한 노드를 읽습니다.
Struct {
success: bool,
cell_ids: List [
numeric string
],
objective_ids: List [
numeric string
],
}

오류 코드

오류설명
100Invalid parameter
200Permissions error

삭제 중

To delete a study:

curl -X DELETE
"https://graph.facebook.com/<API_VERSION>/<AD_STUDY_ID>"

이 엔드포인트에서 수행할 수 없는 작업입니다.