마케팅 API
그래프 API 버전

Ad Account Customaudiences

읽기

The custom audiences associated with the ad account.


Note: To retrieve the IDs of lookalike audiences based on your custom audiences, use the lookalike_audience_ids field. See Lookalike Audiences - Managing Audiences for more information.

예

Graph API Explorer
GET /v21.0/act_<AD_ACCOUNT_ID>/customaudiences?fields=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(
    '/act_<AD_ACCOUNT_ID>/customaudiences?fields=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(
    "/act_<AD_ACCOUNT_ID>/customaudiences",
    {
        "fields": "id"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("fields", "id");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/customaudiences",
    params,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
NSDictionary *params = @{
  @"fields": @"id",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/customaudiences"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X GET -G \
  -d 'fields="id"' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences
그래프 API를 사용하는 방법을 알아보려면 그래프 API 사용 가이드를 읽어보세요.

매개변수

매개변수설명
business_id
numeric string or integer

Optional.
This param assists with filters, such as recently used.

fetch_primary_audience
boolean
기본 값: false

fetch_primary_audience

fields
list<string>

Fields to be retrieved. Default behavior is to return only the IDs.

filtering
list<Filter Object>

Filters on the report data. This parameter is an array of filter objects.

field
string

필수
operator
enum {EQUAL, NOT_EQUAL, GREATER_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN, LESS_THAN_OR_EQUAL, IN_RANGE, NOT_IN_RANGE, CONTAIN, NOT_CONTAIN, IN, NOT_IN, STARTS_WITH, ENDS_WITH, ANY, ALL, AFTER, BEFORE, ON_OR_AFTER, ON_OR_BEFORE, NONE, TOP}

필수
value
string

필수
pixel_id
numeric string

Optional.
This param fetches audiences associated to specific pixel.

필드

이 에지로부터 읽는 경우 JSON 형식의 결과를 반환합니다:

{
    "data": [],
    "paging": {}
}

data

CustomAudience 노드 리스트.

paging

페이지 매김에 대한 자세한 정보는 그래프 API 가이드를 확인하세요.

오류 코드

오류설명
100Invalid parameter
80003There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#custom-audience.
190Invalid OAuth 2.0 Access Token
200Permissions error
2500Error parsing graph query

만들기

Your ability to create custom audiences may be limited.

It is expected that you have the same audience capabilities independent of your app's status, which could be in development or live.

To create a custom audience you'll first need to create a blank audience. Then, you'll want to add people to the blank audience you just created by updating the users edge of the audience. You can create a maximum of 500 custom audiences.


다음 경로에서 customaudiences 에지에 POST 요청을 만들 수 있습니다:
이 에지에 게시할 때 a CustomAudience이(가) 생성됩니다.

예

Graph API Explorer
POST /v21.0/act_<AD_ACCOUNT_ID>/customaudiences HTTP/1.1
Host: graph.facebook.com

name=My+new+Custom+Audience&subtype=CUSTOM&description=People+who+purchased+on+my+website&customer_file_source=USER_PROVIDED_ONLY
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/act_<AD_ACCOUNT_ID>/customaudiences',
    array (
      'name' => 'My new Custom Audience',
      'subtype' => 'CUSTOM',
      'description' => 'People who purchased on my website',
      'customer_file_source' => 'USER_PROVIDED_ONLY',
    ),
    '{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(
    "/act_<AD_ACCOUNT_ID>/customaudiences",
    "POST",
    {
        "name": "My new Custom Audience",
        "subtype": "CUSTOM",
        "description": "People who purchased on my website",
        "customer_file_source": "USER_PROVIDED_ONLY"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("name", "My new Custom Audience");
params.putString("subtype", "CUSTOM");
params.putString("description", "People who purchased on my website");
params.putString("customer_file_source", "USER_PROVIDED_ONLY");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/act_<AD_ACCOUNT_ID>/customaudiences",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
NSDictionary *params = @{
  @"name": @"My new Custom Audience",
  @"subtype": @"CUSTOM",
  @"description": @"People who purchased on my website",
  @"customer_file_source": @"USER_PROVIDED_ONLY",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/act_<AD_ACCOUNT_ID>/customaudiences"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
curl -X POST \
  -F 'name="My new Custom Audience"' \
  -F 'subtype="CUSTOM"' \
  -F 'description="People who purchased on my website"' \
  -F 'customer_file_source="USER_PROVIDED_ONLY"' \
  -F 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/act_<AD_ACCOUNT_ID>/customaudiences
그래프 API를 사용하는 방법을 알아보려면 그래프 API 사용 가이드를 읽어보세요.

매개변수

매개변수설명
allowed_domains
list<string>

A list of domains that the audience is restricted to.

claim_objective
enum {AUTOMOTIVE_MODEL, COLLABORATIVE_ADS, HOME_LISTING, MEDIA_TITLE, PRODUCT, TRAVEL, VEHICLE, VEHICLE_OFFER}

Specifies the objective of audiences with CLAIM subtype.

content_type
enum {AUTOMOTIVE_MODEL, DESTINATION, FLIGHT, GENERIC, HOME_LISTING, HOTEL, JOB, LOCAL_SERVICE_BUSINESS, MEDIA_TITLE, OFFLINE_PRODUCT, PRODUCT, VEHICLE, VEHICLE_OFFER}

Specifies a mandatory content type for TRAVEL claim objective.

customer_file_source
enum {USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED}

Source of customer information in the uploaded file.

dataset_id
numeric string or integer

The offline conversion dataset associated with this audience.

description
string

The description for this custom audience

enable_fetch_or_create
boolean

If true, we fetch a custom audience instead of creating one when an identical custom audience already exists. Identical custom audiences must have same name, claim_objective, content_type, event_source_group/event_sources/sliced_event_source_group, inclusions, exclusions and rule.

event_source_group
numeric string or integer

Specifies event source group for TRAVEL claim objective.

event_sources
array<JSON object>

Specifies event sources for TRAVEL claim objective.

id
int64

id

필수
type
enum {APP, OFFLINE_EVENTS, PAGE, PIXEL}

type

필수
facebook_page_id
numeric string or integer

facebook_page_id

is_value_based
boolean

Whether the audience is used to seed a new value based lookalike audience.

list_of_accounts
list<int64>

List of user and page accounts

lookalike_spec
JSON-encoded string

The specification for creating a lookalike audience.

name
string

The name of this custom audience.

opt_out_link
string

Your opt-out URL so people can choose not to be targeted.

origin_audience_id
numeric string or integer

The ID of origin Custom Audience.The origin audience you create must have a minimum size of 100.

pixel_id
numeric string or integer

The pixel associated with this audience

prefill
boolean

You can specify true or false. true includes website traffic recorded prior to the audience creation, and false only includes website traffic beginning at the time of the audience creation.

product_set_id
numeric string or integer

The Product Set to target with this audience

retention_days
int64

Number of days to keep the user in this cluster. You can use any value between 1 and 180 days. Defaults to forever, if not specified.

rule
string

Audience rule to be applied on the referrer URL. Used for website custom audiences, product audiences, and video remarketing audiences.

rule_aggregation
string

Aggregation rule

subscription_info
list<enum {WHATSAPP, MESSENGER}>

subscription_info

subtype
enum {CUSTOM, PRIMARY, WEBSITE, APP, OFFLINE_CONVERSION, CLAIM, MANAGED, PARTNER, VIDEO, LOOKALIKE, ENGAGEMENT, BAG_OF_ACCOUNTS, STUDY_RULE_AUDIENCE, FOX, MEASUREMENT, REGULATED_CATEGORIES_AUDIENCE, BIDDING, SUBSCRIBER_SEGMENT, EXCLUSION, MESSENGER_SUBSCRIBER_LIST}

Type of custom audience, derived from original data source.
Note: COMBINATION subtype is only used by Ads Manager, and is not available through the API.

Number of audiences limit for selected subtype:
CUSTOM: 500
LOOKALIKE: 10000

use_for_products
list<enum {ADS, MARKETING_MESSAGES}>
기본 값: Vec

use_for_products

use_in_campaigns
boolean
기본 값: true

use_in_campaigns

반환 유형

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

오류 코드

오류설명
200Permissions error
100Invalid parameter
2654Failed to create custom audience
2663Terms of service has not been accepted. To accept, go to https://www.facebook.com/customaudiences/app/tos
80003There have been too many calls to this ad-account. Wait a bit and try again. For more info, please refer to https://developers.facebook.com/docs/graph-api/overview/rate-limiting#custom-audience.
190Invalid OAuth 2.0 Access Token
368The action attempted has been deemed abusive or is otherwise disallowed
2667Your account permissions don't allow you to create a custom audience for this event source.

업데이트 중

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

삭제 중

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